====== Modules ======
Modules allow to create extra functionality that does not touch the core files of 68 Classifieds. Thus enabling your module to not get overwritten during upgrades. 

===== Module Requirements =====

  - Each module must be contained in a single directory.
  - Each module must have a config.php file that includes needed information.
  - The users should be able to activate and use the module from the "Modules" menu in the administrative. Optimally, a module should not require users to modify the source code.
  - If the module is going to interact with 68 Classifieds hook system it must have a hooks.php file.
  - If needed inside the modules directory it can have a templates, language, and plugins directory. The templates directory would contain any template files needed. The language directory allows your module to work for multiple language. Please be careful not to name a language string the same as the standard language file. The plugins directory is to place any Smarty plugins that you would like to use for this module.
  - index.php and admin.php and used if the module has a frontend area or an administration section. These are only required if the user needs to have some of interaction with the module.
  - You may include any other files that the module may need to interact with.

===== Module Tutorial =====
This is intended to be a short tutorial on creating a module. 

==== Naming Your Module ====

The first step is to name your module. We will be building a module that allows you to specify a custom showlisting file when viewing a category. We will name this module "Custom Cats". So we create a directory inside the modules folder named customcats.

==== Create A Module Folder ====

Once we have the name of our module, we need to create a folder for it in the modules folder. The name of this folder should be a lowercased and space-less version of the module's name. Instead of spaces, you should either use a single word for your module or underscores. For our example, we will create a folder called "customcats" that would be located like so: /modules/customcats/.

==== Create a configuration file  ====

We will need to create a new php file named config.php that will reside in the /modules/customcats folder .

The config.php file should look like this:
<code php>
<?php
	$data['module']['name'] = "customcats";
	$data['module']['displayname'] = "Custom Categories";
	$data['module']['description'] = "Allows you to use custom category template files.";
	$data['module']['version'] = "v1";
	$data['module']['admin_capable'] = "1";
	$data['module']['user_capable'] = "0";
?>
</code>
These variables should be pretty self explanatory. However the name should only contain letters, numbers, dashes, or hyphens. Do not enter any spaces here. The version is your internal version number separate from 68 Classifieds. The admin_capable and user_capable determine if the module should be accessed from either location. Since the admin_capable has a value of 1 that means it can be accessed through the administration. Where as the user_capable has a 0 which means this module only includes an admin file.

==== Create an init.php file ==== 

The init.php file is responsible for installing items into the database and uninstalling if the user decides to remove the module.

The init.php file can have three functions and they are:
<code php>
install()
upgrade()
uninstall()
</code>
These functions are not required if you do not need to insert any items into the database.

For our module this file will include the following code:
<code php>
<?php
	function install()
	{
		global $db, $class_tpl;
		$sSQL="ALTER TABLE `".PREFIX."categories` ADD `ccTemplate` VARCHAR( 255 ) NOT NULL ;";
		$db->query($sSQL);
		$class_tpl->assign('msg', 'Everything installed successfully.');
	}
?>
</code>

==== Creating a hooks.php file ==== 

The hooks.php file is responsible for integrating functionality in the core of the script. Here is an example file: 
<code php>
<?php
	class customcats_events
	{
		function customcats_events(&$modules)
		{
			$modules->register('admin_tpl_layout_category', $this, 'admin_links');
		}
		function admin_links()
		{
			echo '<a href="modules.php?mod=customcats">Custom Cats</a>';
		}
	}
?>
</code>

This code basically does two things. First in the constructor it registers the event you want and then when that hook is called it runs your method. In the example above we register admin_links to the admin_tpl_layout_category hook. Once this hook is called the admin_links method is ran. In this case it adds a new link to the admin navigation. 

==== Creating an admin.php file ==== 
The admin.php file is not always needed but if you have $data['module']['admin_capable'] set in the config file then it would be required. Our admin.php file will be responsible for showing the user a list of their categories and a way to add the custom template for each one. Here is the completed file:
<code php>
<?php
	require_once(FILESYSTEM_PATH .'includes/classes/kernel/Categories.php');
	$Categories = new Categories;

	if(isset($_GET['action']) && $_GET['action']=="modify" && isset($_GET['id']))
	{
		$sSQL = 'SELECT id,ccTemplate,name FROM '.PREFIX.'categories WHERE id='.(int)$_GET['id'];
		$result=$db->query($sSQL);
		$rs=$result->fetch();
		$class_tpl->bulkAssign($rs);
		$result->freeResult();
		$location = FILESYSTEM_PATH .'modules/customcats/templates/cattemplates/';

		if ($handle = opendir($location))
		{
			while (false !== ($file = readdir($handle)))
			{
				if ($file != "." && $file != ".." && $file!="CVS" && $file!="index.htm")
				{
					$filelist[]=$file;
				}
			}
			closedir($handle);
		}
		$class_tpl->assign('files', $filelist);
		$class_tpl->assign('body','customcats_edit.tpl.php');
	}
	elseif (isset($_POST['action']) && $_POST['action']=="save")
	{
		$sSQL = 'UPDATE '.PREFIX.'categories SET ccTemplate="'.$_POST['ccTemplate'].'" WHERE id='.(int)$_POST['id'];
		$result=$db->query($sSQL);
		//sucessfull
		$location="modules.php?mod=customcats";
		$class_tpl->assign('title',LANG_FORWARD_SUCESS);
		$class_tpl->assign('forward',TRUE);
		$class_tpl->assign('location',$location);
		$class_tpl->assign('body','forward.tpl.php');
	}
	else
	{
		$tree=$Categories->getAdminCatTree("", 0, TRUE);
		$class_tpl->assign("results", $tree);
		$class_tpl->assign('body','customcats_browse.tpl.php');
	}
	$class_tpl->displayTemplate();
?>
</code>
As you can see this file has three steps. Viewing the category list, editing a category, and updating the database. 

==== Creating a language file ==== 
The next step is to create our language file. For this tutorial we will only create an english language file but it should give you the idea on how it is setup.

Inside your module folder you should create another folder named language and then an english.php file. For this example it will be located here: modules/customcats/language/english.php

Here is what this language file looks like:
<code php>
<?php
	define("LANG_CC_TITLE", "Custom Categories");
	define("LANG_CC_TEMPLATE", "Custom Template");
?>
</code>
One thing to keep in mind is that you do not want to use the same defined variable as another. So please prefix your define statements like done here.

==== Creating the templates ==== 

The templates for your modules will all be located in the modules/customcats/templates folder. Because 68 Classifieds uses a layered approach they will be automatically loaded when the admin or index file is ran.

For our module we will create two templates. customcats_browse.tpl.php and customcats_edit.tpl.php

Here is what I have included in each:

customcats_browse.tpl.php
<code>
<h2>{$smarty.const.LANG_CC_TITLE}</h2>
<table width="100%" class="wrap"><tr><td>
	<table width="100%" border="0" cellspacing="0" cellpadding="3" class="main">
		<tr>
			<th scope="col">{$smarty.const.LANG_ID}</th>
			<th scope="col">{$smarty.const.LANG_FULLNAME}</th>
			<th scope="col" width="15%">{$smarty.const.LANG_ACTIONS}</th>
		</tr>

		{foreach from=$results item="entry" name=status}
		<tr>
			<td width="5%" class="{cycle values="row1,row2" advance=false}">{$entry.id}</td>
			<td class="{cycle values="row1,row2" advance=false}">{$entry.name}</td>
			<td class="{cycle values="row1,row2" advance=true}"><a href="modules.php?mod=customcats&amp;action=modify&amp;id={$entry.id}">{$smarty.const.LANG_MODIFY}</a></td>
		</tr>
		{foreachelse}
		<tr>
			<td colspan="6">{$smarty.const.LANG_NO_RESULTS}</td>
		</tr>
		{/foreach}
	</table>
</td></tr></table>
</code>
customcats_edit.tpl.php
<code>
<h2>{$name}</h2>
<table width="100%" class="wrap"><tr><td>
	{if $success}
	<script type="text/javascript" src="javascript/fat.js"></script>
	<div id="message" class="updated fade"><p>{$smarty.const.LANG_SETTINGS_SAVED}</p></div>
	{/if}

	<form action="modules.php" method="post" name="mainform">
		<input type="hidden" name="action" value="save" />
		<input type="hidden" name="id" value="{$id}" />
		<input type="hidden" name="mod" value="customcats" />
		<table width="100%" class="main">
			<tr>
				<td class="{cycle values="row1,row2" advance=false}"><label for="ccTemplate">{$smarty.const.LANG_CC_TEMPLATE}</label></td>
				<td class="{cycle values="row1,row2" advance=true}">
				<select name="ccTemplate" id="ccTemplate">
					<option value=""{if $ccTemplate == ""} selected{/if}>Default</option>
					{foreach from=$files item=entry}
					<option value="{$entry}"{if $entry==$ccTemplate} SELECTED{/if}>{$entry}</option>
					{/foreach}
				</select>
				</td>
			</tr>
			<tr>
				<td colspan="2" align="left" class="{cycle values="row1,row2" advance=true}">
				<div align="center">
					<input type="submit" value="{$smarty.const.LANG_SUBMIT}" />
				</div>
				</td>
			</tr>
		</table>
	</form>
</td></tr></table>
</code>

For this module I also created a new folder named cattemplates located inside the templates folder. Here is the path:

modules/customcats/templates/cattemplates

This will be the place for the administrator to save their custom templates. This way it will keep it separate.