Getting Started

Nexus uses a function registration system to establish hooks into the functionality in the Nexus engine.  The plugin will register functions that it wants to be called when particular events occur.  The available events, their purpose, parameters and expected return values are enumerated below.

To create a plugin, create a file with a filename in the following format: plugin.[plugin-name].php and add it to the plugins directory (e.g. [root]/plugins/plugin.myplugin.php).   In that file, register for all the events you will need to handle in order to integrate into Nexus using thenx_register_handler function. 

Step by Step Instructions For Creating and Activating a Plugin

1. Pick a name for the plugin.  For the purposes of these instructions, we'll go with 'reporting'
2. Create folder call 'reporting' in the plugins folder.
3. Inside the folder you created, create a file called plugin.[plugin_name].php - or in our case plugin.reporting.php
4. Create a file called reporting.xml and format it as follows:

   <?xml version="1.0" encoding="utf-8"?>

   <plugin id="[plugin name]" name="[friendly plugin name" author="[author]" version="[version]">

       <description>[any length description]</description>

   </plugin>

5. Log in as a super administrator
6. In the front page, click on 'Manage Plugins'
7. Find the plugin 'Reporting' in the list and click the 'activate' checkbox
8. Click submit

Coding Your Plugin

Now that you have an activated plugin, you can start hooking into various events that occur in Nexus during a user's session.  For a complete list of events see the Events section below.  For the purposes of instruction, we'll say that we want our plugin (Reporting) to add a link to the front panel of a super administrator's login.  Here are the steps you need to follow to make that happen:

1. Add this to the top of your plugin.reporting.php file:
   nx_register_handler('EVENT_FRONTPANEL_LINKS_NEEDED','onFrontPanelLinksNeeded');
   
   
2. Add the onFrontPanelLinksNeeded function:
   function onFrontPanelLinksNeeded($params)
   {
       $currentActionArray = &$params['actions'];
      
       $index = -1;
       foreach ($currentActionArray as $action)
       {       
           $index++;
           if ($action->title == str('STR_OTHER_ACTIONS'))
           {
               break;
           }
       }  
      
       if ($index > -1)
       {
           $currentActionArray[$index]->children[] =
                       new ActionItem(
                           'Reporting',                       
                           '?index.php?a=reporting',                       
                           'plugins/sample/my_image.jpg');       
       }        
   }
   

3. Explanation of what's happening in step 2:

    

   The first thing we do is getting the 'actions' parameter as a reference.  It is this variable that we use as a basis for adding new items to the list.  In this case we want to find the top level 'action' called 'Other Actions' and a link in that grouping.  That's what the first foreach loop is doing.  We get the index into the array for that group then add to the children field of that ActionItem object.

Now if you save this and navigate to the front page you will see the new link in the Other Actions section.

Events 

EVENT_FRONTPANEL_LINKS_NEEDED

Purpose

Event sent when the system needs a compiled list of links that should appear on the current users front panel. 

Params

actions - output parameter - The current array of link items that will be displayed in the front panel.   You can modify this array to change what appears on the front panel Output

None

EVENT_NAV_NEEDED

Purpose

Event sent when the system needs an

Params

vertical - boolean - True if the navigation bar being populated is a veritcal one or a horizontal one.

Output

An array of NavBlock objects.

EVENT_EXECUTE_ACTION_PRE

Purpose

This event is sent just before an action (e.g. mod_cat) is executed. This is very early in the process.

Params

action - string - One of the URLACTION_ constants indicating which action is being executed

id - string/int - The ID associated with the action, if any.

Output

Return true to continue processing the action or false to stop it from continuing.

EVENT_EXECUTE_ACTION_PRE_CONTENT

Purpose

This event is sent after an action (e.g. mod_cat) has been processed but before any content has been rendered.
Params

action - string - One of the URLACTION_ constants indicating which action is being executed

id - string/int - The ID associated with the action, if any.

Output

None

EVENT_EXECUTE_ACTION_POST_CONTENT 

Purpose

This event is sent after an action (e.g. mod_cat) has been processed and after the content has been rendered.
Params

action - string - One of the URLACTION_ constants indicating which action is being executed

id - string/int - The ID associated with the action, if any.

Output

None

EVENT_OBJECT_ADDING

Purpose

This event is sent just before an object of any type is added to the database.  Usually called just after a user has submitted a form for an 'Add' such as 'Add Category' or 'Add Group'

Params

object - The object that is being added (can be of type shCompany, shGroup, shItemDocument, shCategory, etc).
Output

None

EVENT_OBJECT_ADDED

Purpose

This event is sent just after an object of any type was added to the database.  Usually called just after a user has submitted a form for an 'Add' such as 'Add Category' or 'Add Group'

Params

object - The object that has been added (can be of type shCompany, shGroup, shItemDocument, shCategory, etc).
Output

None

EVENT_OBJECT_EDITING

Purpose

This event is sent just before an object of any type is edited in the database.  Usually called just after a user has submitted a form for an 'Edit' such as 'Edit Category' or 'Edit Group'

Params

object - The object that is being edited (can be of type shCompany, shGroup, shItemDocument, shCategory, etc).

Output

None

EVENT_OBJECT_EDITED

Purpose

This event is sent just after an object of any type was edited in the database.  Usually called just after a user has submitted a form for an 'Edit' such as 'Edit Category' or 'Edit Group'

Params

object - The object that has been edited (can be of type shCompany, shGroup, shItemDocument, shCategory, etc).

Output

None

EVENT_DOCUMENT_PREVIEW_NEEDED

Purpose

This event is sent just before a document preview is displayed.  Fill the 'content' parameter with your own preview code to customize the preview.  Use the 'doc' to determine the type and location of the file.

Params

doc - The document object.  Use this to get the document type and other information about the document.

content - Populate the content to display in the preview area.  Leave as is to use the default preview.

Output

None