Dashboard > RAIV > ... > Explanations > Module system > Information > Page Comparison
RAIV Log In   View a printable version of the current page.
Module system
Browse Space    
Version 10 by Oskar Stephens
on Dec 10, 2007 15:05.

<< Changes from 9 to 10
compared with
Current by Oskar Stephens
on Dec 10, 2007 15:08.
(show comment)
 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 3 changes. View first change.

 h2. Introduction
  
 The RAIV module system is similar in design to Wordpress modules.&nbsp; If you have ever developed a module for it or Maintain, you will see some very familiar things going on here in RAIV.&nbsp; The general idea is that modules may register filters and actions to hooks.&nbsp; Later, when a call is made to applyFilter or doAction respectively, The appropriate function in the module will be called.&nbsp; In this document, we will cover module writing 101, how module's are installed/enabled/disabled, and how a module's function is invoked by RAIV.
  
 h2. Module Writing 101 - So you want to be a RAIVer
  
 If you were looking for how to write a module, look no further\!&nbsp; This section will introduce you to the basics of module writing.&nbsp;
  
 h3. Terms to Know
  
 * Module Package (Pack for short) - A collection of modules that are contained in the same folder in the module directory.&nbsp; These modules are closely related.
 * Parent Module - The main module in a module package.&nbsp; The main module is easily identified as it must share its name with the containing directory.
 * Child Module (Also referred to as a Sub-module) - All modules in a module package that isn't the main module.
 * Hook - A hook is in RAIV is a point at which a module action may take place.&nbsp; Hooks have names (to differentiate function) and come in two varieties, actions and filters.
 ** Action - An action is a hook from which data is generated.
 ** Filter - A filter is a hook which modifies existing data.
 * Type - Modules define which types they lay claim to.&nbsp; These are used as a representation of what data they will track.&nbsp; (eg., If a module adds support for inventorying canned foods it would probably choose to register a type such as "canned food" or "canned good")
 * Permissions - The permissions that the module wishes to register to the role based permission scheme.
 * Map table - Raiv_Map is the centralized mapping table in RAIV and is implemented to help module writers avoid having to write their own.&nbsp; (Useful if your module has a bunch of sub-modules)
 * Priority - A module registers to a hook with a priority which determines the order of execution.
  
 h3. Important Functions
  
 * \_install() - This method is your install method that you can freely overload to perform any actions that need to be taken on module installation.&nbsp; It should return true on success and false on failure.
 * \_uninstall() - Exact same as the install function, but for the opposite purpose.
 * registerHooks() - The function that is called in order to register which filters and actions a function responds to.
 * Module::doAction() - This function is used to invoke a specific action.&nbsp;&nbsp; Any and every module registered to it will run.
 ** Module::doSingleAction - This function is used to invoke a specific action from a specific module.&nbsp; Only the specified module will run.
 * Module::applyFilter() - This function is used to invoke a filter.&nbsp; Any and every module registered to it will run.
  
 h3. Conventions
  
 * Modules are self contained in a directory.&nbsp; They are not supposed to install files anywhere else in RAIV.
 * Sub-modules should be prefaced with their parent's name.&nbsp; Parent, Parent_Sub.&nbsp; This is to make it obvious in case a module has an overlapping name with another module.
 * Tables in the database should be prefaced with the module package name.&nbsp; Raiv_CRM, Raiv_CRM_Person. Raiv_CRM_Email.
  
 h3. Hooks and You
  
 The key to the entire module system lies in the hook system.&nbsp; These hooks are what allow modules to not only interact with RAIV, but to allow other modules to interact with each other.&nbsp; Hooks are not stored in a central repository anywhere in the system.&nbsp; There is, however, a list of hooks modules have registered to.&nbsp; It is completely legal that a hook could have nothing registered to it.&nbsp; It is also fine if a module registers to a hook that is never called (though the function registered to that hook would never get called).&nbsp; Creating a hook is as simple as calling for its execution.&nbsp; This is achieved through the use of the applyFilter and doAction methods.&nbsp; For example:
 {code}
 Module::doAction('some_action');
 {code}
 Or, if it were a filter:
 {code}
 Module::applyFilter('some_filter', $object);
 {code}
 As can be seen, the signatures of these functions is slightly different.&nbsp; Both functions take an arbitrary number of arguments in order to be able to take advantage of pertinent information and to pass it on to the responding modules.&nbsp; The applyFilter requires the first parameter after the filter name to be the object that will be "filtered."&nbsp; As per the definition in the Terms to Know section, a filter modifies data.
  
 Module writers can, and are actively encouraged, to use filters to improve the flexibility and extensibility of their modules.&nbsp; It can allow other modules to add functionality to your code base, as well as allow ease of development for yourself later on.
  
 h4. How do I answer to a hook?
  
 Making your module respond to a specific hook is exceedingly easy, you just need to use the registerHooks method to tell RAIV what hooks you want to answer to, and with what function.&nbsp; This method is abstract and absolutely MUST be overloaded.
 {code}
 public function registerHooks()
 {
  Module::addAction('some_action',array(get_class($this),'some_method'));
  Module::addAction('some_action2',array(get_class($this),'some_method2'), 42);
 }
 {code}
 The calls to addFilter are the exact same, just with a different function name.&nbsp; The way this function is written right now, this module will respond to the actions "some_action" and "some_action2".&nbsp; It will respond using $this->some_method and $this->some_method2 respectively.&nbsp; The second call also has the optional third parameter, priority.&nbsp; Priority is a range on a scale from 1 to 100.&nbsp; 100 meaning it will be the first module executed and 1 meaning it will be the last.&nbsp; In the event of a tie, the modules are executed alphabetically.&nbsp; If this parameter isn't specified, a default priority of 10 will be assigned.
  
 _Note:&nbsp; The reason that an array needs to be the second parameter is because addAction and addFilter are called statically.&nbsp; Because of this, there really is no way to tell short of a stack trace who made the call._
  
 h4. &nbsp;What hooks are there?
  
 There is a list of currently defined hooks available [here|Currently Defined Hooks].&nbsp; There is also the possibility of creating your own hooks.&nbsp; This is particularly useful when you want to make it so a module can add data to something you've already done.&nbsp; Anything that is a separate module can also be enabled and disabled (without being uninstalled) by a user with the appropriate permissions.&nbsp; This can be handy if you have parts of your module that other people may not necessarily need, or may need at a later time.
  
 h3. &nbsp;Types, Mapping, and Permissions... Oh my\!
  
 In RAIV modules modules also typically register their types and their permissions to be made a part of the mapping table and to be facilitated into the role based permission scheme.&nbsp; Both of these are accomplished by overloading a simple array held by each module.&nbsp; The module installer will take care of entering them into the database and such.&nbsp; These arrays for types and permissions are $_types and $perms respectively. Permissions are inheritance based, so define all permissions for your module in the parent module and any special cases in the corresponding sub-module.
  
 {code}
 public class AModule extends Module
 {
  public $_types = array('Type1','Type2');
  public $_perms = array('Modify_Type1','Modify_Type2','Read_Type1','Read_Type2');
  //...rest of class definition
 }
 {code}
 The entries in the above code will case Type1 and Type2 to be inserted into the type table and the permissions will be entered into the permissions table to be assigned to roles.
  
 h4. &nbsp;A Different Type of Purpose
  
 The types are pretty much exclusively used by the raiv_map table, however it isn't taboo to look things up in it if needed.&nbsp; There is a relatively complete write up on how mapping and types work in the RAIV sense [here|RAIV mapping table].&nbsp;
  
 h4. &nbsp;The Dos and Don'ts of Permissions
  
The permissions RAIV are entered into the permissions table to be retrieved and used later to be assigned to roles.&nbsp; Modules are responsible for their own permission checking.&nbsp; Currently, RAIV does not have this facility, but it is planned for addition in a few months time.&nbsp; Because of this, it is considered good practice at this point to include it for the sake of future planning and completeness.
  The permissions are entered into the permissions table to be retrieved and used later to be assigned to roles.&nbsp; Modules are responsible for their own permission checking.&nbsp;
  
  
 h3. Helping Your Module(s) Talk to Each Other
  
  
 h4. Making Your Own Hooks
  
 As has been mentioned before, the module system allows the hooks to be completely arbitrary and, as a result, you'll be able to allow other modules to add to your work, as well as adding to the work of others through module writer's own hooks.&nbsp; These hooks can be used at your discretion.&nbsp; For the sake of not overlapping with someone else's hooks, it's recommended that the hooks be prefixed with your module's name (though this is not a requirement).
  
 h4. &nbsp;Accessing Data From Other Sources
  
 &nbsp;RAIV's default modules are all about breaking things out into sub-modules.&nbsp; Even if you don't follow this convention, you'll need to learn the magic of the [raiv_map|RAIV mapping table] table in order to access data in other modules.&nbsp; Since this is like a centralized mapping table for all of your relationship needs between tables you'll be able to utilize it to link yourself to the information of a parent object, or to find a specific detail of an object that is on a submodule.
Site powered by a free Open Source Project / Non-profit License (more) of Confluence - the Enterprise wiki.
Learn more or evaluate Confluence for your organisation.
Powered by Atlassian Confluence, the Enterprise Wiki. (Version: 2.2.7 Build:#524 Jul 28, 2006) - Bug/feature request - Contact Administrators