Wiki ⇒ v9 Developer's Manual ⇒ Certified Secure ⇒ Modules ⇒ Module Creation Tutorial ⇒ CPG Dragonfly™ CMS
Wikiv9 Developer's ManualCertified SecureModules ⇒ Module Creation Tutorial

13.3.2. 1: Module Creation Tutorial Parent
A thorough explanation of everything that you need to make a module

Module Creation Tutorial
These are the main parts to creating a sucessful module

Folder Hierarchy
(The folder hierarchy is following the downloads pro hierarchy.)

YOUR_MODULE_NAME/
This is where all the normal and common files go.

cpg_inst.php
This is your installer. Many wonderful examples are out there -- simply open up a file from another module and the layout should be self explanatory

index.php
This is the main file to your module. It is your draw and update file

YOUR_MODULE_NAME/admin this is where you create all the admin stuff. the main files
should be .inc. those being the adminlink.inc and index.inc.
Dragonfly actually searches for these and have .inc's built in
so it searches for these types of files and it's actually alot
faster this way. keep it this way

YOUR_MODULE_NAME/admin/functions
this is where all the admin functions are

YOUR_MODULE_NAME/functions
if you want to have some extra functions that handle the module
without actually having to make your code larger and keep them
all in one place. i advise this. makes it neater and nicer

YOUR_MODULE_NAME/include
if for some reason you need more includes?

YOUR_MODULE_NAME/images
this is where you put all the system images. that is unless you
use the templating system. then those said images should go in
the YOUR_THEME's image folder for YOUR_MODULE. makes enough sence right?

lanugage/english/
YOUR_MODULE_NAME.php
if you don't hardcode what it says in the actual module then you
use this file and it is included somewhere in your module
(require_once()) and all the odd variables like _YES, _NO,
_NO_COMMENT etc are replaced by this file. that language file is
basically a bunch of defines. ex:

define('_LVOTES','votes');
define('_TOTALVOTES','Total Votes:');
define('_THEREARE','There are');
define('_NOMATCHES','No matches found to your query');
define('_SCOMMENTS','Comments');
define('_UNKNOWN','Unknown');
define('_AUTHORNAME','Author\'s Name');
define('_AUTHOREMAIL','Author\'s Email');
define('_DOWNLOADNAME','Program Name');
define('_ADDTHISFILE','Add this file');

blocks/
various files

these files are here for the user. these might or might not be needed.

there is no need for the user or even registered users to have

input on the site OTHER than what's on the forums. even there i

want to make sure that it's limited

themes/YOUR_THEME/
these are the templated files. if you want to create a module
with a template (i think highly of this system) then you put the
files here. you put your html here and add to the theme.php if
needed. i don't suggest it, all that code should be in your
module. also, if you were to do it you would have to follow the
rules for the templating formatting system. or in lamen: put
your module folder in module, your modules images in images and
so on and so forth

--------------------------------------------------------
explanations -> Main Section
--------------------------------------------------------
cpg_inst.php

this is the file that creates the tables for your particular module.
the two most important functions are install() and uninstall(). if the file is not there then it won't be allowed to install.
if the functions aren't there then you cannot even use the module because it won't install :)

it consits of a few items.
1. variables: you have to have your variables. der
2. constructor: this is your code credits.
3. install: create your installer function and install your tables. do it in this fashion:
a. create a global and use that to install your tables
b. recall the variable and keep installing as many variables that
you need.
c. return true.
4. uninstall: do it just like in the cpg_inst.php to uninstall.
5. upgrade: IF you need this then you can do it like this:
function upgrade($prev_version)
{
global $installer;
// $db->sql_query('DELETE FROM '.$prefix.'_credits WHERE
// modname="Downloads v2"');
}
6. For further information please click here.

search.inc
this file puts itself in the search area. i think, i'm not sure. so once your figure out your search code you put it into the search.inc. then when the user goes into the search link they can search only in your module instead of everything on the site. more refined and i believe that you should make your own search.inc so that it runs all together a bit more smoothly.

index.php
index.php is the index file of your module/system. it's the base file, kind of like you have index.html so that when someone goes to, for instance, www.google.com they head to the main file or the default file. that would be index.html. so think of index.php in the same exact way, because it's bascially the same exact thing.

index.php has many functions (not the actual functions but it's functionality as a whole). it will be your draw for whatever types of parts that your module wil have (example below), it will do the nessessary includes, it will update your module depending on what the end user has done. for instance the news function:

there are different ways that the news module looks depending on where you are and what you are doing. for instance you can be looking at a whole article, or perhaps you are looking on the main page and looking only at the summary, or perhaps you are looking at the survey and you want to rate it or you want to print.

well lines 19 to 44 (modules/news/index.php) is the basic function for rating an article. it determines if you have voted for an article or not and gives you the appropriate message depending on that.

there is also a pagination function starting and ending from lines 214 to line 260. that is a function to work with pagination.

now within the index.php is all the functionality that you need. it will draw the module depending on where you are and display them accordingly.

there is an area where you can actually define the tags for your module. and this would be the theme. on line 94 (modules/news/index.php) there is this code: if (THEME_USES_TPL). this is defining the tags for your theme. there are certain tags here but they are defined by the person that creates them. i will get more into templating and tag creation and using that nifty little $cpgtpl variable later.

--------------------------------------------------------
explanations -> admin section
--------------------------------------------------------
YOUR_MODULE_NAME/admin/index.inc

this i think is just bascially what is. the admin index and what you can do. bleh.

for instance. in downloads Pro the index includes all the files from that folder and uses the functions declared in there to use for the admin area. and then after all that, it is the main page for the admin section for Downloads Pro.

in my opinon the index portion of the admin is the most important. i would love to use the blogs but i cannot keep it so that only i can edit and add blogs and there is no admin section for the blogs. it's just straight foward blogging for anyone and i cannot change anything.

i personally like it so that there is more control for the admins and in this section is where it is all held. there is no reason to do or add anything to the main admin folder and i like that. correct me if i'm wrong

--------------------------

goto languages/englis/main.php lines 675 to 673 are all the admin area that your links would go into. what your code in the adlinks.inc file is doing is putting your links into one of these areas in the administration block to the left. by all means add to these, just remmeber what you are adding and when there is an upgrade that you have to redo this later on.

incase you don't understand these are all defines. they are just defining those wierd constants to text or strings (a string of caracters)

bascially if you don't have this then you can't even get into the admin section so forget about debugging it if you don't have these links in here

this is the breakdown of _AMENU#

$menuitems['_AMENU6'][$module]['IMG'] = strtolower($module);

$menuitems
['_AMENU6']: this is the category that it's set to
admin categories and description
_AMENU1: general
_AMENU2: memebers
_AMENU3: messages
_AMENU4: forums
_AMENU5: informative
_AMENU6: linking
_AMENU7: modules
notes1: you can add your own. they will all be added but sorted alphabetically

[$module]: not too sure. i don't think there is any messesing nessesary for this here. just leave it as is ['IMG']: the image associated with it (graphical area) or ['URL'] -> the url of that link

or ['MOD'] -> module i think or ['SUB'] -> sub category i think = duh. this is what the line as a whole is set to.

notes2: FYI if you do not need multiple admin links in the administration menu block then there is no need to add more. but do add the image to the images folder and make sure to you can have the graphical menu.

--------------------------------------------------------
explanations -> templating
--------------------------------------------------------
there are a few very basic things that you need to understand in order to do basic or even advaced template compliance with dragonfly. the way that themeing works is that the PHP file will be call the HTML file in YOUR_THEME/YOUR_MODULE_NAME's folder. then it places everything accordingly to that file and draws it within the index file of the root template folder. confused? i bet, look over the files and you'll understand. it's basically this in more simple terms

1. .php file calls template file
2. .php file draws HTML thru it's own code thru $cpgtpl->draw()
3. done and done. don't you feel sexy? i certainly do

here are some things that you need to understand in order to work with template compliance in your .php file
1. your template needs to be put into the themes folder under it's own folder. same for it's images and all that junk.
2. all the template files are HTML
3. you create your tags within your module's .php files.
4. you need to know how to work with the template.php files
5. you need to understand that $cpgtpl' is your global variable that you use in order to set your tags and display your template
6. your tags can be anything you want and formatted anyway that you want. but to be consise and consistant make them all capital and follow the format produced by DragonFly

now the basics. there is a very important file and variable from that file that you need to understand. the file is called template.php and the variable is $cpgtpl.

--------------------------
includes/classes/template.php
the functions that template.php has that $cpgtpl uses.

1. assign_block_vars: Assign key variable pairs from an array to a specified block
2. set_filenames: Sets the template filenames for handles. $filename_array
3. display: Methods for loading and evaluating the templates
.........a. this is your draw function. so you will draw or 'show' what you just created
4. assign_var: Assign a single variable to a single key
.........a. a single variable. it's like 'vars' but you only assign one variable
5. assign_vars: Assign key variable pairs from an array
.........a. ok, this is where you'll be assigning the tags for your template depending on what you want to show

--------------------------
$cpgtpl
this is a global that is a variable of this class in includes/cmsinit.inc and its declared global in _______________

--------------------------
includes/cmsinit.inc

Load the theme template system and check if the current theme uses the system. some code from that file right here:

$ThemeSel = get_theme();
// defines this constant to the template header.
define('THEME_USES_TPL', file_exists('themes/'$ThemeSel.'/template/header.html'));
// Load template handler
$cpgtpl =& new cpg_template();
$cpgtpl->set_template(); // dynamic language
if (THEME_USES_TPL)
$template =& $cpgtpl;

basically what this define does (which i didn't even know you could do in programming never mind PHP) is check for the verification of the header template file in your themes folder.

--------------------------------------------------------
explanations -> templating
--------------------------------------------------------
there are many more functions within the template.php file but the ones that i have shown are the more important ones that you'll be using more than often. assigning the variable names and shwoing your template and telling where the module theme is (set_filenames).

if you liked it please, email me so that i can keep adding and making your lives easier.

Created: Monday, September 12, 2005 (05:34:16) by MrPotatoes
Updated: Tuesday, September 12, 2006 (22:37:44) by tuta