Qool CMS Manual

The Template

We have created the backend of our module and the next thing we need to do is create the frontend for this module.

We will start from the frontend template file located at /modules/HelloWorld/template/index.tpl :

<h1>{$QoolMO->modLang.QUOTE_OF_DAY}</h1>

<p>{$QoolMO->quote}</p>

It really is that simple.

We print a message in <h1> tags and we create a paragraph with our quote in it. We are done.

The Module file

Next we have to do is create the frontend code. This is the skeleton we must use:

<?php
class quotes{
var $QoolDB = array();
var $QoolRS = array();
var $QoolUR = array();
var $QoolSL = array();
var $QoolUI = array();
var $site = array();
var $QoolTR = array();
var $QoolSP = array();
var $QoolSE = array();
var $QoolFS = array();
var $QoolQM = array();
var $QoolWF = array();
var $QoolPM = array();
var $QoolQC = array();
var $QoolLS = array();
var $QoolFM = array();
var $QoolDS = array();
var $QoolVS = array();
var $QoolQR = array();
var $modLang = array();
var $quote = '';
var $modMenu = array();

function quotes($search='',$DB,$RS,$UR,$SL,$UI,$site,$TR,$SP,$SE,$FS,$FM,$DS,$VS,$QM ,$QC,$WF,$PM,$LS,$QR){
$this->QoolDB = $DB;
$this->QoolRS = $RS;
$this->QoolUR = $UR;
$this->QoolSL = $SL;
$this->QoolPM = $PM;
$this->QoolQC = $QC;
$this->site = $site;
$this->QoolQM = $QM;
$this->QoolWF = $WF;
$this->QoolLS = $LS;
$this->QoolTR = $TR;
$this->QoolQR = $QR;
$this->QoolSP = $SP;
$this->QoolSE = $SE;
$this->QoolFS = $FS;
$this->QoolFM = $FM;
$this->QoolDS = $DS;
$this->QoolVS = $VS;
//We include any files needed. Like the language file of the module
include $this->site."modules/HelloWorld/languages/ $SL->currentLang/index.lng";
$this->modLang = $_LANGUAGE;
if($search!=''){

}else{

}
$this->getRandomQuote();
$this->stopModule();
}

function stopModule(){
unset($this->QoolDB);
unset($this->QoolRS);
unset($this->QoolSL);
unset($this->QoolUI);
unset($this->QoolUR);
unset($this->site);
unset($this->QoolSP);
unset($this->QoolFS);
unset($this->QoolVS);
unset($this->QoolRB);
unset($this->QoolTR);
unset($this->QoolSE);
unset($this->QoolFM);
unset($this->QoolQM);
unset($this->QoolWF);
unset($this->QoolQC);
unset($this->QoolPM);
unset($this->QoolLS);
unset($this->QoolQR);
}
}
?>

The code above is nearly the same as the one we used in the backend. There are some things you have to notice. For example the class name is quotes. We have set this in the install.ini file when we started creating our module. One more difference is the $search check:

if($search!=''){

}else{

}

This code checks if the core is searching something and if our module supported search it would handle the search. We also added this line of code:

$this->getRandomQuote();

which will get a random quote and assign it to Smarty in order to display it with our template. This is the code of our method:

function getRandomQuote(){

$DB = $this->QoolDB;
$RS = $this->QoolRS;
$site = $this->site;
$table = $RS->db_prefix.$this->site."_"."helloworld";
$sql = "SELECT * FROM `$table` WHERE `in_trash`=?";
$data = array(0);
$query = $DB->query($sql,$data);
if (PEAR::isError($query)) {
$this->quote = null;
}else{
while ($rows = $query->fetchRow(DB_FETCHMODE_ASSOC)){
$quotes = $rows;
}
$this->quote = $quotes;
}

}

Our module is now ready. All we have to do is enable it from the admin panel:

The magenta colored arrows show what we need to change to activate our module. Now save it, add some more quotes, insert the QUOTE_OF_DAY string into the language file of your module and load your site:

Our sample module is ready. The module has been added to the main menu and it displays a random quote each time reloaded.

So far we created a template for our module and the backend. We will also need to create some more files for our module to be complete. One of these files is the module's language file. Creating a language file is the easiest part of our module creation. Go to the languages directory of our module. That is /modules/HelloWorld/languages/ and create a new folder named “english”. Then enter this folder and create a new file named index.lng and put this code in it:

<?php
$_LANGUAGE=array(
""=>""
);
?>

That's it. Now no more coding is required. All you have to do now is go to the File Manager link on the left menu and navigate to the HelloWorld module's folder. Double click on the modules folder:

and then on the HelloWorld folder:

and then on the languages folder:

Finally we double click on the english folder:

and in the English folder we see this file:

This is our language file and we need to edit this file in order to insert our strings in it. If you click on this file once the top menu area changes and displays some options:

Have you noticed the Edit Language File link on the top menu? This link will let you edit the file and insert the strings for our module. Click on it and you should see something like this:

The editor we see above is called Language Editor and it allows us to insert or edit language strings one by one. So we must do for our module. We gather all strings we used in the template file and in the backend file. These are:

• SUBMIT → Submit

• QUOTE → Quote

• ACTIONS → Actions

• DELETE → Delete

• ADD_QUOTE_FAIL → There was an error. The system could not insert the Quote.

• ADD_QUOTE_SUCCESS → The Quote has been inserted

Our file after inserting the strings above should look like this:

Now our file is ready. Lets use it. Load the module's backend and you will see our strings printed where needed.

We are ready. Our module is now able to store quotes in the database and move them to the Trash bin if the admin decides it should. You can log in to your newly created site and click on the Quotes module:

You can see the Add link that will allow us to add new quotes in the database. Lets click on it:

Now if you fill some text in the text field and hit the button, the quote will be added to the database. Don't worry about missing strings yet. These will be added when we edit the module's language file. So lets create our first quote. We will create the “Hello World is old. Give me something new” string:

That's it. We created our first quote with our new module. Lets try to delete it and then restore it. Click on the Delete link and Qool will inform you that the item has been deleted (Actually it will just display the messages placeholder but no message in it. We must still create the language file.).

Now if everything is OK our quote is in the system Trash Bin. Click on the Trash Bin link on the left menu and you should see the Trash Bin panel with our quote in it. Click the Restore link and our quote will be restored.

Our template is ready but we still need some work to do before our module is ready. We have to create our module's backend. So we open the file admin.php in our editor and create the code skeleton for our module (Check the //inline comments for more info):

<?php
class modAdmin{ //We create the backend object name. This is the same for all modules.
var $me = array(); //The module itself. Holds module's data
var $QoolDB = array(); //The database object inherited by Qool core
var $QoolRS = array(); //The Requests object inherited by Qool core
var $QoolSL = array(); //The System Language object inherited by Qool core
var $QoolUI = array(); //The Users Info object inherited by Qool core
var $QoolRB = array(); //The Trash Bin object inherited by Qool core
var $QoolFS = array(); //The Qool File System object inherited by Qool core
var $QoolQM = array(); //The Macros object inherited by Qool core
var $QoolWF = array(); //The Workflow object inherited by Qool core
var $QoolUR = array(); //The Users Rights object inherited by Qool core
var $QoolLS = array(); //The Logger object inherited by Qool core
var $QoolSE = array(); //The System Email object inherited by Qool core
var $QoolQC = array(); //The Comments object inherited by Qool core
var $QoolPM = array(); //The Private Messages object inherited by Qool core
var $QoolVS = array(); //The Version Control object inherited by Qool core
var $QoolSP = array(); //The System Pager object inherited by Qool core
var $modLang = array(); //The module language
var $site = array(); //The site we are administrating in an array
//The constructor function.
function modAdmin($DB,$RS,$SL,$UI,$UR,$site,$me,$SP,$FS,$DS,$VS,$RB,$QM,$QC,$SE,$WF,$PM,$LS){
$this->me = $me; //
$this->QoolDB = $DB; //
$this->QoolRS = $RS; //
$this->QoolSL = $SL; //
$this->QoolFS = $FS; //
$this->QoolRB = $RB; //
$this->QoolWF = $WF; //
$this->QoolPM = $PM; //
$this->QoolSE = $SE; //
$this->QoolLS = $LS; // ← Assign inherited values
$this->QoolQM = $QM; //
$this->QoolQC = $QC; //
$this->QoolVS = $VS; //
$this->QoolUI = $UI; //
$this->QoolDS = $DS; //
$this->QoolUR = $UR; //
$this->site = $site; //
$this->QoolSP = $SP; //
//We include any files needed. Like the language file of the module
include $this->site."modules/HelloWorld/languages/$SL->currentLang/index.lng";
$this->modLang = $_LANGUAGE;

}
?>

What we see is a skeleton that all modules must use for the system to load them correctly. We set some objects that are inherited from the core and we also load any module specific files like the language file.

Now we need an internal check in the constructor function that will wait for user generated actions and generally act as a controller. We will place this check right after :

$this->modLang = $_LANGUAGE;

This is the code:

$this->getQuotes();

if($_GET || $_POST){
switch($RS->action){
case "del":
$this->trash();
break;
case "newQuote":
if($_POST){
$this->add();
}
break;
}

}

The code above will check for any generated actions and will filter them. If the user wants to delete (del) a quote, the system will run the trash() function and if the user wants to add a quote it will run the add() function. We also need to get the quotes so we run getQuotes().

Lets create the add() function first. It will just insert any text the user posts in our “helloworld” database table:

function add(){
$DB = $this->QoolDB;
$RS = $this->QoolRS;
$siteId = $this->site;
$me = $this->me;
$table = $RS->db_prefix.$this->site."_"."helloworld";
$update = array(
'id'=>'',
'active'=>1,
'in_trash'=>0,
'creation'=>time(),
'quote'=>$RS->postRequest);
$query = $DB->autoExecute($table,$update,DB_AUTOQUERY_INSERT);
if(PEAR::isError($query)){
echo "<meta http-equiv='refresh' content='5;url=./admin.php?siteId=$siteId&moduleIdAdmin=$me&action=top'>";
$this->msgType = 'System';
$this->Msg = $this->modLang;
}else{
echo "<meta http-equiv='refresh' content='5;url=./admin.php?siteId=$siteId&moduleIdAdmin=$me&action=top'>";
$this->msgType = 'System';
$this->Msg = $this->modLang;
}
}

We also need to create the trash() function which will trash (not delete) quotes that the user does not need anymore. By using this object we can restore the specified item. We will use the Trash Bin ($RS) object we inherited from the Qool core:

function trash(){
$RB = $this->QoolRB;
$RS = $this->QoolRS;
$table = $RS->db_prefix.$this->site."_"."helloworld";
$RB->trash($RS->itemId,'Quote',$table,$this->me,'Quote');
$this->msgType = 'System';
$this->Msg = $RB->Msg;
}

And at last we need to create the getQuotes() method that will query the database and get all existing quotes. Here is the code:

function getQuotes(){
$DB = $this->QoolDB;
$RS = $this->QoolRS;
$table = $RS->db_prefix.$this->site."_"."helloworld";
$sql = "SELECT * FROM `$table` WHERE `in_trash`=? ORDER BY `id` DESC";
$data = array(0);
$query = $DB->query($sql,$data);
if (PEAR::isError($query)) {
$this->quotes = array();
}else{
while($rows = $query->fetchRow(DB_FETCHMODE_ASSOC)){
$this->quotes = $rows;
}
}
}

Important

There is another important method that is needed for our module to work. It is the stopModule method that was left last to ensure that you pay the most attention to it. This method is run automatically from the Qool core in order to free resources. So if it is not there, the system will display a nice Fatal Error The only thing that it does is unset all inherited objects. You can use this method in all your modules. There you go:

function stopModule(){ //Free resources. Some objects was striped out for the shake of space
unset($this->QoolDB);
unset($this->QoolRS);
unset($this->QoolSL);
unset($this->QoolUI);
unset($this->QoolUR);
unset($this->site);
unset($this->QoolSP);
unset($this->QoolFS);
unset($this->QoolVS);
unset($this->QoolSE);
unset($this->QoolRB);
unset($this->QoolQM);
unset($this->QoolQC);
unset($this->QoolWF);
unset($this->QoolPM);
}

Creating a module template is pretty easy. All you have to do most times is to write some HTML code. Qool CMS uses Smarty Templates. Smarty is a very powerful template engine. More for Smarty can be found at the official site.

This is the code for our module's admin page (File: /modules/HelloWorld/template/admin.tpl):

{if $QoolMO->QoolMA->msgType =='System'}
<div style="text-align:center; background-color:red; border: 1px solid silver; height:100px; width:400px;">{$QoolMO->QoolMA->Msg}</div>
{else}

{if $QoolRS->action=='addQuote'}

<form action="admin.php" method="POST" name="newQuote" >

<input type="hidden" name="siteId" id="siteId" value="{$QoolMO->siteToEdit.id}" />
<input type="hidden" name="moduleIdAdmin" id="modid" value="{$QoolMO->moduleToEdit.id}" />

<input type="hidden" name="action" id="action" value="newQuote" />

<input type="text" name="quote" id="quote" value="" />

<input type=”submit” value=”{$QoolMO->QoolMA->modLang.SUBMIT}”>

</form>

{else}

<table>

<tr>

<td>{$QoolMO->QoolMA->modLang.QUOTE}</td>

<td>{$QoolMO->QoolMA->modLang.ACTIONS}</td>

</tr>

{section name=quotes loop=$QoolMO->QoolMA->quotes}

<tr>

<td>{$QoolMO->QoolMA->quotes.quote}</td>

<td>

<a href="admin.php?siteId={$QoolRS->siteId}&amp;moduleIdAdmin={$QoolMO->moduleToEdit.id}&amp;action=del&amp;itemId={$QoolMO->QoolMA->quotes.id}">{$QoolMO->QoolMA->modLang.DELETE}</a></td>

</tr>

{/section}

</table>

<a href="?siteId={$QoolRS->siteId}&moduleIdAdmin={$QoolMO->moduleToEdit.id}&action= addQuote">Add</a>

{/if}

{/if}

This is a little bit confusing when you first look at it but Smarty is very easy to learn. Lets start from the beginning. In the first line of our code we see :

{if $QoolMO->QoolMA->msgType =='System'}

This is a typical Smarty if..else conditional statement. It is as if you were coding in PHP but for HTML. Here we check if Qool generated a message and if this is the case then display the message :

<div style="text-align:center; background-color:red; border: 1px solid silver; height:100px; width:400px;">{$QoolMO->QoolMA->Msg}</div>

If not then we go the second conditional statement:

{if $QoolRS->action=='addQuote'}

Here we check if the user generated an action with the name addQuote and if true we know that the user wants to add a new quote. So we print a form:

<form action="admin.php" method="POST" name="newQuote" >

<input type="hidden" name="siteId" id="siteId" value="{$QoolMO->siteToEdit.id}" />
<input type="hidden" name="moduleIdAdmin" id="modid" value="{$QoolMO->moduleToEdit.id}" />

<input type="hidden" name="action" id="action" value="newQuote" />

<input type=”submit” value=”{$QoolMO->QoolMA->modLang.SUBMIT}”>

</form>

Qool CMS assigns some variables to Smarty (These will be explained later). Some of these variables are:

{$QoolMO->siteToEdit.id} //The id of the site we are administrating

{$QoolMO->moduleToEdit.id} //The id of the module we use

The same values are used to any link or form inside a module to identify the site and the module we are administrating.

If the user did not generate the action “addQuote” then we list any existing quotes:

<table>

<tr>

<td>{$QoolMO->QoolMA->modLang.QUOTE}</td>

<td>{$QoolMO->QoolMA->modLang.ACTIONS}</td>

</tr>

{section name=quotes loop=$QoolMO->QoolMA->quotes}

<tr>

<td>{$QoolMO->QoolMA->quotes.quote}</td>

<td>

<a href="admin.php?siteId={$QoolRS->siteId}&amp;moduleIdAdmin={$QoolMO->moduleToEdit.id}&amp;action=del&amp;itemId={$QoolMO->QoolMA->quotes.id}">{$QoolMO->QoolMA->modLang.DELETE}</a></td>

</tr>

{/section}

</table>

<a href="?siteId={$QoolRS->siteId}&moduleIdAdmin={$QoolMO->moduleToEdit.id}&action= addQuote">Add</a>

In the above code snippet we create a table with 2 cells that hold these variables:

{$QoolMO->QoolMA->modLang.QUOTE}

{$QoolMO->QoolMA->modLang.ACTIONS}

These are variables that are loaded from the module language files.

We also see a new Smarty tag. The {section}{/section} tag which is used to list arrays. This is one of the best Smarty tags and will loop through all our quotes and list them in our table. So for example our quotes array would be a multidimensional array like this:

• Quotes

  • 0

    • id

    • quote

  • 1

    • id

    • quote