MOD Coding Guidelines

Jérôme · Post by **Jérôme** » Thu 29. Apr 2004, 20:24

MOD Coding Guidelines

So you are a developer and want to provide some great enhancement to the phpwcms community? Great, but how do you that so that everybody can do the best out of it? Here are some guidelines to help you (as a developer) and others (as people who want to install your enhancement) to make the best out of it.

In this area, the terms "Hack", "Enhancement", "Module", etc. are consolidated to the term "MOD" - this is short, easily to remember and does not sound as "dirty" as "Hack".

1. Less changes to the core - easier installation and upgrade

If you develop a MOD, pay attention to the fact that you change the less possible to the core code of the phpwcms system. Why? It makes installation and upgrade much more easy for each upgrade of phpwcms itself. In the future, phpwcms is planned to have a plugin system that does not need any changes to the core - you will then be able to drop a MOD package into the appropriate directory and use the MOD immediately (in the perfect case). Until then: don't change the core because your changes will be overwritten with the next release of phpwcms. It is only hard work for you and those who want to install the MOD - and this each time with each upgrade. Well, now I have repeated myself often enough

.

2. Write easy to read and well documented code

This is an important point for you and the others. You never know if your code is 100% bug free. There could be other MOD developers who want to make use of your MOD to enhance it or to use it as the base for their own MODs. And: if some one wants to remove the MOD from their phpwcms system, it is easier for them to find your code if you show precisely where to find it.

3. Provide clear and easy to applicate installing instructions

Not everybody is such a hardcore professional developer like you are. Some people are even almost not able to do simple find, copy & paste actions. So think of those people when you write the installing instructions. The easiest way is to use the template that follows this paragraph. The instructions are easy to read, understand and applicate. (A post with more complete templates will follow.)

Code: Select all

#
#-----[ OPEN ]------------------------------------------
#


directory/subdirectory/file.php




#
#-----[ FIND ]------------------------------------------
#


unique code passage


#
#-----[ AFTER, ADD / BEFORE, ADD / REPLACE WITH ]------
#


code

4. How should you structure your MODs?

The best way to structure your MOD is to put all your files in a separate folder. It is also a good idea to copy the structure of phpwcms itself for your MOD. There are different areas in which your MOD will have to "do" something. It has to show HTML-code that the users will be able to see - you will certainly want to put those HTML-parts into an inc_tmpl folder. Images should be placed in an img folder, CSS definitions in a inc_css folder, frontend functions into inc_front, localisation files into inc_lang, and so on. Here is an example how the structure of your MOD folder could look like:

Code: Select all

mod_mymod
+--- img
+--- inc_css
+--- inc_front
+--- inc_lang
|  +--- backend
|  |  +--- da
|  |  +--- de
|  |  +--- end
|  |  +--- ...
...
+--- inc_lib
+--- inc_tmpl
main.inc.php

It is also recommended that you use a file called main.inc.php that you will place in to the root folder of your MOD. This will be the main file of your MOD from which all actions and functions of your MOD will be accessed (in the backend). "5. On which places does core code has to be changed?" will explain why this is the case.

5. On which places has core code to be changed?

This will certainly be the most interesting part for MOD developers. At the moment, it is not possible to include a MOD to phpwcms without changing some core code of phpwcms. But it is possible to minimize the changes.

5.1 Language localisation

If you have created the MOD structure as described in Point 4 of this guidelines, it is quite easy to include language localisation to your MOD by simply adding one line to the file phpwcms.php. Change the reference to your language folder according to the name of your MOD (here written in capitals).

Code: Select all

#
#-----[ OPEN ]------------------------------------------
#

phpwcms.php




#
#-----[ FIND ]------------------------------------------
#

include_once ('./include/inc_lang/backend/'.$_SESSION["wcs_user_lang"].'/lang.inc.php');


#
#-----[ AFTER, ADD ]------------------------------------------
# 

include_once ('./include/inc_module/MY_MOD/inc_lang/backend/'.$_SESSION["wcs_user_lang"].'/lang.inc.php');

If you create the language folders (with language files), the users will be able to see the backend area of your MOD in the language they have set in their phpwcms profile. Great, huh?

5.2 Add a menu entry in the MODULES area in the backend of phpwcms

You certainly want to provide some backend interface in which the users will be able to change settings for or see results of your MOD. If you do so, you will have to change some code in phpwcms to show up a menu entry in the MODULES area. You do this by adding code according to the following instructions:

Code: Select all

#
#-----[ OPEN ]------------------------------------------
#

phpwcms.php




#
#-----[ FIND ]------------------------------------------
#

$wcsnav["modules"] = "<strong class=\"navtexta\">".$wcsnav["modules"]."</strong>";


#
#-----[ AFTER, ADD ]------------------------------------------
# 

$subnav .= subnavtext($BL['be_subnav_company_mod'], "phpwcms.php?do=modules&p=MOD_ID", $p, "MOD_ID", 0);

Please notice the terms MOD_ID which are written in capitals in the previous code section. You will have to replace this variable with a number that will be associated with your MOD. Each MOD needs a unique ID. You should have a look in the forums to see which MODs have already been developed and which MOD numbers they have so that you don't have conflicts with those.
See a list of actual MODs that already have been released or are in development in this thread: MOD List and Numbers

5.3 Include the main.inc.php file of your MOD into phpwcms.php

Well, now you have added a menu entry. But this entry points to nowhere if you don't include your main.inc.php which will lead to the content of your MOD.
This passage is a bit tricky. There are two possible situations: either do you (or the user that wants to install your MOD) install your MOD on a clean system that has no other MOD already installed, or you install it on a system that already has a MOD installed.
Change your code according to the following instructions. Again, pay attention to the variables MOD_ID and YOUR_MOD which will depend on the ID and the name of your MOD.

Clean install

Code: Select all

#
#-----[ OPEN ]------------------------------------------
#

phpwcms.php




#
#-----[ FIND ]------------------------------------------
#

		case "modules":	//Modules -> later
						echo 'in preparation - will follow later';
						break;


#
#-----[ REPLACE WITH ]------------------------------------------
#

		case "modules":	//Modules
	   					switch ($p) {
							case MOD_ID: // Description of your MOD
									include_once "./include/inc_module/YOUR_MOD/main.inc.php";
									break;
									
							default: echo '';
									 break;
						}
						break;

- Another MOD is already installed

Code: Select all

#
#-----[ OPEN ]------------------------------------------
#

phpwcms.php




#
#-----[ FIND ]------------------------------------------
#

		case "modules":	//Modules
	   					switch ($p) {


#
#-----[ AFTER, ADD ]------------------------------------------
#

							case MOD_ID: // Description of your MOD
									include_once "./include/inc_module/YOUR_MOD/main.inc.php";
									break;

5.5 Frontend functions

If you want to release a MOD that affects the frontend of phpwcms (e.g. replacement tags or other features visible on your web site), you will have to include the file that contains your frontend functions. You can do so by performing the following actions:

Code: Select all

#
#-----[ OPEN ]------------------------------------------
#

include/inc_front/content.func.inc.php


#
#-----[ FIND ]------------------------------------------
#


?>


#
#-----[ BEFORE, ADD ]------------------------------------------
#

require_once ('./include/inc_module/YOUR_MOD/inc_front/fe.func.inc.php');

This will guarantee that, with every load of a frontend page, your frontend functions will be available. Please be careful: if your MOD causes a problem, the whole website is endangered not to work anymore!

6. How has my main.inc.php has to look like?

If you plan to develop a MOD, I believe you will quickly understand how the following code works:

Code: Select all

<?php

switch($_GET["s"])
{
	case "MOD_FUNCTION_1": // Function 1
			switch($_GET["t"])
			{
				case "MOD_SECTION_1":	// Description
						include_once "inc_tmpl/function1.add.tmpl.php";
						break;
						
				case "MOD_SECTION_2":	// Description
						include_once "inc_tmpl/function1.update.tmpl.php";
						break;
						
				default: // Description
						 include_once "inc_tmpl/function1.default.tmpl.php";
						 break; 
			}
			break;
			
	case "MOD_FUNCTION_2": // Function 1
			switch($_GET["t"])
			{
				case "MOD_SECTION_1":	// Description
						include_once "inc_tmpl/function2.add.tmpl.php";
						break;
						
				case "MOD_SECTION_2":	// Description
						include_once "inc_tmpl/function2.update.tmpl.php";
						break;
						
				default: // Description
						 include_once "inc_tmpl/function2.default.tmpl.php";
						 break; 
			}
			break;
	
	default: // MOD Index Page
			 include_once "inc_tmpl/index.tmpl.php";
			 break;
}

?>

The most effective way to understand the code above is to look at another MOD that has already be done in this way and to look how it performs. If you have looked at how phpwcms works, you have seen that it is always the file phpwcms.php that is called with a whole bunch of parametres added. A typical line could look like this:

Code: Select all

http://localhost/phpwcms/phpwcms.php?do=modules?p=2&s=function&t=add

Your main.inc.php will then go through those so-called GET-parametres and lead to different areas of your MOD according to the values of the single variables.
As said - have a look at finished MODs to see how they look like to better understand how it works.

Well, and now go and begin to provide the community with killer MODs

. But don't forget to provide them with detailed information on how they can apply them.

brans · Post by **brans** » Fri 3. Jun 2005, 08:29

hi visioneer, as these guidelines don't contain the things about frontend_render etc. I'd kindly request you to use the text from the guidelines @ --...-- , which have been updated during the time..

visioneer · Post by **visioneer** » Fri 3. Jun 2005, 08:40

brans wrote:hi visioneer, as these guidelines don't contain the things about frontend_render etc. I'd kindly request you to use the text from the guidelines @ --...-- , which have been updated during the time..

Someone should remove this post. Good thing I haven't started working on my MOD yet. And now that I'm checking out your forum perhaps someone has already tackled my MOD. Just a tip something should be setup to move and/or redirect the phpWCMS hacks forum to yours.

brans · Post by **brans** » Sat 4. Jun 2005, 09:28

No this won't be possible as OG isn't actually very happy with our external forum he wants to keep everything at this central place, this one forum here.

visioneer · Post by **visioneer** » Sat 4. Jun 2005, 09:34

So why then have you setup a new forum for this? Why not leave it hear so everyone can find everything? just my 2 cents

trip · Post by **trip** » Tue 7. Jun 2005, 09:47

dev-brenner-b-e was created to make the mods more easily viewable...
In the present site you loose all the mods as users add more info and questions...
the forum is not competing, its complimenting...
TriP