In most cases, you'll want to support Admin Restrictions in your model classes because in the IPS Community Suite, this is how site owners control access to various parts of the AdminCP among their staff.
How Admin Restrictions work
Admin Restrictions work by calling methods on your model that represent actions the administrator is taking. The method called in the model will return a boolean indicating whether the admin has permission to perform that action. The supported action methods are:
- canAdd() (i.e. can the admin add new nodes of this type)
- canEdit() (i.e. can the admin edit existing nodes)
- canCopy() (i.e. can the admin duplicate nodes)
- canManagePermissions() (i.e. can the admin edit user permissions for this model)
- canDelete() (i.e. can the admin delete nodes)
The \IPS\Node\Model class defines these methods automatically for you. You'll create the admin restrictions you want to support in the Developer Center, and then map them to these action methods in your model.
Setting up Admin Restrictions
The first step is to use the Developer Center to create the restrictions for your app. Each controller within each module in your app can have separate restrictions. Restrictions are always shown as simple Yes/No fields, so are phrased as a question like "Can _____?". For example, "Can manage forums" or "Can edit feed imports?".
There's a handful of supported permission types that you can implement. They are:
- access (i.e. can the admin access this node at all)
- manage (i.e. can the admin view this node)
- add
- edit
- copy
- permissions
- delete
Note that access and manage do not have associated action methods (i.e. there is no canAccess or canManage method you can use in your model); instead, the Dispatcher will automatically check these permissions, if defined, and prevent access if they are not set to Yes by the site owner.
Add a restriction by clicking the plus icon next to the relevant controller. You'll see a prompt to enter a key, which is how this restriction will be referred to in your code. It'll also form your language string for translating the restriction description, with the language key being r__{key} where {key} is the key you enter in this prompt. It is easiest if you keep restriction naming conventions, and set your key in the format {controller}_{permission}, where {controller} is the relevant controller in your model, and {permission} is one of the types in the list above. For example, in the forums controller for the Forums app, we have:
- forums_manage
- forums_add
- forums_edit
- ...and so on.
Keeping this format makes setting up your model easy. Don't forget to add the relevant language strings to your application's language file.
That's all you need to do in the AdminCP. Next, you'll set up your model.
Configuring your model
To implement the restrictions in your model, you need to add a static property:
There's two required keys you'll need to add to this array:
- app - the key of your application
- module - the module which contains the restrictions you're applying
You'll also need to supply at least one additional key, depending on the kind of behavior you want:
- prefix - if you named your restrictions using our convention, discussed above, you can simply specify the prefix here, and the model will automatically use the correct permissions. For example, if you named your restrictions forums_add etc., the prefix you'd specify for this value would be forums_.
- all - if you want to use a single permission for all of the actions, simply specify it using this value.
-
map - if you want to manually specify which action should check which permission, add a value named map. This should be an associative array with the keys shown below. The value for each key should be the restriction key you created in the developer center that will be checked for that action.
- add
- edit
- copy
- permissions
- delete
Overloading permission methods
Although the base model defines and implements the action methods for you, there may be situations where you need to overload them in your own model class. For example, if we assume our app has a setting that means adding new child nodes makes no sense, we might do:
// app/sources/ExampleModel/ExampleModel.php
function canAdd()
{
if( $this->some_setting )
{
// Can't add nodes if this hypothetical setting is true, so we force FALSE here
return FALSE;
}
// Remember to call the parent method in other cases
return parent::canAdd();
}
Using the permission methods
Most of the time, you won't need to manually use the action methods provided for admin restrictions. The \IPS\Node\Controller class automatically calls them as needed to build the interface, showing appropriate elements according to what the administrator is allowed to do. However, you can call them if needed, like so:
$item = \IPS\forums\Forum::load( 1 ); echo $item->canAdd();
Report Document