XBS Modgen, a Xoops CMS module is copyright © Ashley Kitson, 2006, UK
Xoops is copyright © xoops.org, 2000
The terms 'XBS ModGen' and 'ModGen' refer to the same product.
Ever wanted to write a module for Xoops but don't know where to get started? Are you writing for Xoops and find the initial module setup tasks boring or tedious? This module writes a complete module skeleton for you and enables you to setup the user side and admin side pages and menus, configuration items and underlying data tables. You have to provide the page logic but you are safe in the knowledge that you are writing in a secure framework as used by all XBS modules.
Features:
- Form driven entry of all information required to create module
- Setting up of following module items
- Name, tag and directory information
- Author, language and country information
- Module configuration items
- MySQL table creation
- Admin side and user side menu and pages
- Shell functions for module installation, update and delete
- Shell functions for search, comments and notification
- Framework to include common function in every page
- Structured approach to including language specific and non language specific constant defines in every page
- Shell page for every user and admin menu option
- Shell page for admin help page
- Shell scriopts for block definitions
- Admin menu in XBS module style allowing redirection to config page, home page, support site, documentation page and donations site
- One click module generation
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
You may not change or alter any portion of this comment or credits of supporting developers from this source code or any supporting source code which is considered copyrighted (c) material of the original comment or credit authors.
This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
This documentation may not be republished in any form without the explicit prior and written permission of its author, A Kitson. (admin@xoobs.net)
Xoops V 2.0.13 or V 2.2.4 (some limitations in admin menu appearance exist under V2.2.4 but the module is usable.)
XBS Code Data Management (XBS CDM) available from http://xoobs.net. This module must be installed prior to XBS ModGen. Depending on which distribution package you chose, XBS CDM may also be in your package.
Install XBS ModGen as per any other module. That is, unpack the archive and copy the contents of the xbs_mogen directory into your Xoops site modules directory. Logon as administrator, go to modules admin and install the module as per normal.
As this module is used to create new modules, we do not expect that you will install it on a production machine.
During installation, a message is sent to Xoobs.net telling the author that you have installed a copy of the module. No personal information is sent and this information is not used for any other purpose than to determine coverage of the module. If you deinstall the module a similar message is sent notifying the author of the deinstallation.
Whilst Xoops is undoubtedly one of the most feature rich and powerful freely available CMS's available, writing a Xoops module is not a task for the faint hearted. To write a good module you need to understand PHP programming including Object Orientation, SQL programming and in particular MySQL,and Smarty Template programming. In addition you need to have a good understanding of how Xoops itself works. XBS ModGen is not going to teach you any of these. What it can do however is set up a module framework that will install and will work. This typically involves setting up dozens of files in a directory structure that is a Xoops module. What documentation that is available is at http://xoopsdocs.net/modules/docs/
Once the framework is set up, you will still need to code your application logic to display input forms and output screens and any other processing that you require, but you can do this by editing just a few of the files that XBS ModGen provides and be sure that your module will work.
We advise that your development platform toolkit consists of a minimum of the following:
- A good text editor or preferably an integrated development environment such as Zend Studio or phpEclipse
- A graphics package such as The Gimp or Paintshop Pro
- phpMyAdmin installed on your development server for working with your MySQL server
Additionally you might also consider
- a graphical database design tool such as DBDesigner 4
- phpDocumentor for generating systems documentation. XBS ModGen writes out comments compatible with phpDocumentor.
- an XML editor such as XMLMind for writing user side and tutorial documentation for inclusion in phpDocuemntor output. This document is written using XMLMind.
Also take a look at the Xoops FAQ on what you need to develop Xoops mods at http://www.xoops.org/modules/smartfaq/faq.php?faqid=412
To use XBS ModGen you will need to first do some thinking and planning. The rest of this tutorial leads by example. Our example is a (very) simple address book. On the admin side we need to be able to set up a few module configuration items and manage the address book (edit, delete etc). On the user side we want to be able to display the address book as a list and allow the user to search specifically for an address. In addition we'll prepare the module for inclusion in the general search facility offered by Xoops.
There are many ways to design software and without going into a long discussion you need a statement of requirements first. Well, we have that - see previous paragraph. So lets break it down in terms of the functionality our module has to offer. Where our requirements statement doesn't specify what is required, the programmer will generally put in what they think fit. We'll do the same.
We need to be able to store data about addresses. We use MySQL to do this and can therefore define a table with the following attributes:
Table 1. xbs_address
Data Item | Data Type | Usage |
---|---|---|
id | int autoincrement | a unique internal identifier for an address - required |
name | varchar(30) | name of a person - required |
addr1 | varchar(30) | first line of address - required |
addr2 | varchar(30) | second line of address - not required |
town | varchar(20) | town of address - required |
postcode | varchar(8) | postcode of address - required |
We can convert this to a SQL statement:
create table xbs_address
( id INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
name VARCHAR(30) NOT NULL,
addr1 VARCHAR(30) NOT NULL,
addr2 VARCHAR(30) NULL,
town VARCHAR(20) NOT NULL,
postcode VARCHAR(8) NOT NULL,
PRIMARY KEY(id)
);
Please note that when we use this statement in ModGen, we will replace the actual table name with {TABLENAME}
From our requirement we can define two menu options for the user side of the module:
- List Addresses - Display a list of addresses in the address book
- Search Addresses - Present a search form for user to find an address
We only have one menu option on the admin side of things
- Manage Addresses - Allow administrator to perform edit facilities on the address book
We will be including our module in the Xoops general search facility
You need to have name for your module. In this example we'll call it 'XBS Address'.
You also need to have a tag for the module. A tag is a short acronym that is used to prefix a lot of names within the module to make them unique. We'll use 'XBSADDR'.
You need to have a name for the directory in which the module will sit in the Xoops framework within the modules directory. For this example we'll use 'xbs_addr'. You need to try to ensure that the tag name and directory name are unique to your module. This can be difficult and until Xoops come up with a way of allowing developers to register tags and directory names it is possible that you may choose one that someone else is using for their module development. I have suggested this to the Xoops team.
This is the modules directory on your server where you want to build the module to. For ease of use you may wish to make it the modules directory of the instance of Xoops that you are running, but it could be anywhere. We'll use '/web/xoops/modules'. You need to specify the absolute path of the location and note that there is no trailing slash. It is not a URL, nor can it contain dots or other non alpha characters.
Armed with our functional requirement detailed in section 4.1 we can now proceed to enter details in ModGen to create our module. However, you first need to set up ModGen for your usage with some module configuration options that will be valid for any module you create. All following instructions assume that you are signed in as administrator and have entered module administration and selected XBS ModGen. Please note that Xoops V2.2.4 users will not see the tabbed menu on the admin screen. They will have to use the drop down module admin menu.
Select 'Module Config' topline menu option. Enter the details as indicated on the screen.
Author Name - Your name - Used in the module credit and copyright notices Default Language - Default language for modules, defaults to English Country of Origin - Country in which software is developed - defaults to United Kingdom URL - URL of author's website - Used in the module credits AND as the place to which users are sent for support for your module Contact Details - How to contact the software author - usually you would enter your email address here. If you do, enter it in the form 'admin at xoobs dot net', to stop mail address harvesting.
Click Go! to save the details. These details will be used for all modules that you create using ModGen.
Click on 'Module Parameters' tab (or via Module menu option for Xoops V2.2.4 users). If this is the first time you have used ModGen, you will go straight to an input screen. Else click the Insert button to add a new Module record.
Please note that in subsequent usage of ModGen, you need to visit 'Module Parameters' to choose the module to work with. Any subsequent actions then act upon your chosen module.
Enter the details we gathered during the functional requirements stage.
Module Name - enter 'XBS Address' Module Tagname - enter 'XBSADDR' Module Description - enter 'A simple address book' Module Credits - Write here the names of any other developers or contributors to the module Has admin menu? - Click Yes Has user menu? - Click Yes Has module search? - Click Yes Has module notification? - Click No Has module comments? - Click No Module Directory - enter 'xbs_addr' Target build root directory - enter '/web/xoops/modules'
Click 'Save' to save the module parameters
Click on the 'Module Configs' tab. If this is the first time you have used this tab, you will go straight to an input screen. Otherwise you will see a list of items you have already defined and can edit them or delete them. Click on the 'Insert' button to add a new one.
Enter the details we gathered during functional requirements stage. You will need to repeat this for each configuration item that your module requires. We'll use the 'Welcome Message' as an example.
Item name - enter 'welcome_msg' - use any name by convention keep it short, in lower case and use underscores rather than spaces. Item description - enter 'User Welcome Message' - a descriptive message that is displayed in the module config entry screen. Form Type - select 'Text Box' Value Type - select 'Text Box' Field Length - enter '255' Default value - enter 'Welcome to XBS Address' Options - leave blank
The 'Form Type' relates to the type of input field that Xoops will display on the config input form. Value type relates to the basic field type as it will be stored in the database. Field length only really applies to text type fields. If your Value Type is 'Array', then in the 'Options' you should enter a comma delimited set of array items. These can be in the form '"item1","item2","item3"' or '"value1"=>"index1","value2"=>"inedx2"' etc
Click 'Save' to commit the record to the database. Repeat this process for all your defined configuration options.
Click on the 'Table Definitions' tab. If this is the first time you have used this tab, you will go straight to an input screen. Otherwise you will see a list of tables you have already defined and can edit them or delete them. Click on the 'Insert' button to add a new one.
We only have one table in our requirements so enter the details:
Table Name - enter 'xbs_address' Description - enter 'A simple address book' Table Create Script - enter 'create table {TABLENAME} ( id INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, name VARCHAR(30) NOT NULL, addr1 VARCHAR(30) NOT NULL, addr2 VARCHAR(30) NULL, town VARCHAR(20) NOT NULL, postcode VARCHAR(8) NOT NULL, PRIMARY KEY(id));'
Click 'Save' to commit the table definition.
Click on the 'Admin Menu' tab. If this is the first time you have used this tab, you will go straight to an input screen. Otherwise you will see a list of items you have already defined and can edit them or delete them. Click on the 'Insert' button to add a new one.
We only have one Admin Menu item so enter the details:
Short Menu Name - enter 'Manage' - Keep this name short so that it will fit easily on the admin menu tabs Menu Description - enter 'Perform edit facilities on the address book'
Click 'Save' to commit the definition
Click on the 'user Menu' tab. If this is the first time you have used this tab, you will go straight to an input screen. Otherwise you will see a list of items you have already defined and can edit them or delete them. Click on the 'Insert' button to add a new one.
We have two user side options, so enter the first:
Short Menu Name - enter 'List Addresses' Menu Description - enter 'Display a list of addresses in the address book'
Click 'Save' to commit the definition
Repeat this operation for your other menu items
We have now created all the items we need for our module shell. So lets generate it. Click on the 'Module Generation' tab. You will see a resume of your module displayed on the scree. If all looks OK, then click the 'Go' button to generate the module shell. A confirmation message will be displayed on successful generation.
You can now install your module using the Xoops module installation features as per normal. Once installed, check to see that each page on the user side and admin side displays as expected. A short message asking you to edit the appropriate page will appear.
Thats it! Now comes the hard bit :-)
The following directories and files are produced by ModGen into your module directory:
module:
header.inc - the module header file that is included in each user side page. This file in turn includes all necessary files for page display.
install_funcs.inc - shell functions that you must complete to provide processing (if required) when the module is installed, updated or removed
umenu#.php - one per user menu option i.e. umenu0.php, umenu1.php. Put your page display logic in these files
metatags_info.php - the XBS MetaTags configuration file. This is used by XBS MetaTags if installed on your target user's systems to create page indexing entries for keyword and page title generation. See the MetaTags system for more details.
index.php - the default page to display to user when they select your module. Can often be the same as umenu0.php but doesn't have to be. I.e. you could display a simple summary page. You will need to edit this page as with umenu#.php files.
xoops_version.php - module configuration file
module/admin:
admenu#.php - one per admin menu option i.e. admenu0.php, admenu1.php. Put your page display logic in these files.
adminheader.inc - a header file that is included in each admin page to in turn include all necessary files required for admin pages.
functions.inc - an empty shell script. Put in here any functions that are required by your admin pages.
menu.inc - admin menu item definitions
adminindex.php - the default page that is displayed when you click on your module logo in the administration system of Xoops
help.php - Edit this file to display system help to the administrator when they click on 'Module Help' from the module admin screen.
index.html - Sends user back to where they were. Prevents users from accessing directory directly.
module/admin/images:
bg.gif left_both.gif right_both.gif - glyphs used to display admin tabs
index.html
module/blocks: (the home for any block scripts)
block#.php - shell script for each block defined
index.html
module/class: (the home for any class definitions)
index.html
module/docs: (the home for any documentation)
index.html
module/images:
bg.gif left_both.gif right_both.gif - glyphs used to display admin tabs by some versions of Xoops
module_slogo.png - a blank module logo. Use a graphics editor to edit this and create your own module logo
index.html
module/include:
comments.inc - a shell function file that contains function headers required if your system is using the Xoops comments system. Edit if required.
notification.inc - a shell function file that contains function headers required if your system is using the Xoops notifications system. Edit if required
search.inc - a shell function file that contains function headers required if your system is using the Xoops search system. Edit if required
functions.inc - an empty shell file. Put in here any functions required to display your user side pages. This file is automatically included in user side menu pages
defines.inc - constant definitions that are non language specific. This file is automatically included in user side menu pages
index.html
module/language:
index.html
module/language/english: (Note, if you have selected a different language then it will be reflected here)
admin.php - module administration non language and language constant definitions
admin2.php - module Admin global menu definitions
blocks.php - language specific constant definitions for module blocks
main.php - constant definitions that are language specific rather than module specific. Edit this file to add you additional constant definitions as required.
modinfo.php - module installation language specific constant definitions
index.html
module/sql:
module_mysql.sql - the table creation script used by Xoops module installation
index.html
module/templates:
mytemplate.tpl - a simple Smarty template used to display the user side pages generated by ModGen
module/templates/blocks:
b_module_block#.tpl - simple Smarty template for each block defined
index.html
Define any blocks you want in your application in a similar manner to teh other items you have created. Now you need to write the logic for your application. ModGen has provided the framework for you, now you must create reality.
All XBS software is written using much the same format and it is one that you might use as a template. Look at some XBS modules such as ModGen itself, MetaTags, CDM and SACC.
First, create a file in include/class called something like class.module.base.inc. In this create your data object classes inherited from XoopsObject. Then create a file for each data object hander class based on XoopsObjectHandler. You could decide to use XBS CDM under your application as this has solid object handlers. Take a look at the class definitions for XBS ModGen to see how it is integrated with CDM.
Now, for each admin side menu page, create choice logic script in the appropriate admenu#.php file, but place all your display code into functions in admin/functions.inc. Take a look at how ModGen does this.
Repeat this for your user side pages using umenu#.php and include/functions.inc. You will also need to create Smarty Templates in the templates directory to support user side pages.
Remember to define language constants in /language/<your language>/main.php wherever you display text.
In all your code, make sure you comment clearly, preferably in English, and comment in depth; a/ to make sure you understand what is going on 6 months from now and b/so others can learn by your genius :-) Use the phpDocumentor style so that you can automatically generate documentation (place it in the docs directory.)
Don't forget to edit the module_slogo.png file to create your module logo.
Test it, test it and test it again.
Publish at your peril !!