What is « com_module »

Is a Joomla module extender, this Joomla component help the developer/users to add Ajax views in modules.

It's a long work to add ajax views in Joomla if a component don't provide itself the view you need, com_module simple add an entry point to permit the extention, render of all the views you want add to your modules with no more work and can resole many specific needs.You can work with the full MVC structure or only use a simple file structure for little needs (a json response for eg.)

Why using this solution ?

The system is done to remove the need of hacks, complex modification, help and simplify your work.

No need to add special codes to do it work. Use the same type of model as a real Joomla component.

Your Module Language file are loaded by the component all your jText are working.

The main URL params are SEF , Only your own variables are not SEF.

The main view can be added in the joomla menu as an entry point.

This mean you can set template and syle, menu page title for each main module view.

You can use raw output, json, html why not PDF.

All plug-in can be added if you add the right calls in your module extension.

 Download Com_module.zip

How to call my module new views?

Simply use this link to call it

in case of module mod_sample, the naming is sample, the url is :

index.php?option=com_module&view=sample

Of course you can add your own variables in url but only use this reserved variable :

view,module, module_id, task and layout, for a standard usage, in the URL.

How to implement the module extender in your modules ?

For the tutorial we use « mod_sample » as module name

at start we have this files (most always needed) in a module.

JoomlaROOT/modules/mod_sample Folder & structure

-> mod_sample.php (the main entry)

-> mod_sample.xml(the parameter file)

\tmpl Folder

-> default.php (default module layout file)

this is really the basic structure.



Now simple add the file in your module root.
(JoomlaROOT/modules/mod_sample Folder)

The minimal file to add is controller.php


This file must include this lines on a standard way :

<?php
// No direct access.
defined('_JEXEC') or die;

jimport('joomla.application.component.controller');
// this is the main controller from module named sample
class sampleController extends JController
{
 public function display($cachable = false, $urlparams = false)
{
// your code here
 } 
}



I dont wan't make a full course of MVC, only display you the differences.

You can use another Class extends as all standard components.

NOTE : For a little project, ajax, json render you have not always to add all this files comming after this

 

What is changing in MVC?

So to say, only some class naming and views structure.

You have not to learn another framework, you can use joomla. Only a little helper to get modules params is used not more.

The folder structure is same as joomla components :

(from module root)

\controllers (all none default controllers)
\models (your models)
\views ( the views)
controller.php (main controller)

The file structure is same for default controller no 'mod_xxxx' as name but the name itself :

eg. for default controller, model, view and tmpl files in case of mod_sample name is sample :

controller.php

\models\sample .php

\views\sample \index.html.php

\views\sample \tmpl\default.php



The Class naming refer to the module component, its why the naming change with prefix 'module' (and to prevent classname duplicates)

\models\sample .php classname is moduleModelSample

\views\sample\index.html.php classname is moduleViewSample

For default controller, no more changes.



Using non default view & controllers(Advanced users)

I wanted to have allmost the same usability as in a component. So you can addd more controllers, view models ….

So the task , layout are managed(with joomla) but the naming is a little different for « extra » view and controller

Say, we want add a secondary controller/view structure with this url. options

'view=sample&module_id=94&task=article.edit&layout=form'

the task use the Joomla way to call a secondary controller. In joomla this call the article controller with edit task and use the layout form.



The need files, for com_module(and in joomla), in your module folder mod_sample.

In JoomlaROOT/modules/mod_sample Folder

\controllers\article.php

\models\article.php

\views\sample_article\index.html.php

\views\sample_article\tmpl\form.php



But the file naming/class change a little :

article controller classname is sampleControllerArticle (no change)
article model classname is moduleModelSample_article
the view index.html.php classname is moduleViewSample_article

(in case of joomla real components : eg.sampleControllerArticle, sampleViewArticle ...)

the url follow joomla new convention but you can use :
'view=sample_article&module_id=94&task=edit&layout=form'

Joomla Template overides

Because 'com_module' is used as component entry all the templates overide are to be included in the com_module folder.

 In case of beez5 for the sample, default layout the file destination is
JoomlaROOT\templates\beez5\html\com_module\sample\default.php

For the sample module, secondary article controller using form layout
JoomlaROOT\templates\beez5\html\com_module\sample_article\form.php

It's the same logic but the overide are always in the temaplte com_module component folder.

Reserved variables

this url parameters are used by com_module, you can use it but do not change it, to prevent errors :

view Set the name of the module (eg. view=sample for module mod_sample)

module_id Set the module_id (you can get this value on your standard module mod_sample .php file php variable is $module->id

Can be usefull for different template choice, or module options

task Set the task&controller as new joomla convention

layout Set the layout (render different layout from one view for eg.)



Provided Helper function

moduleHelper::getModule()); // get modules infos
moduleHelper::getParams());// get saved module options from XML

in case of using : 'index.php?option=com_module&view=sample&module_id='.$module->id

you get all the info from the module caller, if not then you get the infos from first published modules info in the joomla #__module table.



Know limits

Please do not use module names with underscores to prevent naming collision.

table creation are not included as in a standard component.



Copyrights

Copyright (C) Studio42 France 2012. All rights reserved.
License GNU General Public License version 2 or later; see LICENSE.txt
You don't have the right to remove Author/license/weblink from com_modules component files and packages.



For an advanced need, implementation, you can mail me at contact[At]st42.fr