How to build a moduleTable of contents
So you want to create your own eFront module and extend the system's functionality to your own needs? This tutorial will help you learn all there is about the eFront modules system and will enable you to create your own module in a series of easy steps. All that is required from you is:
The rest is up to your creativity, imagination and programming skills.
Quick startQuick step-by-step guide for creating a simple module, called "Simple module":
What next?You can either continue reading this guide, or install the "Demo module" from http://www.efrontlearning.net/mods, which makes use of all the functions available inside a module. Enjoy!
Just a little theoryeFront modules are based on the extension of an abstract base module class. The returned values of these methods are used by the core eFront system to display and manage your module. Some of those methods are mandatory, while others might be used or not. If your module does not use them, then they will return the default values as defined in the base class and the system will know that they have not been implemented for this module. Therefore, define only mandatory derived methods and only the derived methods that are required by your module in order to avoid unnecessary problems. Avoid touching anything else! If you are an experienced programmer, then you might figure out pretty easily how to write a module by reading the following chapter and studying the methods of the modules.class.php file, where the module base class exists. No matter what, take a look at the step-by-step tutorial below. Let’s get started! Defining the module.xml manifestWe assume that you have downloaded and setup eFront and that you have a brillian idea for an eFront module. Great! The first thing to do is write an XML description file called module.xml to describe your module. <?xml version="1.0"?> <module> <title>Any title for the module</title> <author>For vanity reasons mainly</author> <date>For historians to know</date> <version>The version of your module</version> <description>A free-text description of the module</description> <className>the PHP class of the module – beware not to leave unintentionally spaces</className> </module> The className is the only of the six aforementioned fields that is mandatory and that actually matters (ok, if you insist, the author one as well). Defining the className.class.php fileThe className tells eFront that the base class of your module will be called className and will be defined in a file called className.class.php. For example, the module.xml manifest file for the sample module "frequently asked questions" is as follows: <?xml version="1.0" ?> <module> <title>Frequently asked questions </title> <author>Me</author> <date>Today which is the 24/02/2008</date> <version>1.214 beta </version> <description>Module letting users find out FAQ for a lesson</description> <className>module_faq</className> </module> and should define the class module_faq in a file called module_faq.class.php. Note: This file as any other defined should use UTF-8 encoding. Moreover, the definition of your class should be set to extend the abstract global class for eFront called eFrontModule. This is done as follows: module_faq.class.php <?php
class module_faq extends EfrontModule {
// … Definition of the class here
}
?>
Note: the base class header file should NOT be included. The base class you write should define two basic functions defined as “abstract” in the basic class:
which should return a string with how your module should be called. This shouldn’t necessary be the title you have defined in the module.xml file.
This function should return an array with all eFront roles that are involved in the module, meaning that they are to interact somehow with the module’s interface. The possible roles are strings: “administrator”, “professor” and “student”. A sample implementation of those basic two functions, for a module called (with className) module_best_student, which shows the name of the student with the best grade in a lesson to its professor, would be the following: module_best_student.class.php <?php
class module_best_student extends EfrontModule {
public function getName() {
return “Best Lesson Student”;
}
public function getPermittedRoles() {
return array("professor");
}
}
?>
If the students were also to see who the best student is, then the getPermittedRoles() function would change as: getPermittedRoles method public function getPermittedRoles() {
return array("professor", “student”);
}
Well, believe it or not, this is all that is required for you to create the basis of your module. You needn’t even define a constructor class. (Note: Actually you shouldn’t define a constructor class). In fact, if you do not need to add or alter any table structures in the eFront database for your module to function correctly, then you might as well install the module right away. Of course, if no other methods are implemented, the module won’t do anything, but it will be recognized by eFront and you would be able to view the changes on your code on the eFront system, since programming in blind is always risky. Before we move on to the installation part, we will have a brief discussion on how to incur any changes to the database. Changing the eFront databaseYou may define your module to setup the eFront database in three occasions: during its installation, its uninstalling and during system upgrade. The methods used for this reason are onInstall, onUninstall and onUpgrade respectively. Database setup methods //What should happen on installing the module
public function onInstall() {
eF_executeNew("CREATE TABLE module_faq
id int(11) NOT NULL auto_increment,
lessons_ID int(11) not null,
question text not null,
answer text not null,
PRIMARY KEY (id)");
return true;
}
// ... and on uninstalling the module
public function onUninstall() {
eF_executeNew("DROP TABLE module_faq;");
return true;
}
Note: Function eF_executeNew is a utility wrapper eFront DB-function that allows you to directly execute SQL queries on the eFront database. Make use of it! Installing the moduleAfter optionally designating the database setup functions (and even more significantly the onInstall one), we suggest you install the module right away. Installation can take place from the administrator menu, namely from the “Modules” option at the administrator control panel. To install a module:
Note: It is suggested that the zip file has the same className as your module, in order to avoid any collision problems of modules with the same name.
Note: If a module exists in the system with the same className, then your module will not be installed. Solution: Change the className Note: If the your module cannot be installed maybe there is a problem with the database script (if you provided one) Now, if the module has been correctly installed, it should appear on the list of modules on the administrator module page. You can edit your module’s code by going to the www/modules/ folder, opening your own module folder and editing or inserting the files you want (or only the className.class.php one). Making the module do somethingTo this point, we have installed a module that doesn’t do anything, so it might as well all seem like a waste of time. Not at all! In fact, we have let eFront know of a new unique module class called className and take it into account for all pages of the roles returned by the getPermittedRoles() method array defined there. Moreover, we (optionally) have changed the underlying database for our module to function correctly. So, we can start making the module do something. The easiest way to do that is open the module.class.php file and have a look at the methods provided for implementation. These can be divided into the following categories: Main - independent module page(s)These methods trigger the appearance and functionality of the module page(s) that should appear as stand-alone on the right hand side frame of the eFront system window. Links to these pages could be defined as explained in the 5.2 Link methods section and their urls should all begin with the $this->moduleBaseUrl string. This leads to the first golden rule of eFront modules: Rule I: Any URLs related with your module’s main-independent pages should begin with the $this->moduleBaseUrl string. Note: The $this->moduleBaseUrl is defined by the eFront system during runtime - NOT by you. You should therefore use it without defining it.
Write the code to be executed by the main pages of your module. This means that every time that a connection is made to a module related url (starting with $this->moduleBaseUrl as defined by Rule 1), this function will be called. This method returns pure HTML code or true if smarty is being used. Obviously, more than one independent pages might be displayed with this function.
Return the filename of the smarty template file that might be used by one or more of the getModule() appearing pages. If getSmartyTpl() returns false, then eFront will understand that no smarty template has been used. Sample implementation of getModule() method: public function getModule() {
if ($_GET[‘module_operation’] == “insert”) {
// … do what needs for insertion
insertFunc($_GET[‘data’]);
// show page for insertion with pure full HTML code
return “<html><body>
<table><tr><td>Insertion ok</td></tr></table>
</body></html>”;
} else if ($_GET[‘module_operation’] == “update”) {
// … do what needs for update
update($_GET[‘data’]);
// show page for update just with a part of HTML code
return “<table><tr><td>Update ok</td></tr></table>”;
} else if ($_GET[‘module_operation’] == “delete”) {
// … do what needs for delete
delete($_GET[‘data’]);
// Use smarty (view module.tpl file below) to display the page
// This means that for this case, function getSmartyTpl() should not
// return false, as it does in every other case
$smarty = $this -> getSmartyVar();
$smarty -> assign(“T_MY_MODULE_MESSAGE”, “Delete ok”);
return true;
} else {
// show pure full HTML code for the main module page
return “<table>
<tr>
<td><img src = ‘“.$this->moduleBaseLink.“images/logo.png’ /></td>
<td>Main module page</td>
</tr>
</table>”;
}
}
// Smarty is only used if module_operation header is equal to delete
public function getSmartyTpl() {
if ($_GET[‘module_operation’] == “delete”)
{
$smarty = $this -> getSmartyVar();
$smarty-> assign("T_MY_MOD_BASEURL", $this -> moduleBaseUrl);
$smarty-> assign("T_MY_MO_BASELINK", $this -> moduleBaseLink);
$smarty-> assign("T_MY_M_BASEDIR" , $this -> moduleBaseDir);
return $this -> moduleBaseDir . "module.tpl";
} else {
return false;
}
}
module.tpl file in the root of the module directory {*Smarty template*}
<table>
<tr>
<td><img src=“{$ T_MY_MO_BASELINK}images/del.jpeg“ / ></td>
<td>
<a href =“{$ T_MY_MOD_BASEURL}&module_operation=delete&data=…”> Delete another</a>
</td>
<td>
{$T_MY_MODULE_MESSAGE}
</td>
</tr>
</table>
Understanding this example means that you have the entire eFront modules system figured out. Let’s make some observations here: a) The getModule() method returns 4 (at least – since we have “else”) pages executing different code according to the $_GET variables set. Speaking of $_GET variables let’s have a look at the second golden rule of eFront modules: Rule II: You might have your pages using any $_GET/$_POST variables you like except from ‘ctg’ and ‘op’ b) In 3 out of the 4 cases, pure HTML code is returned which will be printed as is. Take notice that the $this->moduleBaseDir is used to denote the module directory path. However, the path for the image file logo.png in folder images is referenced with the $this->moduleBaseLink variable. This leads to the third golden rule of eFront modules. Rule III: The root of your module extracted folder is stored as the $this->moduleBaseDir variable. Any further paths inside that directory may be referenced normally. The URL location of this folder is stored in the $this->moduleBaseLink variable. This means that the path on the hard disk of the file my_photo.png inside the photos folder of the module directory should be referred to as: $this->moduleBaseDir . “photos/my_photo.png” However, the url of this file is: $this->moduleBaseLink . “photos /my_photo.png” Therefore, if you want to link to an image file you will have to use the following syntax: echo “<img src = ‘“.$this->moduleBaseLink.“ photos /my_photo.png’ />”; Note: The “/” character is included in both $this->moduleBaseDir and $this->moduleBaseLink variables. Not that you need to know that, since these variables are automatically defined for you, but just for better clarifying the distinction of the aforementioned variables:
$this->moduleBaseUrl is something like:
“http://localhost/efront/www/professor.php?ctg=module&op=my_module”
$this->moduleBaseDir is something like (for a Windows installation):
“C:\xampp\htdocs\efront\www\modules\my_module\”
$this->moduleBaseLink is something like:
“http://localhost/efront/www/modules/my_module/”
c) In the 4th case smarty is used. The global smarty variable is received from the eFront system with the getSmartyVar() method and is used normally. No HTML code is returned by the getModule() function. However, the getSmartyTpl() method returns the filename of the template file to be used for that scenario, thus explaining to the system that smarty is being used in this case. d) Finally, have a look at how the smarty template file still makes use of the $this->moduleBaseUrl, $this->moduleBaseLink and $this->moduleBaseDir variables as defined by rules 1 and 3. Note: These variables can be assigned to the global smarty object, as it is done in the getSmartyTpl() function of the example above, and be used by the template. However, make sure as a good practice to use smarty variable names that include your module’s class name, so as to ensure uniqueness. The smarty object is the same for the entire eFront system and for all modules. Thus using general names like “T_MODULE_BASELINK” or “T_USER” or “LESSON” might conflict with existing variables with various results on the system. For a module called “best_module” you could alternatively use “T_BEST_MODULE_BASELINK” or “T_BEST_MODULE_USER” or “BEST_MODULE_LESSON”.
Module linksMethods related to module links are used to make links appear for the module, meaning to the module’s pages or to any other pages in the system the module author wants to.
This method returns an array of arrays of links that lets the system know of the way and the menu in which new links will appear on the left hand sidebar of eFront. The main structure is the following: array ( menu id => link array ), where:
Let’s explain each of those fields:
 If “Other” is set as menu id, then: - the title of the new menu should also be provided in a field called “title” - the links of the new menu should be provided in a field called “links” Note: Up to 8 new custom eFront menus may be defined. If more than these are used, then all links of “Other” menu id will be put under the “Modules” menu.
Now let’s see a sample implementation of the sidebar links method: //Sample implementation of getSidebarLinkInfo () method
public function getSidebarLinkInfo () {
$currentUser = $this -> getCurrentUser();
// If a professor he should see a link in the lessons menu
if ($currentUser -> getType() == "professor") {
$link_of_menu_lessons = array (
'id' => 'other_link_id1',
'title' => “Lesson link title”,
'image' => $this -> moduleBaseDir . 'images/image16',
'eFrontExtensions' => '1',
'link' =>$this -> moduleBaseUrl."&module_operation=lesson_related")
return array (‘lessons’ => array ($link_of_menu_lessons) );
// ... and if an admin he should see a link in the users menu and in a newly defined menu
} else if ($currentUser -> getType() == “administrator”) {
//link using relative path to the eFront images folder
$link_of_menu_users = array (
'id' => 'users_link_id1',
'title' => “Users link title”,
'image' => 'images/16x16/pens.png',
'link' => $this->moduleBaseUrl."&module_op=user_related");
$link_of_menu_other = array (
'id' => 'other_link_id1',
'title' => “Other link title”,
'image' => 'images/16x16/pens',
'eFrontExtensions' => '1', //no extension provided up
'link' => $this -> moduleBaseUrl."&module_op=user_related");
return array (‘users’ => array ($link_of_menu_users),
‘other’ => array (‘title’ => “Module menu”,
‘links’=> array ($link_of_menu_other)));
}
}
The sample should be self – explanatory. Just note again the how variables $this -> moduleBaseUrl and $this -> moduleBaseDir are used, and how the module urls do not use ‘ctg’ or ‘op’ (but in this case “module_op”). These three observations indicate how the three golden rules are applied in this case as well.
This method returns an array of arrays of links that lets the system know of any new links on the administrator control panel of eFront. Most of the fields as the link of the previous chapter are provided here as well, namely ‘title’, ‘image’ and ‘link’. The ‘id’ and ‘eFrontExtensions’ are not used. //Sample implementation of Admin's control panel link (as used on the RSS module)
public function getCenterLinkInfo() {
$optionArray = array('title' => 'RSS',
'image' => $this -> moduleBaseLink.'images/rss32.png',
'link' => $this -> moduleBaseUrl);
$centerLinkInfo = $optionArray;
return $centerLinkInfo;
}
This method returns an array of arrays of links that lets the system know of any new links on the professor or student lesson control panel. Most of the fields as the link of the previous chapter are provided here as well, namely ‘title’, ‘image’ and ‘link’. The ‘id’ and ‘eFrontExtensions’ are not used. //Sample implementation of a Lesson's control panel link (as used on the Wiki module)
public function getLessonCenterLinkInfo() {
$currentUser = $this -> getCurrentUser();
if ($currentUser -> getRole($this -> getCurrentLesson()) == "professor") {
return array('title' => _WIKI_WIKI,
'image' => $this -> moduleBaseDir.'images/eFrontWiki32.png',
'link' => $this -> moduleBaseUrl);
}
}
This method returns an array of links that defines the navigational links that appear on the top navigation row when module pages are displayed. These links are divided by default with the “>>” character. Only ‘title’ and ‘link’ fields are provided. Sample implementation of getNavigationLinks () method public function getNavigationLinks() {
return array ( array ('title' => "Main Page" ,
'link' => $this -> moduleBaseUrl),
array ('title'=> “Sub Page 1",
'link' => $ths -> moduleBaseUrl ."&mod_op=sub"));
}
This method defines how left sidebar links might be highlighted according to current (module related) url. It returns the ‘id’ of the link that should be highlighted, as this id was defined in the getSidebarLinkInfo() method. Sample implementation of getLinkToHighlight () method public function getLinkToHighlight() {
if (isset($_GET['management'])) {
return 'management_link';
} else {
return ‘default_module_link';
}
}
We assume here that links with id 'management_link' and ‘default_module_link' have been defined. Lesson modulesMethods related lesson modules have to do with sub-windows that may appear on the current lesson control panel for professors and students. They work in the exact same way as the “Main – Independent module pages”, meaning that either pure HTML code is returned and printed or a smarty template file is defined. The picture above shows a snapshot of a typical professor lesson control panel, denoting with red color the places where module related links or frames might be put. The corresponding methods are the following:
This method is very important because it characterizes a module as a lesson module thus letting the system know that this module should be included in lesson related functionalities. For example, this method lets administrators activate – deactivate lesson modules from the eFront Lesson Administration menu, though this module may not have the “administrator” role in the permitted roles array. This method returns true of false.
This method does the same thing as the getModule() function for main module pages. It might distinguish between user roles to create and display different pages to professors and students, while it can be used in conjunction with getLessonSmartyTpl() to define a smarty template file.
May optionally define a smarty template file for the lesson module. Otherwise should return false, or not be defined at all. Note: Lesson modules must be activated for each lesson from the lesson administration page by the administrator or one of the lesson’s professors. Control panel modulesMethods related to administrator control panel modules have to do with sub-windows that may appear on the main administrator control panel. They work in the exact same way as the “Main – Independent module pages” or the “Lesson modules” meaning that either pure HTML code is returned and printed or a smarty template file is defined. The picture above shows a snapshot of a typical administrator control panel, denoting with red color the places where module related links or frames might be put. The corresponding methods are the following:
This method does the same thing as the getModule() function for main module pages. It might distinguish between user roles to create and display different pages to professors and students, while it can be used in conjunction with getControlPanelSmartyTpl() to define a smarty template file.
May optionally define a smarty template file for the lesson module. Otherwise should return false, or not be defined at all. Setting module environmentThe eFront module’s system offers further possibilities for increasing the appearance customization and functionalities of modules. This is accomplished with methods that allow you to define a ‘css’ file for your module, a ‘js’ file or language files. New featureseFront has extended module class to allow blocks of modules to be displayed in specific pages in the platform. So module blocks can now be displayed in user's dashboard page, in course catalog page (aboove the course list) and as a separate page just after a user logs in the platform. Corresponding funtions for these operations are: - getDashboardModule() - getDashboardSmartyTpl() - getCatalogModule() - getCatalogSmartyTpl() - getLandingPageModule() - getLandingPageSmartyTpl() Since getLandingPageModule function is implemented, "Redirect user after login to:" setting (that is located in System settings-> Appearance) fills in with an option for this module. When this module is selected eFront redirects users to this page after login. Files1
|
|||||||||||||||
