webCOMAND

io_comand_repo\models (COMAND Models)

A COMAND Model is a PHP class used for COMAND repository objects of a specific content type when they are accessed in PHP code.  In other words, when an object in the repository is accessed in PHP, the PHP object will be an instance of the model (PHP class), providing all of the model's methods (and the methods of models it extends), in addition to the content type fields as object properties.

If a model is not associated with an object's content type, the model associated with the content type it extends will be used, and so on, potentially up to the Content or cObject model.

The core COMAND models, organized by inheritance hierarchy, are:

Variables & Methods

A model is ultimately just a PHP class, so the model can define any number of public, private and protected variables and methods.  However, there are a few considerations when adding variables and methods to models.

Variables

Public variables will take precedence over Content Type fields.  It is a best practice not to define public variables at all.  Instead define access methods to get internal values that are not defined as content type fields.

Methods

The following methods are defined in cObject, but may be overridden in a model to alter the default behavior for a specific content type.

  • approve() - Called when an object should be approved.  Return FALSE to fail.
  • save() - Called when an object should be saved.  Return FALSE to fail.
  • store() - Called when an object should be stored.  Return FALSE to fail.
  • validate() - Called when an object should be validated, most typically when an object is saved or approved, but notably not when it is stored.  Log an error to fail.  Return FALSE to short-circuit subsequent validation processes (this is the first).  method__validate() is a more elegant way to augment validation of a content type, rather than completely overriding the default behavior.

Hooks

The following hooks (aka hooking methods) are not already defined, but if defined in a model, they will be recognized by the API to augment default behaviors.

  • method__description() - Returns a string to be used for the object description, which displays below the object title in List View.
  • method__icon() - Returns an image (actual data, not a filename) to represent the object.  The icon image will be cached by the API automatically.
  • method__key() - Returns a string to be used as the object key.
  • method__keywords() - Returns a string of space-separated keywords to match on when an API, CMS or query MATCH() search is performed.
  • method__new() - Called when a new object is created to set one or more object field values to defaults.
  • method__summary() - Returns a string to be used for the object title, which is returned by the object __toString() method and displayed in List View and throughout Content Manager and other apps.
  • method__validate() - May log events and return TRUE to indicate the object is valid and can be saved or approved, or FALSE to indicate the object is not valid and can not be saved or approved.  Can also be used to modify field values before they are saved or approved, to trim whitespace, produce image thumbnails, etc.
  • method__* - All public methods that start with "method__" can be called from cScript and cTemplate.
For more information about these methods, see cTemplate Methods.

cScript Accessible Methods

Content Type methods can be accessed from cScript code.  Content Type Methods can be defined as Templates within the repository and written with cScript.  However, it is often advantageous to define methods in PHP.  Any PHP methods in the model with a name that starts with method__ will become available in cScript and can be accessed from cScript the same way a Content Type Template is accessed (see #INSERT).

Example

A basic model looks like this.

<?php
namespace com_example\models;

// The class name must match the Content Type Identifier.
class Example extends \comand\models\Content {

    // this method can be called from PHP code, but not cScript code
    public function example(){
    }

    // this method can be called from cScript code
    public function method__example(){
    } 

    // this method will override the New behavior,
    // including a New template if defined
    public function method__new(){
    }
}