Creating an "Add Item" form
You can create a form that allows users to create new content items by simply calling the following in a controller method:
\IPS\Output::i()->output = \IPS\yourApp\YourModelClass::create( $node );
You must pass the node into which the content item is being created as a parameter (or pass NULL if you are creating content items independent of nodes, or if you will add a form element from which the user can select the node themselves). The create() method will automatically handle showing the form, creating the item, and then redirecting the user to it after creation.
The form elements shown on the form are obtained from the formElements() method inherited by your model from the content item model. You can override this method in your own model to add additional fields that will show on both the create form and edit form. The method automatically adds fields for:
- Item title
- Tags (if your model implements tagging)
- An editor field for the first comment on your item (if commenting is supported by your model and the first comment is required).
If you override the formElements() method, be sure to also call the parent method so that these automatic fields are included.
The names for the form elements are prefixed with the value of the static property $formLangPrefix (which is empty by default, unless overwritten). You can set this property in order to use custom language strings to customize the output of your form.
Lifecycle methods
There are several lifecycle methods that can be overridden to perform actions at certain points of creation.
Before the form is shown, this method is called to determine if the member has permission to create new items. Most permission checking is handled automatically, so usually you do not need to override this method, but if you have the need to perform additional checks they can be done here. For example, the messenger module has a setting that can restrict the number of messages sent per day, so that limit is checked in this method of the messenger models.
-
$member (\IPS\Member, required )
The member whose permissions are being checked -
$container (\IPS\Node\Model, optional)
The container into which the item is going to be created, if appropriate -
$showError (boolean, optional, default FALSE)
By default, this method will return a true/false value. If $showError is TRUE, instead of returning a value, this method will show an error to the user.
This method is called just before the data is inserted into the database, but after the object has been created in memory, and default values such as the author, date and any fields which can be set by virtue of having the same key as a database column have been set. It's important to note this method only runs for new items.
-
$values (array, required)
Array of values from the form.
This method is called immediately after processBeforeCreate (see above). It differs from that method in that it also runs for items being edited. You should use it to set any fields you added in formElements() which are more complicated than just setting the direct value (which would be done automatically). The default method sets the title, tags (if enabled - see Tags section) and other data, so ensure you call the method in the parent class to not override this.
-
$values (array, required)
Array of values from the form.
Called after the content item has been inserted into the database and all processing has been completed, including creating the first comment, if enabled.
-
$comment (\IPS\Comment\Content, required, default NULL)
The object for the first comment, if applicable -
$values (array, required)
Array of values from the form.
Incrementing post counts
By default, when a user posts a new content item, their post count is incremented by one. This might not be desirable depending on the purpose of your application, so by defining an incrementPostCount method on your model, you can control this behavior.
-
$container (\IPS\Node\Model, optional, default NULL)
The container into which the content item is being created, if applicable.
Return true or false from this method to dictate whether the user's post count should be incremented.
Report Document