Website Publisher Module Framework - Interspire

P a g e  | 1   

Website Publisher Module Framework  About This Document  Intended Audience  This document is intended for developers wishing to extend the functionality of Website Publisher through  the creation of modules. It is expected that readers of this document already have an understanding of web  servers,  MySQL,  PHP  and  general  Object  Oriented  programming  techniques,  unit  testing  and  test‐driven  development.  This document will not serve as an introduction to these topics.  Work in Progress  This documentation is currently considered a work in progress. Some sections have not been started or are  incomplete. This draft copy has been published to act as a starting point for module developers and will be  ported to a new Wiki platform we are implementing in the near future to allow for public contributions.  Additionally, some formatting issues exist in this document which will be addressed after conversion to an  online medium. Specifically, code blocks with long lines are currently word wrapped and may cause issues if  pasted directly into PHP files.  Further Discussion  To  discuss  the  Website  Publisher  module  framework,  please  visit  the  Interspire  Website  Publisher  Customization and Integration forum on our website, here:  http://www.interspire.com/forum/forumdisplay.php?f=214 

P a g e  | 2   

Contents  Website Publisher Module Framework ............................................................................................................... 1  About This Document ...................................................................................................................................... 1  Intended Audience ...................................................................................................................................... 1  Work in Progress ......................................................................................................................................... 1  Further Discussion ....................................................................................................................................... 1  Contents .......................................................................................................................................................... 2  Introduction to Modules ................................................................................................................................. 5  What are modules? ..................................................................................................................................... 5  Basic Module Usage .................................................................................................................................... 5  Types of Modules ........................................................................................................................................ 5  Module File Structure ...................................................................................................................................... 7  Typical File Structure ................................................................................................................................... 7  The module.ini File ...................................................................................................................................... 7  The Primary Module Class ........................................................................................................................... 8  The uriPatterns.ini File............................................................................................................................... 10  Language Pack – The language.ini File ...................................................................................................... 10  Step by Step: A Trivial Content Module ........................................................................................................ 12  Module Prerequisite Files .......................................................................................................................... 12  Your Modules Primary Class ...................................................................................................................... 12  Defining a Content Module ....................................................................................................................... 13  Defining Content Module Data Storage .................................................................................................... 13  Adding your Module to the Content Type Editor ...................................................................................... 15  Adding Fields to the Content Editor .......................................................................................................... 15  A Note about Field Names ......................................................................................................................... 16  Content Editor Field Language .................................................................................................................. 16  Validating Module Field Data .................................................................................................................... 17  Testing your Progress ................................................................................................................................ 18  Saving Module Field Data .......................................................................................................................... 18  Loading Module Field Data ........................................................................................................................ 19  Loading Existing Data into Module Field ................................................................................................... 20  Front‐End Output ...................................................................................................................................... 20  Conclusion ................................................................................................................................................. 22  Step by Step: A Trivial Site Module ............................................................................................................... 23 

P a g e  | 3    Module Prerequisite Files .......................................................................................................................... 23  Your Module’s Primary Class ..................................................................................................................... 23  Defining a Site Module .............................................................................................................................. 24  Adding a Layout Block ............................................................................................................................... 24  Testing Your Progress ................................................................................................................................ 25  Front‐End Output ...................................................................................................................................... 26  Conclusion ................................................................................................................................................. 26  Saving and Loading Module Data .................................................................................................................. 27  Using the Module Variables Database Table ............................................................................................. 27  Using a Custom Database Table ................................................................................................................ 28  Using Multiple Database Tables ................................................................................................................ 29  Activation and Deactivation Routines ........................................................................................................... 31  It’s Automatic ............................................................................................................................................ 31  Yet it’s Customizable ................................................................................................................................. 31  Creating a Configuration Screen .................................................................................................................... 33  Does Your Module Have a Configuration Screen? .................................................................................... 33  A Basic Configuration Form ....................................................................................................................... 33  Configuration Language ............................................................................................................................ 34  Saving and Loading Configuration Data .................................................................................................... 35  Default Variable Values ............................................................................................................................. 36  Content Module Functionality ...................................................................................................................... 38  Adding a Custom Field to Content ............................................................................................................. 38  Displaying Custom Data on the Front‐End ................................................................................................ 38  Handling Front‐End Form Submits and AJAX ............................................................................................ 38  Adding to or Altering Front End Content Body Output ............................................................................. 38  Site Module Functionality ............................................................................................................................. 39  Adding to the Control Panel Navigation .................................................................................................... 39  Adding a New Control Panel Section ......................................................................................................... 39  Advanced Layout Block Uses ..................................................................................................................... 39  Giving a Module its Own URL or Page ....................................................................................................... 39  Modules and Website Publishers Event System ........................................................................................... 40  Listening to Existing Events ....................................................................................................................... 40  Creating New Events ................................................................................................................................. 41  Modules and the Template Library ............................................................................................................... 48 

P a g e  | 4    Template Library Scope ............................................................................................................................. 48  Stylesheet (CSS) files .................................................................................................................................. 48  Control Panel Templates ........................................................................................................................... 49  Front End Templates ................................................................................................................................. 49  Modules and the Permission System ............................................................................................................ 51  Defining Site Module Permissions ............................................................................................................. 51  Defining Content Module Permissions ...................................................................................................... 53  Checking for Permissions ........................................................................................................................... 55  Granular Permission Options .................................................................................................................... 57  Permission Options Language ................................................................................................................... 58  Modules and Activity Logging........................................................................................................................ 60  Adding an Activity Log Entry ...................................................................................................................... 60  Language Text for Activity Log Entries ...................................................................................................... 61  Generating Activity Log URLs .................................................................................................................... 62  Reference Information .................................................................................................................................. 64  Module Variables ....................................................................................................................................... 64  Module Functions ...................................................................................................................................... 64  Core Events ................................................................................................................................................ 64  Module Events ........................................................................................................................................... 66  Class References ........................................................................................................................................ 66     

P a g e  | 5   

Introduction to Modules  What are modules?  Modules  are  Website  Publisher’s  programming  interface  to  customizing  or  extending  its  existing  functionality without modifying the core code. This allows the behaviour of Website Publisher to be altered  or improved in ways that, when compared to modifying the core PHP code, are both more organized and  more likely to survive through updates to Website Publisher itself.  Each module is self‐contained in its own directory and can be removed or disabled without affecting the rest  of the system.  As the core of Website Publisher is updated regularly, customizations which are made to the core code can  easily be overwritten by new product versions. Modules on the other hand are mostly unaffected by core  product updates.  Basic Module Usage  For instructions on how to activate, deactivate and configure existing modules, please refer to the Website  Publisher  User  Guide,  which  is  available  as  a  downloadable  PDF  from  our  website  –  www.interspire.com/support  Installing a Module  Modules  provided  with  Website  Publisher  are  already  ‘installed’  and  do  not  need  further  action  to  install  them.  Modules provided by third parties (note: these are not covered by our technical support services) should be  placed  inside  your  Website  Publisher  installation’s  ‘modules’  directory.  Please  refer  to  the  ‘Module  File  Structure’ section further into this document for more information on where module files are located in your  Website Publisher installation.  Once the files for a module are in place, check the module management area in your control panel (Tools >  Modules). The installed module should be visible in the list  Uninstalling a Module  Should the rare case arise that you need to completely remove a module’s files from your installation, this  can be done by first deactivating the module (if it is activated) and then removing the files from the module’s  directory in the Website Publisher installation’s ‘modules’ directory.  Module  database  resources  are  not  automatically  removed  when  a  module  is  deactivated.  This  allows  modules to be re‐activated at a later date. Should you also wish to remove all traces of a module from the  database, please refer to the ‘Storing Module Data’ section further into this document for information about  where a module may be storing its data.  Currently, manually removing module tables from the database is the only way to completely remove all old  module data after a module has been uninstalled.  Types of Modules  Website Publisher modules can be categorized in two ways. A module can be either a ‘content’ module, or a  ‘site’  module,  or  a  combination  of  both.  The  differences  between  the  two  categorizations  are  in  what  functions they serve. 

P a g e  | 6    Content Modules  A  content  module  adds  functionality  to  individual  pieces  of  content.  A  content  module  typically  presents  itself as a field that can be added when a content type is created or edited in the control panel.  Content  modules  may  be  used  to  add  ‘custom  fields’  to  Website  Publisher  content  through  PHP  development.  Most modules provided with Website Publisher are content modules. Examples of content modules that are  provided with Website Publisher are: anchorimage, attachments, contactform, comments...  Site Modules  A site module adds functionality to Website Publisher without being tied to specific pieces of content.  A  site  module  may  present  itself  only  through  its  configuration  screen  in  the  control  panel’s  module  management area, it may add a custom block that can be added to any layout via the control panel, or a site  module  may  also  add  a  whole  new  custom  section  to  the  control  panel.  However,  these  are  optional  –  a  basic site module may work with no configuration or layout options.  By hooking in to the Website Publisher event system, a site module may show its own customized front end  output at nearly any point during the front end display process.  Examples  of  site  modules  that  are  provided  with  Website  Publisher  are:  calendar,  googleanalytics  and  twitter.  Combination Modules  It is entirely possible for a module to implement both content‐ and site‐module‐like functionality.  The  comments  module  provided  with  Website  Publisher  provides  mostly  content  functionality,  but  also  includes some site‐module‐like functionality in that it introduces a new section in the control panel and has  global configuration options. 

P a g e  | 7   

Module File Structure  All files related to modules are located in the /modules/ directory of your Website Publisher installation.  Each module is self‐contained in its own sub‐directory of the /modules/ directory. The individual module’s  directory name must be the same as the module’s codename.  Each  module  has  a  ‘codename’.  This  codename  is  used  throughout  the  framework  for  directory  names,  filenames,  PHP  class  names,  database  tables,  cookie  names,  event  names,  etc.  A  naming  convention  for  module  codenames  must  be  followed  to  avoid  potential  problems  with  invalid  or  clashing  database  table  and class names.  A module may have another, longer display name without character restrictions, but the naming convention  must be followed for codenames.  The following rules apply to module codenames. A module’s codename:  • • • • •

Must be unique among all installed modules.  Must be no longer than 255 characters.  Must  contain  only  alphanumeric  characters  (a‐z,  0‐9)  with  no  whitespace  and  must  begin  with  a  letter.  Should be similar to its full display name.  Should be all lowercase to avoid issues in file and database systems that are case‐insensitive. 

For  example,  if  you  wish  to  create  a  module  called  ‘My  Example  Module’  you  may  want  to  choose  the  codename ‘examplemodule’.  Typical File Structure  A typical module may have the following files:  modules/    examplemodule/      module.examplemodule.php      language.ini      module.ini      images/        field_icon.png      javascript/        examplemodule.js      templates/        styles.css        examplemodule.html 

This  is, of  course, not  the  limit  of  files  a  module  may  include,  but  it  is the  minimum  which  a  module may  require for producing visible results.  The module.ini File  The module.ini file located in a module’s directory contains basic module information. This file mainly exists  to ease the introduction of future automated module update systems. It is easily accessible by other systems  in Website Publisher without having to load the module’s full set of PHP code just to access basic module  information. 

P a g e  | 8    This file follows standard INI file conventions and is parsed using the PHP standard parse_ini_file function.  For  module.ini  examples,  please  see  the  module.ini  files  included  in  any  module  provided  with  Website  Publisher.  AuthorName  The  name  of  the  module’s  author.  Currently,  this  is  not  displayed  anywhere.  This  may  change  in  future  versions of Website Publisher.  AuthorURL  A URL to the author’s website. Currently, this is not displayed anywhere. This may change in future versions  of Website Publisher.  VersionNumber  A numeric version number of the currently installed module.  The version number of a module is displayed in the control panel’s module management area.  Typically this is “1000” to indicate version 1.0.0. Another example value of “1234” would result in a version  number of 1.2.34.  This value exists to ease the introduction of future automated module update systems.  Other values  If  it  is  programmed  to  do  so,  a  module  may  read  this  file  to  obtain  other  arbitrary  information,  but  it  is  recommended  that  other  methods  of  storage  is  used  for  such  information  as  it  is  not  guaranteed  that  module  files  will  be  writeable  by  Website  Publisher.  A  module  developer  should  consider  all  other  value  names in the module.ini file as ‘reserved for future use’. Additional values may be introduced in future as  updates to the module framework require. To avoid clashes with future versions of Website Publisher, avoid  using the module.ini file to store additional information.  The Primary Module Class  Each individual module consists of at least one PHP class, following a set naming convention, based on the  module’s codename.  The module’s primary class must be named ‘iwp_module_{codename}’ and must extend the ‘iwp_module’  class.  The  primary  class  may  directly  extend  other  classes,  but  those  classes  must  at  some  point  extend  the  iwp_module class.  This class file must exist in, or be included by, a file named ‘module.{codename}.php’ located in the module’s  directory.  The following is an example of a skeleton module class. This class does not do anything and will not create a  useable module. It is just the basic requirements for the module’s primary class.  /modules/examplemodule/module.examplemodule.php 

P a g e  | 9