Location: PHPKode > projects > Enigma > Enigma2/Enigma2_Upgrade_from_beta5/modules/Modules.txt
*****************************************************************

 Modules.txt

*****************************************************************
LSP: Lunabyte Systems Portal
Open-Source Project Inspired by Zef Hemel (hide@address.com)
*****************************************************************
Software Version:                  LSP 2.0 "Enigma 2"
Software by:                         Lunabyte Systems (http://www.lunabyte.net)
Copyright 2002-2005 by:       Lunabyte Systems (http://www.lunabyte.net)
Support, News, Updates at:    http://www.lunabyte.net
*****************************************************************
This program is free software; you may redistribute it and/or modify it
under the terms of the provided license as published by Lunabyte Systems.

This program is distributed in the hope that it is and will be useful,
but WITHOUT ANY WARRANTIES; without even any implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the "LSP_license.txt" file for details of the LSP license.
The latest version can always be found at http://www.lunabyte.net.
*****************************************************************

This file is here to help explain what is needed to create a module addon
for your Enigma Portal.

In the past, if mod creators wanted to add features to the portal, they
would have to dump new php files inside the Sources directory and then
add to the gigantic action or op arrays that existed in the index.php file
of previous versions of Enigma and YaBB SE.

With Enigma 2.0 you are able to add new features to your portal without
having to edit the original installation files and there is no need for
adding to any internal arrays. If a request is made for a module, the
modules directory is automatically scanned for the corresponding Mod_{name}.php
file and loaded as needed to excecute functions.


The following will need to be expanded as Enigma 2.0 expands and moves further
along in it's updates to a final release, but currently this will explain the
basics....

*** Standard Module additions ***

1.	A php file (to be referred to as a module from here forward) to be 
	added in the modules directory has to have a Mod_ prefix on it to 
	be recognized by the main portal code as a module. All php 
	functions associated with the module should be contained within 
	it.  However, you may still call functions from the main as you 
	were able to in past versions.

2.	All template files associated with the module should be put in 
	your Themes/{themename}/portal/modules directory and 
	named according to the following. 

		Modulename.template.php 

		- replace 'Modulename' with the actual name of
		  the module.

	Use loadMTemplate('Modulename'); to load a template for any module.  
	Do NOT use loadPTemplate (Enigma template function) or 
	loadTemplate (SMF template function).

3.	All language files associated with the module should be put in your 
	Themes/{themename}/languages/portal/modules directory and 
	named according to the following.

		Modulename.{language}.php

		- replace 'Modulename' with the actual name of
		  the module and replace {language} with the 
		  appropriate language name.

	Use loadMLanguage('Modulename'); to load a language file for any 
	module.  Do NOT use loadPLanguage (Enigma language function) 
	or loadLanguage (SMF language function).

4.	Any functions that need to be loaded every time a page refreshes
	should be added to ModuleSubs.php which is found in the 
	modules folder.  Please refrain from putting a lot of functions in 
	this file, as it will increase load times if adding functions that aren't 
	really needed on every page load.


*** Permissions, Settings, Error messages, Admin Index and Help Text

The following paragraph is the old way of adding these features for your module and may
still be used, but the recommended method (new in Enigma2 RC1) is explained below.

To add permissions, settings and error messages to the site for your new module,
use the corresponding ModulePermissions.php, ModuleSettings.php,
ModuleErrors.{language}.php, ModuleHelp.{language}.php and
ModuleSettings.{language}.php files. Each file has some basic information for
making additions, right in the file.  If more help is needed in making these additions,
refer to the SMF Forum documentation.  Modules use the SMF functions for all of
these features and the related Module files just append information to the main
Enigma and SMF files.

*** New and improved methods of loading module permissions, settings, errors, help text and
adding your new module to the admin index.

Keep in mind that this is just a basic explantion and that you will still need to know
you way around the Enigma and SMF code to use everything correctly.

As of the RC1 release Enigma now has what we call "Autoload" folders.  These are new folders
designed for module related files to be placed that will be loaded automatically when the
corresponding pages of your portal are loaded.

Inside of the main "modules" directory in the root directory of your Enigma installation there
are 3 new directories which are explained below.

Note:  very shortly after the release of RC1, we will be releasing an Uploads module which uses
all parts of the new Autoload features.  Even if you are not interested in using the Uploads
Module features on your site, we recommended that you browse through it's files for examples
of how to use the modules autoload directories and files.

	ModuleControls - used to add a module to the Admin Index listing.  The module needs to be added
		to one of the existing admin display arrays.  Refer to ModuleControls.php, Subs.inc.php
		or the Admin index function in SMF's Subs.php file to see what arrays exist and examples
		of how to add your module.

	ModulePermissions - used to add permission variables for use on the "Edit Permissions" page.
		In the file you create for your module, you will need to create 3 specific arrays named:
		$perm_list, $perm_non_guest & $perm_left_groups.  Each of these arrays follow all of the
		SMF formats for permissions.  You can refer to ModulePermissions.php, PortalPermissions.php
		or SMF's Permissions.php files for examples of setting up the arrays.  When you go to the
		Permissions page from the Admin Center, your new file will be loaded and each of the 3 mentioned
		arrays will be merged with the existing permission arrays.

	ModuleSettings - used to add settings to the Portal Settings page in the Admin Center.
		Files in this directory will need to use $auto_config_vars as the name for the main array.
		This array is setup just like the main arrays in ModuleSettings.php, PortalSettings.php & SMF's
		ModSettings.php files.  You can add to an existing section of the settings page by adding
		to part of the existing multi-dimensional array or create a new section of the array.  As with
		permissions, when the Settings page is opened, your new file will be loaded and the config array
		will be merged with the existing arrays so that your settings will be displayed.
		
	** Please remember to create any needed language variables for files created above.  Explanation of
	how the language files are loaded will be next.
	
New directories for language variable files are also added as of RC1.  These are initially created
inside the default theme directory's language/portal/modules directory.  If you need to customize any newly
created language files for a custom theme, you may also create these directories in your custom theme's
language directory as well.  Usually the default theme should be sufficient.  Let's list the directories now.

	ModuleAdminHelp - put files containing the help variables for Module Settings in this directory.
		Just the standard $helptxt variable format is required here.  All files in this directory will
		be loaded and the variables will be added to the $helptxt global going to the Portal Settings page.
		Refer to ModuleHelp.english.php, PortalHelp.english.php & SMF's Help.english.php files for more
		information on formatting.

	ModuleControls - this where the language variables will go that you used in the main ModuleControls
		directory to add a module to the admin index listing.  The requirement for these is that you
		need to use the same variable name as you did in the corresponding ModuleControl file.
		
	ModuleErrors - does your new module have custom error messages stored in variables that could be triggered
		before the main module code loads?  If so, you will need to add them as $txt variables in a file
		in this directory.  Again, view the main Enigma and SMF files for reference.

	ModulePermissions - the files in this directory are to contain the language variables for the permissions
		file you created above.  Be sure to maintain the coinciding variable name for the permission you
		added previously.  Follow the formats in the main Enigma and SMF permission files.

	ModuleSettings - as with permissions, these are the files that correspond to the ModuleSettings file(s)
		that you created above and the variables will also need to have names corresponding with the settings
		you created.  And again, refer to the main Enigma & SMF files for more info.
		
As stated earlier in this text file, module creation is meant for users that have some php & mysql knowledge and
you will need to know your way around Enigma & SMF just a bit before being able to make full use of these
features.  However, once mastered, modules can and will become the back bone for creating a feature rich site.

And again, please refer to the Uploads Module files for examples of how all features of modules are used.
Every feature described in this text file has been used in the Uploads Module, making is good reference material.
Return current item: Enigma