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.
<?php 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.
Required.
A language string key for a plural word that describes what your nodes are, for example "Forums" or "Categories".
Required. Inherited from \IPS\Patterns\ActiveRecord.
Specifies the database table that this ActiveRecord maps to.
Required.
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).
Optional. Inherited from \IPS\Patterns\ActiveRecord.
Specifies the field prefix this table uses.
Optional (default: 'id'). Inherited from \IPS\Patterns\ActiveRecord.
Specifies the primary key field of this database table.
Optional (default: true)
Determines whether nodes will be sortable by administrators in the AdminCP.
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).
Required.
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.
Required.
Should define form elements on the $form object that will be used to display a form for adding/editing nodes in the AdminCP.
Returns an array of nodes. If you implement Parent/Children relationships it will return only those with no parent.
Returns an array of nodes that match the search.
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 ) { $this->save(); } \IPS\Lang::saveCustom( 'yourApp', "yourApp_category_{$this->id}", $values['category_title'] ); parent::saveForm( $values ); }
Report Document