Principals, Policies and Standards for Module Development

Have a question or a suggestion about a 3rd party addon module or plugin?
Let us know here.
calguy1000
Support Guru
Support Guru
Posts: 8169
Joined: Tue Oct 19, 2004 6:44 pm
Location: Fernie British Columbia, Canada

Principals, Policies and Standards for Module Development

Post by calguy1000 »

Okay, Here it goes, I know I'm starting a big (HUGE) topic, and possibly a flame war, but after the recent development team meeting we thought it would be a good idea to get everybody's opinions, and then later come to a consensus that could be formed into a document, and implemented into the Skeleton and ModuleMaker modules about the proper, efficient, maintanable, and clean (ahem) techniques and standards used in cmsms module development.

Among (but in no way limiting) the topics of discussion should be:
  • PHP 5 Compatibility
  • Database independance
  • Query Efficiency
  • CMSMS Permissions
  • The proper use and organization of tabs
  • Private vs. Public methods
  • Method name standards
  • Documentation

Here's your opportunity to suggest your coding standards, tips, techniques, and preferences with respect to cmsms module development, and argue for or against them.  All of us module or plugin developers could probably find something to learn from this discussion.  Once this discussion winds down, or at appropriate times we will try to find a consensus, and then implement them in the documentation and sample modules.

So please, post your comments, questions, or suggestions. and let the discussion begin!
Follow me on twitter
Please post system information from "Extensions >> System Information" (there is a bbcode option) on all posts asking for assistance.
--------------------
If you can't bother explaining your problem well, you shouldn't expect much in the way of assistance.
westis

Re: Principals, Policies and Standards for Module Development

Post by westis »

Great, Calguy!!

I'll take a stab at the principles that have more to do with after a module has been created and is about to be released and leave the coding standards to those who know about that. Anyone, please feel free to comment on what you think should be changed!

I’ve given each point a number, for easy reference when people comment on it. But so far they’re not in any particular order. I've written module, but the same goes for tags of course, although they can as of yet not be translated.

[1]
Always test a module thoroughly before it's releaed.

[2]
If there are known bugs or other issues in a release, please write about that in the release notes when uploading a release in the CMSMS Forge. Also write what platforms the module has been tested on and what version of CMSMS. That helps when a user encounter a problem, that may be related to what platform or CMSMS version that they use.

[3]
Use SVN to develop your module. This has many advantages. It can be used for people to test the module before a release. It will appear in the Translation Center, so that translators can translate it to other languages than the natural language of the module before release. And some people only use the SVN versions of modules and do not download the releases.

Do you think we need better guidelines for how to use SVN?

[4]
Do not make a new release every so often if there is not a substantial feature addition or important bug fix. And this is especially important if the new features have not yet been thoroughly tested on as many platforms as possible. Otherwise that may cause people using that module to have to update it very often (or think that they have to) and sometimes a newer version may even break. In the meantime, SVN can be used for these feature additions and testing.

[5]
Do not forget to categorize your module in the CMSMS Forge. See How to create and manage a project

[6]
Encode the file for the natural language of your module in UTF-8! If the natural  language is not English it will otherwise be displayed incorrectly in the Translation Center and for people who use the now-default UTF-8 encoding in the CMSMS Admin Panel.


Ok, those were some thoughts. Anything more to add that doesn't have to do with the actual coding of a module?

Then of course, all you experienced module developers, comment on Calguy's post, so that we can come up with some great guidelines for module development!

;D
calguy1000
Support Guru
Support Guru
Posts: 8169
Joined: Tue Oct 19, 2004 6:44 pm
Location: Fernie British Columbia, Canada

Re: Principals, Policies and Standards for Module Development

Post by calguy1000 »

Okay, I'll be the first to add a few of my development related thoughts, and some of the procedures I (usually) follow, in no particular order

1.  Templates
Any templates that will be presented on the front end (not the admin section) should be stored in the databse, with some reasonable default values attached.  This will allow admins to adjust front end layout without having to edit files.  As well, as I have done in (most of) my modules, there should be a button to reset the template to default values.

The Module API methods I am referring to are:
  • ProcessTemplateFromDatabase
  • SetTemplate
  • GetTemplate
  • DeleteTemplate

2.  Tabs
Tabs should be used to organize the functionality of a module logically, and particularly for template editing, this allows for better permissions management, and improved usability

3.  Permissions
As I've learned over recent weeks, it may not always be necessary to create a new permission for a module, many of the existing permissions work well.  For example, recent modifications to the News Module allows for more modular control, and although it does still add the permission "Modify News" it also uses some of the standard permissions.

"Modify Layout" or some other similar permission is used to determine wether the template tabs should be displayed at all, "Modify News" is strictly used now for adding/editing and deleting news articles, as well the "Modify Site Preferences" permission is used to determine wether the preferences tab is displayed.

As well, the permissions should be checked not only when displaying the form, but also when processing the form results, this increases security one more little bit, and ensures nobody can do anything malicious without actually being logged in.

Conclusion
Does anybody have any suggestions, comments, or questions about these ideas?
Follow me on twitter
Please post system information from "Extensions >> System Information" (there is a bbcode option) on all posts asking for assistance.
--------------------
If you can't bother explaining your problem well, you shouldn't expect much in the way of assistance.
iNSiPiD

Re: Principals, Policies and Standards for Module Development

Post by iNSiPiD »

Having spent the last couple of weeks trying to build my "Positions Vacant" module I think this is a very worthy venture.

I'm sure that the Skeleton module is useful to programmers and those familiar with the API but I don't seem to be getting terribly far with it.

I didn't realise a ModuleMaker module even existed. Where is it, or is it still to come? Couldn't see it in the Forge.

What would be really useful for me is practical code examples of how to do certain things. And if the skeleton module was broken up into more logical parts. Examples inlcude:

- create table samples
- define tabs in admin
- define input fileds in admin
- display ouput for front-end
- integrating pre-existing code

Pah! These probably all sound stoopid but I've got no idea of the larger picture and I'm sure this means I'm recreating the wheel in many cases.
westis

Re: Principals, Policies and Standards for Module Development

Post by westis »

iNSiPiD wrote:I didn't realise a ModuleMaker module even existed. Where is it, or is it still to come? Couldn't see it in the Forge.


One of the news items in the forge is about the initial release of ModuleMaker and takes you directly to the project page. A search for ModuleMaker also brings you directly to the project page. :D


What would be really useful for me is practical code examples of how to do certain things. And if the skeleton module was broken up into more logical parts.


SjG is working on improving Skeleton and ModuleMaker (that automagically, as he puts it, builds a skeleton for a new module using the skeleton module). I'm sure SjG is welcoming feature requests in the tracker for the ModuleMaker project in the forge. There already are some feature requests similar to some of your examples.

Examples inlcude:

- create table samples
- define tabs in admin
- define input fileds in admin
- display ouput for front-end
- integrating pre-existing code


All those are good suggestions! I've also made a couple of tries modifying modules, but got stuck when trying to understand how it all worked, as my PHP skills are not what they should be. With the above examples even people like us could fairly easily make some easy modules! ;D


Pah! These probably all sound stoopid but I've got no idea of the larger picture and I'm sure this means I'm recreating the wheel in many cases.


Not stupid at all, I am glad there are others helping me asking the kind of stoopid questions I keep bugging the developers with on IRC. ;D
Ted
Power Poster
Power Poster
Posts: 3329
Joined: Fri Jun 11, 2004 6:58 pm
Location: Fairless Hills, Pa USA

Re: Principals, Policies and Standards for Module Development

Post by Ted »

This has happened twice now.  Please, please,  please don't include the entire PEAR repository in your module.  If you have a reliance on a PEAR module for your CMSMS module, make a llttle note in your README file on what/how they should install that.  It just becomes unnecessary bloat that and a waste of resources for everyone.

Thanks!
Piratos

Re: Principals, Policies and Standards for Module Development

Post by Piratos »

A standard could look in such a way:

1. Script writing under up to date versions of Apache Mysql Php (e.g. xampp, lampp)
2. Only use of functions, which it least under possible PHP denominator already gave (e.g. 4,3), that would be then the minimum necessary version
3. the CMS must be with the libs (adodb, log4php, smarty, fckeditor) always up to date and not like up to now e.g. adodb version 4.65, 4.66 - and 4.7 is the latest, something similar is current with smarty - there one extracts at present the basis from the authors practically and also morally - one require more of them than the CMS guidance to carry out is ready.
4. Self-test under Windows and Linux
5. Constant publication of the latest version (build).
iNSiPiD

Re: Principals, Policies and Standards for Module Development

Post by iNSiPiD »

Just a note for those who don't sail the bleeding edge: many users (myself included) must work with service providers who dictate when server-side software is updated.

My current ISP, for example, is running PHP 4.2.1, mySQL 3.23.49 and Apache 1.3.26. I sh1t thee not.

Most ISPs are nototriously hesitant to upgrade as soon as new versions are released. We, as end-users for a large organisation, can't do much about that.

One needs to cut a fine line between excluding good people like myself by setting the specs too high,  and losing those people who're dead keen on seeing the latest bells and whistles in new release software.

Just my 2 scrotes.
Piratos

Re: Principals, Policies and Standards for Module Development

Post by Piratos »

xampp, lampp


These are complete apache, mysql,php etc. software editions to develop local. see http://apachefriends.org

At the moment there are four XAMPP versions:

    * a version for Linux systems (tested for Ubuntu, SuSE, RedHat, Mandrake and Debian),
    * a version for Windows 98, NT, 2000, 2003 and XP,
    * a beta version for Solaris SPARC (developed and tested under Solaris 8),
    * and a beta version for Mac OS X.
cyberman

Re: Principals, Policies and Standards for Module Development

Post by cyberman »

Piratos wrote:3. the CMS must be with the libs (adodb, log4php, smarty, fckeditor) always up to date and not like up to now e.g. adodb version 4.65, 4.66 - and 4.7 is the latest, something similar is current with smarty


This will be very important for the future of cmsms I think, so every user can update these by himself.
Last edited by cyberman on Mon Jan 16, 2006 2:42 pm, edited 1 time in total.
badhoy

Re: Principals, Policies and Standards for Module Development

Post by badhoy »

I have not tried my hand at developing a module yet, but have tweaked a couple just to play. 

I'd like to suggest that module dependencies be documented.  Meaning if a module relies on another module document that in the Help or About info.  This will allow CMSMS admins to quickly know all the modules they need to install.
Ryno

Re: Principals, Policies and Standards for Module Development

Post by Ryno »

Calguy since you started this topic with some great ideas, I thought I might reply to your suggestions as I don't have any of my own, plus, I'm not experienced with developing modules.

PHP 5 Compatibility
What sort of guidelines would you document under this section? Is there a nice article about how to write php5 friendly code for php4, or at least a checklist of things you need to be aware of? If so I'd love to read it!

Database independance
Does this mean going another step beyond adodb? Can you please explain in more detail?

Query Efficiency
Once again, if you could please provide some more detail on this that would be great.

I should apologise at this point if I am asking for help on stuff I am expected to know as a web developer? If so, please tell me where to go, i.e, not off a bridge, but to some articles :)

Documentation
I think this is one area that I'd like to see improved. I can count on one had the number of modules I've looked at in the forge that have utilised this section well. I think the required 'About' and 'Help' that are embedded in the module itself are a good starting point but more detail should be available under the project in the forge.

As a general comment, I'm looking forward to this documentation being developed as it is not only valuable in terms of us all coding modules in a consistent way reflecting best practices, but it also makes CMS Made Simple more attractive to Web Development companies who need supporting documentation in order to train staff, instead of having to write their own.

Great stuff everyone!
calguy1000
Support Guru
Support Guru
Posts: 8169
Joined: Tue Oct 19, 2004 6:44 pm
Location: Fernie British Columbia, Canada

Re: Principals, Policies and Standards for Module Development

Post by calguy1000 »

In 0.12 (at least, I can't remember if 0.11.2 had it or not), but the dependencies are now documented automatically in the help page for a module.  And with the forthcoming ModuleRepository and ModuleManager modules, you'll be able to preview the requirements without actually downloading and installing the module.  So we're taking a step forward there.

badhoy wrote:I'd like to suggest that module dependencies be documented. Meaning if a module relies on another module document that in the Help or About info. This will allow CMSMS admins to quickly know all the modules they need to install.
Follow me on twitter
Please post system information from "Extensions >> System Information" (there is a bbcode option) on all posts asking for assistance.
--------------------
If you can't bother explaining your problem well, you shouldn't expect much in the way of assistance.
calguy1000
Support Guru
Support Guru
Posts: 8169
Joined: Tue Oct 19, 2004 6:44 pm
Location: Fernie British Columbia, Canada

Re: Principals, Policies and Standards for Module Development

Post by calguy1000 »

The nice part about the open source community, is that usually, somebody has already written code that illustrates these points somewhere, the hard part is finding it :)

A reasonable, and small example of a module that does most of this (okay, I should document it better) is the HitCounter module

It includes examples of:
  * Creating Tables
  * Tabs in the admin (well, only one tab, but it's there)
  * Input fields in the admin (it's done in the preferences tab)
  * Output in the frontend

iNSiPiD wrote:- create table samples
- define tabs in admin
- define input fileds in admin
- display ouput for front-end
- integrating pre-existing code
Follow me on twitter
Please post system information from "Extensions >> System Information" (there is a bbcode option) on all posts asking for assistance.
--------------------
If you can't bother explaining your problem well, you shouldn't expect much in the way of assistance.
greypanda

Re: Principals, Policies and Standards for Module Development

Post by greypanda »

Although I'm a newcomer to CMSMS, I have been digging deeply into some of the core functions. I agree that getting started on a module can be daunting, and the CMSMS installation "out of the can" has just too many things happening at once.
On my third try, I stripped most of the templates and style sheets out and worked with just the basics. It is very frustrating when you make a tiny little change to a module and then the module won't even install. And the skeleton won't work out of the box on 0.13 now because it depends on events.

I'm anxious to get 1.0betax working, but have stumbled on some major problems when trying to trim the sample content. I'll post my issues once I get my "real work" out of the way.

We have a real struggle ahead since the name of the product says "simple", and it is far too easy to get infected with "rampant featuritis" in short order. So please, let's KISS it!
Locked

Return to “Modules/Add-Ons”