Creating Custom Pluslets

Planning your pluslet

First of all, you should decide on your requirements. In this process, you might want to ask yourself the following questions:

• What tasks will staff users need to complete in your pluslet?
• What tasks will public users need to complete in your pluslet?

You should also consider whether you would like to show different views of your pluslet in various contexts. Some questions that can be helpful:

• Will staff users need an interface to edit this pluslet?
• Will the non-editing interface of the pluslet be different for staff users and public users? This can be fruitful for things like an accessibility or data integrity checker -- you would want the results of the check to display to staff users so that they can make corrections, but not to public users.

Creating a basic pluslet

First of all, decide on a type name for your pluslet. The main restriction is that this name can't have spaces. To follow the naming convention, it should start with a capital letter. For the purpose of this documentation, we'll name our pluslet type "BestPluslet".

Creating the pluslet class

Create a file in lib/SubjectsPlus/Control/Pluslet with the name of your pluslet type and the extension .php. In our example, we will create lib/SubjectsPlus/Control/Pluslet/BestPluslet.php.

In this new file, you need to create a class with a name that starts with Pluslet_ and ends with your pluslet type. In our example, that would be Pluslet_BestPluslet.

In this new file, you need the following public methods:

• __construct -- this is where you can set lots of defaults. For example you can set a default title for your pluslet using $this->_title. You must set $this->_type to be your pluslet type string. In our example, you would write: $this->_type = "BestPluslet";
• getMenuName should return the user-facing name of your pluslet. Try to make this name unique.
• getMenuIcon should return a string including a [http://fontawesome.io/icons/ fontawesome icon] and a span including the staff-facing name of the pluslet (probably a static function)
• onViewOutput will return the string for the view version of the box. (you can check to see if the url contains /control/ if you want the staff non-editing version to be different)
• onEditOutput returns a string for the editing version of the box.

If you want boxes to be configurable/editable by individual staff users, you'll want to put those data into $this->_extra in the json format To save content from forms in the edit view, make sure the name of the attribute is in the format Typename-extra-Nameofattr (in our example, BestPluslet-extra-LibrariansText).

Add your pluslet type to the admin configuration page

Add your pluslet type to the pluslets_activated array in the edit-config.php file. This way the pluslet can be activated/deactivated by admin users from the GUI interface.

Make your pluslet clone-able

Add your pluslet to the switch-case in the getPlusletCloneBody function located in the Clone.php file.

Organizing your pluslet files

You can add some optional files:

• assets/js/guides/BestPluslet.js
• assets/js/guides/guideSetup.js (just to add some setupFunctions)
• lib/SubjectsPlus/Control/Pluslet/views/BestPlusletView.php -- to separate the view logic/HTML from the basic guts of the pluslet
• subjects/guide.php (just to include that JS file)

Providing global configuration options

You will want to configure some pluslets so that they behave the same across your entire site. To do this, you will need to modify three files:

• lib/SubjectsPlus/Control/Pluslet/BestPluslet.php will need to look for the global variable and handle cases in which that variable is empty.
• control/includes/config.php should be updated with the value you want.
• control/edit-config.php should be updated in order to give admin users the ability to change this configuration.