PostNuke

Flexible Content Management System

News

Postnuke Verified Module program

Contributed by on Jul 17, 2002 - 02:22 AM

Question and Answer




Q: What does the term "Verified Module" mean?




A: Basically, the term "Verified" replaces the old term "Official" so now in place of "PostNuke Official Module" the term will be "PostNuke Verified Module".






Q. Is module verification required?




A. No, it is optional. The developer must request verification.






Q: Why the change?




A: The verification process will allow our community an easier way to find quality modules and will ensure compatibility with future releases of PostNuke.






Q: Why use the term "Verified"?




A: The word "Verified" just fits well with the process, of registering your module name, and developing under the API standards that have been set down, again all to ensure that your module will work with all future versions of PostNuke.






Q: Who tests and examines the module?




A: The Modules QA manager and staff administer the verification program.






Q: What do you examine for during the verification process?




A: The <a href=http://centre.ics.uci.edu/~grape/modules.php?op=modload&name=Wiki&file=index&pagename=Verified%20Modules>Verification Standards document describes the standards and it can be found on the Documentation Central site. We've included the current version below.






Q. What will I have to change in my modules?




A. You should not have to make any changes if you followed the PostNuke Modules Developer Guide.






Q: Why would I want my module to be "Verified" by the PostNuke team?




A: We presume that Verified Modules will have broader community acceptance.






Q: Will PostNuke only run with Verified Modules in the future?




A: No. PostNuke recommends Verification for modules, but it does not enforce it. Module authors are free to make their own choice about


verification.






Q: Why does Verification test for design standards?




A: Modules that meet these design standards will allow compatibility with future versions of PostNuke. This means fewer problems in the future and easier upgrades.






Q. Why do we require a Verified Module to be Open Source and reside in the PostNuke Modules CVS?




A. We want to ensure continunity. These criteria allows someone else to support the module in case the original developer departs






Q. Does the verification program include commercial modules?




A. Not at this time. Adding commercial modules will be considered later.








PostNuke Verified Modules Criteria - Version 1.0





Proper Documentation




Documenting your module is a vital step. There are three areas in which your module may need documentation: webmaster, user and code documentation.




The webmaster and user areas are covered by producing manuals and placing them in the appropriate place in the directory hierarchy (below). Webmaster information tells how to install, configure and operate the module. User doeumentation tells the end user how to use the module.




Code is covered by writing a short description of each function, noting the parameters and return values that it has, and placing that at the head of the function. Writing the code documentation in the style of PHPDoc (http://www.phpdoc.de/) will allow for automatic parsing of the documentation by other developers who wish to use your module.




Software Design




The module software will be examined to ensure proper design standards were followed. We look at:




Reserved Variable Names





A number of variables are reserved by PostNuke. These variables must not be duplicated within modules as they will conflict with the PostNuke core and cause unpredictable results. The current list of variables which are reserved can be found in the PostNuke Modules Developer Guide.




Module Directory Structure





A PostNuke module has a very specific directory structure. This allows the PostNuke System to use a generic system to access all modules without needing to know specific information about each separate module that is built. Following the directory structure as laid out below is an absolute requirement of any PostNuke compliant module.




Note: Extra files and directories in addition to these shown below are allowed. Also, if any of the files below are not required (eg. the module does not have database tables of its own so it does not require the pntables.php file) then they do not need to exist. However, files that perform the functions outlined below must comply with the file naming convention to allow the PostNuke system to load the suitable files at the appropriate times to ensure correct operation of the module.




Note: This shows the example layout that a gallery module might have. Other modules will have different names for their top-level directory and blocks as appropriate for their specific functionality.




modules/ [1]


gallery/ [2]


docs/ [3]


credit.txt [4]


install.txt [5]


changelog.txt [6]


licence.txt [7]


pnadmin.php [8]


pnadminapi.php [9]


pnblocks/ [10]


snapshot.php [11]


pnimages/ [12]


admin.jpg [13]


pninit.php [14]


pnlang/ [15]


deu/ [16]


admin.php [17]


init.php [18]


manual.htm [19]


snapahot.php [20]


user.php [21]


eng/ [22]


admin.php [23]


init.php [24]


manual.htm [25]


snapshot.php [26]


user.php [27]


...


pntables.php [28]


pnuser.php [29]


pnuserapi.php [30]


pnversion.php [31]




[1] The top-level directory in PostNuke for modules


[2] The directory that contains all of the module code (in this case the Gallery module is name "gallery"). This directory name must be lower case. You must also register your module name at http://centre.ics.uci.edu/~grape/modules.php?op=modload&name=Wiki&file=index&pagename=ModReg and obtain a module ID number.


[3] The directory that contains all of the module documentation


[4] The file that contains all of the credit information of the module


[5] The file that contains all of the installation instructions of the module


[6] The file that contains all of the changes to the module since the last release


[7] The file that contains all of the license information of the module


[8] The file that contains all administrative GUI function for the module


[9] The file that contains all administrative operational functions for the module


[10] The directory that contains all blocks associated with the module


[11] A file that contains a block associated with this module; in this case it displays a random snapshot from a gallery


[12] The directory that contains all images for the module


[13] The image for the administration icon of the module


[14] The file that contains initialization functions for the module


[15] The directory that contains all language translation files for the module


[16] The directory that contains all German language translation files for the module


[17] The file that contains German language translations for the administrative GUI functions of the module (i.e. pnadmin.php)


[18] The file that contains German language translations for the initialization functions of the module (i.e. pninit.php)


[19] The file that contains the German language translations for the manual for the module


[20] The file that contains the German language translation for the snapshot block


[21] The file that contains German language translations for the user GUI functions of the module (i.e. pnuser.php)


[22] The directory that contains all English language translations files for the module


[23] The file that contains the English language translations for the administrative GUI functions for the module (i.e. pnadmin.php)


[24] The file that contains the English language translations for the initialization functions of the module (i.e. pninit.php)


[25] The file that contains the English translation of the manual for the module


[26] The file that contains the English translations for the snapshot block


[27] The file that contains the English language translations for the user GUI functions of the module (i.e. pnuser.php)


[28] The file that contains all information on database tables for the module


[29] The file that contains all user GUI functions for the module


[30] The file that contains all user operational functions for the module


[31] The file that contains all version and credit information for the module




Use Standard Function Names




There are a number of function names that are considered standard i.e. they have well-known meanings and are used in a number of modules. Using the standard function names makes it easier for other module developers to use your module. See the PostNuke Modules Developers Guide for a complete list.




  • Calls to pnModCallHooks() in all appropriate locations




    Use pnAPI




    pnAPI is the PostNuke Application Programming Interface, a way for modules to interact with the PostNuke core without needing to access tables and internal structures directly. The API also allows for the underlying implementation details of PostNuke to be hidden from a developer so that they can write modules in a standard fashion and not worry about what it might change under the hood. This is very important for a system such as PostNuke which has undergone, and continues to undergo, radical changes in the core design to allow it to be faster, more secure, and more flexible.




    pnAPI is the only supported way of accessing core information. Module developers must use these methods of obtaining information from the PostNuke core system; failure to do so will very likely result in the module not working when the next version of PostNuke is released.




    Output





    All output generated by module functions must be returned to the PostNuke core. No output of any type should be made directly from the module; doing this is not supported and will break in future versions of PostNuke.




  • All output should be parsed through pnVarPrepForDisplay() or pnVarPrepHTMLDisplay()


  • All suitable output censored by pnVarCensor()


  • No echo or print statements used




    Global Variables




    If your package needs to define global variables, their name should start with a single underscore followed by the package name and another underscore.




    Security





  • All operations protected by pnSecAuthAction()


  • All form results protected by pnSecConfirmAuthKey()


  • All form variables obtained by pnVarCleanForInput()


  • All variables in SQL queries protected by pnVarPrepForStore()


  • All variables in filesystem access protected by pnVarPrepForOS()


  • All directories have an empty index.html file present





    Continuity





    The following requirements exist to ensure that Verified Modules can continue even if the original author abandons the module and vanishes.




  • The source code must reside in the PostNuke CVS.


  • Licensed under the terms of the GNU General Public License or another Open Source License.


  • Uses Pear coding standards (http://pear.php.net/manual/en/standards.php)




    Database Usage for Modules




    ADODB database abstraction (a way for PostNuke to support multiple database types such as Oracle, Postgres and ODBC)




  • All fields must be prefixed to prevent problems with reserved words


  • All table names must not be a database reserved word.




    Testing





  • Installs / Uninstalls without problems


  • No obvious bugs


  • No detectable security exposures




    Support




    Module has support from developer(s)




    Commercial Modules





    We've not received any requests to certified commercial modules and will handle them individually. Some criteria (ie: CVS, Open Souce license, etc) may not apply to commercial modules.




  • 2391