Modules Development

Modules development is really quite simple once you know how to program the basics in PHP. The module code is as simple or as complex as you want to make it.

Getting Started:

Every module must reside in subdirectory in the modules directory, (so in /modules/module_name for example) and the main file of that module must be called index.php.

After you've created this index.php file, the basic development is virtually the same as any PHP page you create. The beginning of a module might look like this:

<?php

/**********************/
/* Your credits go here     */
/**********************/

if(!eregi("modules.php", $_SERVER['PHP_SELF'])){
     die("You can't access this file directly...");
}

$module_name = basename(dirname(__FILE__));
$module_dir = "modules/$module_name/";

these 3 lines in that code section

if(!eregi("modules.php", $_SERVER['PHP_SELF'])){
     die("You can't access this file directly...");
}


basically check to see if the module file is being accessed through the proper modules system or not. If not, the user gets the error message "You cannot access this file directly". If they are accessing the module through the modules system, the module will work properly.

This is done because some of the functions and variables used in modules require files like mainfile.php, theme.php and the database files to be included. These functions include the very commonly used OpenTable(); CloseTable(); OpenTable2(); and CloseTable2(); (see the "; ?> themes development section for details of what they are).

These 2 lines of code:

$module_name = basename(dirname(__FILE__));
$module_dir = "modules/$module_name/";


define the module name, and module directory for that module. We do this because you can then create links to pages and files in your module that aren't affected by you changing the name of the directory the module is in. You can also add:

$index = 1;


if you wish to have the right hand blocks showing in your module.

Creating a page

There are really 2 ways to create a page. You can either create each page in a seperate file, or create a function for each page, and use a switch to call the page functions (I'll explain this in a minute).

Creating a file for each page
When creating a file for each page, the files should all reside in the modules root directory (eg. /modules/module_name ). Each file should contain the same beginning as the module index.php file does.

Links to each of the pages will looks as follows:

When linking to a page, you would use a link tag like:

<a href="modules.php?name=$module_name&file=filename">


The filename should only contain the name of the file, not the extension (so it'd be something like
modules.php?name=Idiots_Guide&file=example

Also, if this link is in a php file, a \ should be added before every " inside the link tags so it'd look like this:

echo "<a href=\"modules.php?name=$module_name&file=filename\">Link Text</a>";


Creating a function for each Page
This is a more widely used method of creating pages. This method uses something called a switch to define the page functions so that they can be linked to.

A switch is a built in function of PHP defined using the switch($var){ function.

Normally, $var is $op but you can call it what you want to for modules.

Each page resides in the index.php file of the module inside a function, so the way to start a page would be as follows:

function pagename(){


and the function must be closed with a } at the end of the page. Putting this in when you first create the function, and then just adding the content in between the existing { and } is the best idea for not forgetting to close the bracket.

The function, if it's a page, must also be defined in the switch function too, so a standard switch might look as follows:

switch($op){

default:
pagename();
break;

case "pagename":
pagename();
break;

}


In this case, a default page was also defined as being function pagename();

If you wanted to add a page for this, you'd create a new entry in the switch function like this:

case "newpage":
newpage();
break;


where newpage() is the name of the function you've created the new page in.

Now, here's where it starts to get a little bit clever. The links for the pages would look a bit like this:

echo "<a href=\"modules.php?name=$module_name&op=pagename\">Link Text</a>";


When this link is clicked and the module is called, the index.php file looks at the switch function for the case that matches the pagename, as defined by "op=pagename". PHP then runs whatever's defined in that case before the break; line, which is just the function call "pagename();" in our example.

You can also place code in the switch if all you want to do is run an SQL statement, or have a confirmation screen after a form submission. (I'll talk about that more in the "Forms and Functions" section.

Giving your page a title

There is a pre-defined function in Nuke which allows you to create a title which displays on any pages you want the title of the module on. This is called using this line:

title("Your Title Goes Here");

This bit of code will display a title of "Your Title Goes Here" (without the quotes) on your site inside a full-width box.

In place of the title in quotes, you can also put in a language definition (see the Languages section lower down) which can be used to have a language-specific title for every language your site supports.

Adding Content to the pages

Before you start adding content to the pages, you should have the lines:

include("header.php");


and the last thing you should have in the page content is

include("footer.php");


Now I've mentioned the core 2 lines that must be included with every page, there is only one other line that really needs to be mentioned. This line is known as the globals line. (see "; ?> this section for what you can typically find on a globals line, and what each entry is for.

As for the content itself, it can be created using standard php and html script. Any html you wish to use, or anything you want to display on screen (other than the title) has to be inside an echo line:

echo "anything in here will show on screen, but the line must end like this: ";


inside this echo line, any html tags you use must have a \ before any "s you use

Forms and Functions

In modules, if you wish to use a form for information submission into a database, or a custom feedback module of some description for example, then the form can be initialised with the following tag:

<form action=\"modules.php?name=$module_name\" method=\"post\">


When you create the form content itself, be sure to add a hidden input with a name of op and a value of the name of the function which the form wants to send the data to.

Now, if all you want to do with the data once you've submitted a form is run a bit of code, so it doesn't require a user interface of any kind, instead of creating a function just for it, and sending the data submitted by the form to that function, you can just put the code right between case "bla_bla": and break;. For example:

case "formactioncode":

$db->sql_query(INSERT INTO ".$prefix."_random_table VALUES (NULL, $data1, '$data2');
header("Location: modules.php?name=$module_name&op=wherenext");

break;


This code inserts the values submitted in the form to a table, then sends the user to the next screen you want them to go to.

Languages

How, here's one of the cleverest bits of programming you're going to see in Nuke. A system was created that allows developers to program multiple languages for their modules, without having to repeat code over and over and over and over. Basically, it works like this. You create a directory called "language" (without the quotes) inside the modules directory. Then, you create a file named lang-[language].php where [language] is replaced with the name of the language that file is for.

Inside this file, you put lines like this:

define("_LANGUAGE_CALL", "Language Definition");


When, in the module, _LANGUAGE_CALL is entered instead of text inside a pair of quotes, the Language Definition will be displayed instead.

This isn't all it takes to make it work, there's 1 more line that must be added before the language files will be used.

Near the top of the index.php file, where the $module_name and $module_dir definitions are, afterwards, you add the line:

get_lang($module_name);


which will call the correct language files for that module.