Overview

An ActiveWAFL Functional Model is a middle-tier class that implements any of the application's logic that applies to the data that the model represents.

In database-first development, ActiveWORM automatically generates the stubs for all of the Functional Models. Controllers can load, persist, and delete Functional Models to/from a a data Storage Engine using methods provided by the Functional Model's underlying Data Model.

Functional Model files are normally in the AppNamespace/Models/FunctionalModel folder.

Loading Functional Models

From a Database

To load a set of Functional Models prepopulated with underlying Data Models from a data source, use the Filter or FilterFirst utility method on the desired Functional Model's class.
If you know the unique id of the model, you can instead simply instantiate the Functional Model with the unique id as the first argument.

On the server side

FunctionalModel::Filter Signature
  1. static Model[] ModelName::Filter(string $filter, [string $orderByFieldName=null, int $maxRecordCount=null, string $groupingField=null, array $joinObjects=null, int $startOffset=0, string $arrayKeyField=null])
FunctionalModel::FilterFirst Signature
  1. static Model ModelName::FilterFirst(string $filter, [string $orderByFieldName=null, string $groupingField=null, array $joinObjects=null, int $startOffset=0, string $arrayKeyField=null])
Example: Load an array of Functional Models for products with "Waffle" in their title
  1. $products = \AppNamespace\FunctionalModels\Product::Filter("Title like '%waffle%'", "DateAdded desc, 100);
Example: Use an inner-join on ProductSales.ProductId = Products.ProductId to load an array of Functional Models for products with "Waffle" in their title and that are also on sale.
  1. $products = \AppNamespace\FunctionalModels\Product::Filter("Title like '%waffle%'", "DateAdded desc, 100, $groupingField, $joinObjects, $startOffset, ["ProductSales"=>"ProductId"]);
FunctionalModel Constructor Signature
  1. new ModelName([String $keyValue=null, Array $objectData=null, StorageEngine $storageEngine=null, String $dataGroup=null])
Example: Load a Functional Model for an existing product by it's unique id (primary key).
  1. $product = new \AppNamespace\FunctionalModels\Product($productId);

On the client side

Example: Load a Functional Model for an existing product by it's unique id (primary key).
  1. var product = DblEj.Data.Model.LoadInstanceFromKey("Product", productId);

See the DblEj docs for the IFilterable::Filter() method for more details.

Persist a new Functional Model

You can add data to a database by using Functional Models' underlying Data Models on either the server or client side.

Server Side

Example: Create a new product and save it to the database.
  1. $newProduct = new \AppNamespace\FunctionalModels\Product();
  2. $newProduct->Set_Title("My New Product");
  3. $newProduct->Set_Description("A really awesome product");
  4. $newProduct->Set_Price(59.95);
  5. $newProduct->Save();
  6.  
  7. $newProductId = $newProduct->Get_ProductId();
Example: Load an existing product, change it's price, and save it to the database.
  1. $product = new \AppNamespace\FunctionalModels\Product($existingProductId);
  2. $product->Set_Price(32.50);
  3. $product->Save();

Client Side

Example: Create a new product and save it to the database.
  1. newProduct = new AppNamespace.FunctionalModels.Product();
  2. newProduct.Set_Title("My New Product");
  3. newProduct.Set_Description("A really awesome product");
  4. newProduct.Set_Price(59.95);
  5. newProduct.SaveToServer();
  6.  
  7. newProductId = $newProduct->Get_ProductId();
Example: Load an existing product, change the price, and save it to the database.
  1. product = DblEj.Data.Model.LoadInstanceFromKey("Product",existingProductId);
  2. product.Set_Title("My Renamed New Product");
  3. product.Set_Price(32.50);
  4. product.SaveToServer();

Application Logic

When logic is derived from, applies to, and/or affects any data in a Data Model, then the code for that logic should be live in a Functional Model.

Functional Model stubs are created automatically by ActiveWAFL and they inherit some behavior from the underlying Data Models.
You will add the appropriate functionality for your application.
Example: Functional Model that represents a row from the hypothetical Employees table
  1. namespace MyAppNamespace\FunctionalModel;
  2. class Employee extends \MyAppNamespace\DataModel\Employee
  3. {
  4.    public function GivePromotion($effectiveDate,$newTitle,$newSalary=null)
  5.    {
  6.       //if they didn't pass in the new salary, then give our standard 5% raise
  7.       if (!$newSalary)
  8.       {
  9.          $newSalary = $this->_salary + ($this->_salary*.05);
  10.       }
  11.  
  12.       //update employee's current title and salary
  13.       $this->_title = $newTitle;
  14.       $this->_salary = $newSalary;
  15.  
  16.       //create a promotion object to represent this event
  17.       $promotion = new EmployeePromotion();
  18.       $promotion->Set_EffectiveDate(effectiveDate);
  19.       $promotion->Set_EmployeeId($this->_employeeId);
  20.       $promotion->Set_Title($newTitle);
  21.       $promotion->Set_Salary($newSalary);
  22.  
  23.       return $promotion;
  24.    }
  25. }
Example: An action in the EmployeeDetails Controller that gives an employee a promotion using the Employee Functional Model. Occurs when the supervisor submits a form on the Employee Details page.
  1. namespace MyAppNamespace\Controllers;
  2.  
  3. use DblEj\Application\IMvcWebApplication;
  4. use DblEj\Communication\Http\Request;
  5. use DblEj\Mvc\ControllerBase;
  6. use MyAppNamespace\FunctionalModel\Employee;
  7. use DblEj\Data\ArrayModel
  8.  
  9. class EmployeeDetails extends ControllerBase
  10. {
  11.    public function PromoteEmployee(Request $request, IMvcWebApplication $app) {
  12.       $employee = new Employee($request->GetInputInteger("EmployeeId", Request::INPUT_POST));
  13.       $promotion = $employee->GivePromotion(time(),"IT Manager");
  14.       $employee->Save();
  15.       $promotion->Save();
  16.       return $this->createResponseFromRequest(
  17.          $request, $app,
  18.          new ArrayModel(["EMPLOYEE"=>$employee,"PROMOTION"=>$promotion])
  19.       );
  20.    }
  21. }