Principals, Policies and Standards for Module Development

greypanda · **Posted:** Tue Sep 05, 2006 6:38 pm

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!

iNSiPiD · **Posted:** Tue Sep 05, 2006 11:12 pm

I look forward to your detailed critique greypanda.

It is true that in an effort to make things as simple as possible for people, they have inadverently become more complicated.

Once the core stabilises (post 1.0) it should make future development that mcuh simpler.

Watch this space.

Ryno · **Posted:** Wed Sep 06, 2006 6:21 am

One thing Drupal have done recently have put a halt on new features and changes to the core for the next two months leading up to their version 5 release. This then gives module developers plenty of time to get everything sorted and compatible before the new version comes out.

Now I'm not suggesting that CMS is doing nothing to help the module breaking problem, or that it's huge issue, I just like that Drupal has made that a prioriity. In keeping CMS Made Simple as simple as possible to me, makes the modules SO important as that's where people get specific with their functionality requirements.

Is it possible for the Skeleton and Module Maker modules to be handed over to the core developers to maintain? I know they've got so much to do already but these modules definitely need to keep up with any changes affecting module development.

I personally stopped looking at developing modules for CMS Made Simple until post version 1 due to these factors, plus I'm not a strong PHP programmer.

aln_cms · **Posted:** Tue Sep 11, 2007 6:02 pm

hi,

I noticed there has been very little talk of Naming Standards within CMS. I have been using CMSMS for about a year now, I've developed / hacked /modifed modules and the customised some stock functionality for my customers. But I am no wiser as to naming standards for methods etc.. than I was when I started.

I think that this kind of chat with help deal with the prolbems such as poor reviews on opensourcemadesimple.org... That reviewer was correct to an extent about the forge. If coding standards were more stringent, I think it would be possible for newcomers to get up to speed more quickly, and have less versioning /dependency errors.

One other thing I have noticed is that in the earlier stages I reinvented the wheel A LOT. I didn't realise that the supporting classes in /lib had so much functionality. However, now that I know it is there doesn't make it any easier to figure out / find -- discover. Maybe some documenation / demos showing the main API functionality of classes such as CMSObject would be nice. (Since I suggested it, I should really stand up and offer to participate in this..... I do)

Alan

webmastertgp · **Joined:** Sun Dec 21, 2008 6:11 am **Posts:** 4

Hi, I think it is a great idea, but I really think you will start with a good and a very good documentation on how to make modules, including all process and access to parts of the modules, databases, external classes, etc.

I actually use php and smarty, but for some unknow reason I don't get my first module works properly.

Good look and I will be spect for details.

gap_tooth_clan · **Posted:** Mon Nov 02, 2009 9:45 am

Hi I have made a few modules for CMSMS, they are usually fairly large and the key focus of the web site, so obviously SEO is of upmost importance. The two things that I think would be awesome for module developers are:

[1] I would like to be able to control page title metadata from the module, with out having to use a template hack.

[2] On several modules I have had to build seperate sitemap components, so is there anyway to include a modules page listings into the sitemap?

I imagine that the first is probably not too difficult, but the second is probably a complete ball ache.

gap_tooth_clan · **Posted:** Mon Nov 02, 2009 10:24 am

Oh yeah, I use a lot of images in my modules, and I am sure everyone else does too. It would be great to have a standard library for uploading and resizing images. I really like phpthumb 2.0

http://phpthumb.gxdlabs.com/

kendo451 · **Posted:** Tue Nov 10, 2009 4:05 pm

CGExtensions has image upload and thumbnails that you can adjust size of.

viebig · **Posted:** Thu Jul 08, 2010 1:39 am

Hello All,

Sorry for my absense last months, I am opening my own company and moving to an office, and I´m not having the time to contribute to this community as I should. I will try to make it up!

PHP 5 Compatibility

I think PHP4 is getting "deprecated", as long I could see, 90% of the servers out there are supporting PHP5, and that acceptance can´t be ignored. If PHP5 offers a better flexibility for your module, I will say: use it.

Database independance

Another interesting point. Likewise PHP5 Compability.. tying the developer to a database module is not a good idea in the pov of flexibilty. But even that way, the debugging capabilities of cmsms should be extended somehow for modules that dont use adodb directly.

Query Efficiency

Flexibity comes with a price: many queries... to improve that at this point ... just by forgeting about legacy support. Tables would need to be changed, please correct me if I´m wrong.

CMSMS Permissions

Well, latest versions of cmsms improved a lot... but we still cant say cmsms is built under a granular permission base. Legacy makes this one harder to improve too...

The proper use and organization of tabs

Hard to say that... I can´t imagine a standard there, since.. modules can be anything .. can have different properties/purposes ..

Private vs. Public methods

Private is always better... if visibility is must.

Method name standards

Reserved names must exist.. eg.. a PHP5 interface definition, a matter of organization

Documentation

What documentation? :> thats a weak point of cmsms... our wiki is way out of something usable.. Its easier to get confused with most documentation cmsms have than getting actual help, thats why our forum is so loved...

I will include a important thing:

Module Skeleton

After all definitions, a updated, full featured module skeleton can make all the difference. When developing modules, my references were always about learning Calguy´s ways to do it, since his modules are coherent. The fact is that right now, all developers do their best with the development tools/documentaion cmsms provides, and that, I belieeb is the reason to this topic existence.

I want to say thank you for all your hard work to make cmsms, one of the best solutions around, and I would like to hear your thoughts about my words.

Regards,

G

jpatti · **Joined:** Mon Jun 28, 2010 1:43 am **Posts:** 41

I don't know what my opinion of writing modules is yet, give me a few months.

Meanwhile...

viebig wrote:

After all definitions, a updated, full featured module skeleton can make all the difference. When developing modules, my references were always about learning Calguy´s ways to do it, since his modules are coherent.

Calguy's modules are also extremely well-documented - when you hit the Help button, you know EXACTLY what to do even if it isn't what his examples do.

If every module was documented the way, for example, CGSimpleSmarty is documented, my life as a user would be so much simpler.

calguy1000 · **Posted:** Sun Jul 11, 2010 4:23 pm

Okay it's time for me to chime in here again...

I've been developing modules and assisting with the core now for a long time, and my opinions have changed over the years, as well a few CMSMS facts have changed.

Module Developer Skill
Just as we assume that the CMSMS user is a professional user, and don't document things that aren't related to CMSMS, we should assume that the module developer is not a 'weekend php coder, weekday auto mechanic'. Therefore we should not make attempts to document things like 'how to use svn' or 'how to code php' or any other such thing that is not specifically related to CMSMS.

Added: Topics like 'how do I do a checkout in svn' etc, can be answered by google. All we need to do is make it easy for people to find the CMSMS specific information.

PHP5
This is a given now, and a standard... we no longer support php4 and I have not been supporting it for even longer than that in my modules. There is a class autoloader already in the core and in CGExtensions to make loading classes automatic, and therefore allows you to split up your code into separate classes much easier.

However, just due to the 'if its not broke why fix it' mentality, there's no reason to go whole heartedly through each module and change it to work only with php5. As time goes by more 'private and protected' keywords will be introduced (I wish php had friend relationships). But in new code, I would suggest using them liberally. I think member variables for a class should ALWAYS be private.

Naming / Coding Standards
I support the idea of an interface class for assisting module develoeprs, however I am not sure if it's going to be as simple as that... as we currently only have one base class (CmsModule) for developing from, and most of the methods there are stubbed so that module developers don't have to override each one unless necessary. There are only a few methods that must be overridden.

I also will not support any strict naming (or for that matter coding styles) rules within CMSMS. Each developer has their own style (and that style changes over time depending upon their needs and experience). As well, even the gnu coding standard has changed over time, and I personally don't like it. As the primary developer on my modules they are written so that I can read them easily.

When I write a module I (try to) write it so that I can maintain it, that includes code documentation. If the formatting and documentation is a benefit or a hindrance to other (potential) developers, that's an afterthought.

If another developer is reading/editing the code they are assumed to be proficient enough to be able to read that code independent of how it is formatted or how the functions are named. I've been working with code for ~20 years now, and have had this 'problem' throughout that time (ever tried to debug integer overflow problems in some electrical engineers hacked together F77 code... I still have nightmares). The best solution is to learn how to read the code. Yes it may be more convenient (for some) to have a strict coding style that they can learn and and then it is quicker to read and understand the code, but it is only a minor aide.

Added note: all attempts should be made when working with somebody elses code to match their coding standards. Don't re-format the whole file for a 3 line patch and expect us to be happy about what you did.

Database Independance
I am of mixed opinions on this. Although in principle I like the idea of being able to work with umpteen different databases (sqlite would be my one of choice), I think now that that should be left to the choice of the module developer, based on his needs. With over 80 modules/plugins that I maintain at this point, I have had only little requests or complaints about compatibility with postgres. Also doing some research have found that less than 10% of websites out there are using postgres, which means that it is potentially alot of effort for a small portion of the market to support that database. So therefore, let the module developer decide based on his need. MySQL support though would be required.

Query Efficiency
This is one of those things where we learn as we go. I regularly go through and improve the efficiency of my queries (as I introduce new features) or add indexes to aid in the queries, etc. and this is because well... when I started with CMSMS I was a relational database noob. Now I know some different things, others will go through the same exercise. Not much we can do about this except for providing feedback to the module developers using the standard mechanisms.

CMSMS Permissions
I'm of mixed opinions about this too. The package is named 'CMS MADE SIMPLE'. to provide a simple mechanism for 80% of the websites we find we produce. Why introduce a complex hierarchical permissions model just to solve the case for 20% (or less) of the sites we need to implement. It doesn't make much sense. There is a flat list of permissions, and each group can have different permissions, and a user can belong to multiple groups... that's about as flexible as we need.

Now we should make an effort (for security purposes) to call CheckPermission() with the appropriate arguments at the top of our admin actions, and at any place where options can be displayed differently for users with different permissions.

Documentation / Skeleton Module
I don't think it's a bad idea to use the Skeleton module as our primary form of communication with the module developer, as a tutorial of sorts (which is what it is). And yes this could be brought into the pervue of the core developers (I don't think that _SjG_ would have a problem with that).

However, when considering documentation also consider that for developer documentation we are aiming at the experienced programmer. Therefore we need a well documented API (we took care of that in 1.

and we need some good examples/tutorials. The developer can then look at those examples/tutorials to figure out how to do things. This largely works... just the skeleton module needs a bit of updating for 1.8 and for php5. There are also alot of other examples out there in the various modules... somebody just needs to ask where they are.

Conclusion:
In conclusion I don't want to put too many 'rules' as to how developers should format their code, name their functions, etc. However we do need to make sure our examples are kept up to date, and that we provide a decent support mechanism for the well asked question from developers on the forum.

Addendum:
There has been debate over time as to whether modules should include stylesheets for their sample templates. I say that they should not. The templates we distribute with our modules are meant to be examples, and a 'getting started' guide for designers. There is no way we can know how somebody will attempt to use the module, or what color scheme, styles, or conventions they are applying. They are free to change any div's or id's in the templates, add new ones, re-arrange the templates at will. Providing stylesheets with the modules is IMnsHO just an added complication to the professional web developer. However, I in no way want to make this a 'rule'. Just my recommendation.

gour · **Posted:** Mon Sep 27, 2010 12:40 pm

calguy1000 wrote:

Database Independance
I am of mixed opinions on this. Although in principle I like the idea of being able to work with umpteen different databases (sqlite would be my one of choice), I think now that that should be left to the choice of the module developer, based on his needs. With over 80 modules/plugins that I maintain at this point, I have had only little requests or complaints about compatibility with postgres. Also doing some research have found that less than 10% of websites out there are using postgres, which means that it is potentially alot of effort for a small portion of the market to support that database. So therefore, let the module developer decide based on his need. MySQL support though would be required.

Although I'm just beginning with PHP at very moderate speed and therefore didn't write any CMS module (yet), imho, it does not make much sense to use Adodb abstraction and then don-t-develop-for-postgres or breaking it by intention.

Silk is also going to use database abstraction, but the question is why bother with another layer when "CMS developer of the year" (author of many significant modules) does not support it?

Quote:

With over 80 modules/plugins that I maintain at this point, I have had only little requests or complaints about compatibility with postgres. Also doing some research have found that less than 10% of websites out there are using postgres, which means that it is potentially alot of effort for a small portion of the market to support that database.

I believe this is the result of two factors:

1) majority of old hostings did not have support for Postgresql, but it was prevalent when MySQL was in better shape than today and today this is certainly not the situation - even cheap hostings are providing Postgresql support
2) by not providing support for it, new users are choosing alternative CMS-es and new devs are recruited from there.

Quote:

So therefore, let the module developer decide based on his need. MySQL support though would be required.

I think just the opposite: following Adodb API and not breaking it by intention should be the policy and if the abstraction is not good-enough, iow, if eg. supporting both MySQL & Postgresql requires too much tweaking on the side of the developer, than new & better ORM should be found and used. (It seems that pdo/adodb are not the only players in the town.) ::)

The current practice is not very reasonable, imho.

Principals, Policies and Standards for Module Development

Who is online