Module Structure

The typical structure for the XOOPS Module looks like this:

Skeleton file structure

The following is a summary of the Basic Module Structure document by Onokazu. Note that this structure was outlined for XOOPS 1 RC3 modules. Not all of these files are needed [TO DO: WHICH ONES ARE ACTUALLY REQUIRED ?]

Create the following directory structure and files as a skeleton code that will form the basis of your new module.

Folder	Files	Description
/admin	admin_header.php index.php menu.php	Admin files
/blocks		block files
/config	config.php	configuration files
/language		local language files
------/english	admin.php blocks.php main.php modinfo.php
/assets		web files formerly /assets folder
----/css		CSS files
----/img		images & icons
----/js		JavaScript files
/sql		database setup files
/templates		Smarty templates
----/admin ----/blocks
/tests		test files
----/testdata		sample data files
xoops_version.php header.php index.php

Function of skeleton directories and files

The actual functions of these directories and files are described below. This is based partly on the Basic Module Structure by Onokazu and Coolpop’s Module Kickstart Guide. It is also based on an analysis of a simple module – Polls – and the code and comments therein. your_module The top level directory for your module must sit under the path: XOOPS_root/modules/your_module or you will not be able to install it. There are three files found in the suggested skeleton structure:

xoops_version.php This is the most important file in the module as it contains various module configuration variables. This file indicates: • Basic information about the module (name, author, credits etc) • The location of the sql database file, and the names of the database tables generated by the module • Whether the module has an administration page, and its location. • List of templates used in the module, with optional descriptions • List of blocks used in the module, with optional description • Whether the module should be included in the main menu • Whether the module uses comments, and on what pages

General variables & statements

Statement/variable	Description
$modversion['name'] = _MI_POLLS_NAME; $modversion['image'] = "images/xoopspoll_slogo.png";	A variable holding the name of the module (the name is specified in the file: language/english/modinfo.php file The path to the module image (for the administration menu)
$modversion['version'] = 1.00;

SQL-related variables and statements

Statement/variable	Description

Administrative things

Statement/variable	Description

Blocks

These statements provide information about the module’s blocks:

Statement/variable	Description

Menu

Statement/variable	Description
$modversion['hasMain'] = 1;	Specifies if the module should be included in the main menu (‘1’) or not (‘0’).

Comments

Statement/variable	Description
$modversion['hasComments'] = 1; $modversion['comments']['pageName'] = 'pollresults.php'; $modversion['comments']['itemName'] = 'poll_id';	Specifies if the module uses comments (‘1’) or not (‘0’). If you set this at 0 comment options will not be available in your module. ???? Not sure what this does. Look at the ‘including comments in your module’ guide in the Wiki etc. ???? ???? Not sure what this does. Look at the ‘including comments in your module’ guide in the Wiki etc. ????

header.php (not required)

Inclusion of required core files is done here. This file is not present in the Polls module. TO DO: LOOK AT ANOTHER MODULE AND SEE WHAT IT DOES THERE

index.php Module main contents come here.

/admin

All the admin related files for the module belong to this directory. Access to this directory must be restricted.

admin_header.php Permission checks, inclusion of mainfile.php and language files are done here.

index.php Module administration contents come here.

menu.php This file includes variables used for creating popup admin menu for the module.

/blocks

This directory contains files that define block display/edit functions

blocks.php

/cache

Files that are created/updated dynamically belong to this directory. To create new files within the directory, the permission of this directory should be set writeable by the server (chmod 666 or 777 for UNIX/LINUX servers).

The permission of files in this directory should be set writeable by the server (chmod 666 or 777 for UNIX/LINUX servers).

/images

This directory simply houses all of the images used in your module. Put them here. Easy !

/language

The language directory contains most of the text used in the interface of your module (ideally all of it). The official XOOPS modules are mainly distributed in English (only) but translations are available in many languages and you are free to install as many as you like – they coexist peacefully. Each language sits in its own subdirectory, ie:

/language/english /language/spanish /language/chinese etc

To translate a module simply copy (say) the english subdirectory, rename it and then translate the english text strings inside. Its that easy. If you want to change the text in a module, all you need do is to look in the appropriate language file. /language/english The text used in a module is not hard-coded into its interface, rather it is held within constants as you will see below. This keeps the module’s business logic separated from the text used in its display. That is why it is so easy to translate a XOOPS modules into many languages.

admin.php This file defines the value of language constants used in the administrative side of the module: If there are not many used in the administration pages, this file may be merged with english/main.php.

/sql

SQL dump files used for module installation belong to this directory.

mysql.sql mysql dump file postgresql.sql postgreSQL dump file

/templates

Smarty template files for XOOPS are called by xoops_version.php & modversion array.

All templates used in the module should be found in this directory.

module_start_page.tpl

/templates/admin

Location for all templates used in the Admin (Control Panel) of the module.

/templates/blocks

Location for .tpl template files used for blocks, and called by xoops_version.php & modversion array for 'blocks' items. These files use Smarty variables to display module information.

All templates used in module blocks should be found here. They use Smarty block variables to display module blocks information.