Jump to content

Developer Documentation

Working with Node models

The base class that your own node classes will extend is \IPS\Node\Model. This class provides a wide range of specialist methods for working with your node data. \IPS\Node\Model in turn extends \IPS\Patterns\ActiveRecord, providing standard ways for fetching and interacting with the underlying data in your database.


namespace IPS\yourApp;

class _ExampleModel extends \IPS\Node\Model

Your model can then be loaded in your controllers like so (see Active Records for more information):

$item = \IPS\yourApp\exampleModel::load( 1 );


Specifying your class properties

Node classes require a few static properties to configure their behavior. Many come from \IPS\Patterns\ActiveRecord.

protected static $multitons = array();

Required. Inherited from \IPS\Patterns\ActiveRecord
Simply needs to be defined by subclasses of \IPS\Patterns\ActiveRecord.


public static $nodeTitle = 'string';

A language string key for a plural word that describes what your nodes are, for example "Forums" or "Categories".


public static $databaseTable = 'string';

Required. Inherited from \IPS\Patterns\ActiveRecord
Specifies the database table that this ActiveRecord maps to.


public static $databaseColumnOrder = 'string';

Should be the column in your database table (without prefix) which contains the position number that nodes will be pulled in order of (the central code will handle setting and using the value, but you have to create a field for it - it should be an INT column).


public static $databasePrefix = 'string';

Optional. Inherited from \IPS\Patterns\ActiveRecord
Specifies the field prefix this table uses.


public static $databaseColumnId = 'string';

Optional (default: 'id'). Inherited from \IPS\Patterns\ActiveRecord.
Specifies the primary key field of this database table.


public static $nodeSortableboolean;

Optional (default: true)
Determines whether nodes will be sortable by administrators in the AdminCP.


public static $modalForms = boolean;

Optional (default: false)
Determines whether forms for adding/editing nodes in the AdminCP will show in a modal popup.


Specifying your class methods

In addition to the methods inherited from \IPS\Patterns\ActiveRecord, the \IPS\Node\Model class also provides additional methods (some of which are required in your own class).

public void url()

Should return an \IPS\Http\Url object pointing to the location on the front-end where users can view the content items in your node.


public void form( \IPS\Helpers\Form $form )

Should define form elements on the $form object that will be used to display a form for adding/editing nodes in the AdminCP.


public static array roots()

Returns an array of nodes. If you implement Parent/Children relationships it will return only those with no parent.


public static array searchstring $column, string $query, string $order=NULL, mixed $where=array() )

Returns an array of nodes that match the search.


public array getButtons( string $url [, boolean $subnode=FALSE] )

Should return an array of buttons to show in the node tree for nodes in the AdminCP. The base class defines the following buttons automatically (based on the configuration of the node model):

  • add
  • edit
  • permissions
  • copy
  • empty
  • delete

You can define additional buttons. Be sure to call parent::getButtons( $url ) in your own class first to set up the default buttons.


Getters & Setters

Because \IPS\Node\Model extends \IPS\Patterns\ActiveRecord, getters and setters can be defined to handle certain properties of nodes. \IPS\Node\Model defines many for you, so you only need to define your own if you need to process fields in different ways. For example, you'll always define a get__title() method, but you'll almost never need to manually define a get__id() method.


Property Description Get Set Default value
$_id Should return the ID number of your node.     The value of the “id” column in the database.
$_title Should return the title of your node.     Empty string
$_description Should return the description of your node, or NULL if not applicable.     NULL
$_badge Can be used to return a badge to show when viewing nodes in ACP. See phpDocs.     NULL
$_icon Can be used to display an icon in the row when viewing nodes in the ACP. Return a CSS class name for the icon.     NULL
$_enabled If implemented, will add an “Enabled” / “Disabled” badge that can be clicked on to toggle status. You should implement this if your nodes have a concept of being enabled/disabled.     NULL
$_locked If you are using $_enabled, this can be used to specify that an individual node cannot be enabled/ disabled and is locked in it’s current status.     NULL
$_position Returns the position of the node.     The value of the column in the database represented by $databaseColumnOrder
$_items The number of content items in the node     NULL
$_comments The number of comments on content items in the node     NULL
$_reviews The number of reviews on content items in the node     NULL


Model forms

When viewing nodes in the AdminCP, IPS4 automatically builds forms to add/edit them. You must therefore define a form method in your model that should build the form elements to show. For example:

public function form( \IPS\Helpers\Form $form )
	$form->add( new \IPS\Helpers\Form\Translatable( 'category_title', NULL, TRUE, array( 'app' => 'yourApp', 'key' => ( $this->id ? "yourApp_category_{$this->id}" : NULL ) ) ) );
	$form->add( new \IPS\Helpers\Form\YesNo( 'category_example', $this->example ) );

This builds a form with two elements - a Translatable field that allows the admin to set a localized title for the node, and a YesNo field for another (imaginary, in this case) property.

Note: consult the form helper documentation for more information on building forms.

When the form is saved, any fields which match columns in the database table will be set automatically. However, you may need to do additional work. In this example, because the title is translatable, it cannot be stored in a specific database column, so we need to store it in the language system. This can be done by overriding the saveForm() method. For example:

public function saveForm( $values )
	// Need to do this as if we’re creating a new node, we
	// won’t have an ID yet and the language system will need one to
	// store the title.
	if ( !$this->id )
	\IPS\Lang::saveCustom( 'yourApp', "yourApp_category_{$this->id}", $values['category_title'] );
  	parent::saveForm( $values );


  Report Document

  • Create New...