Sunday, 22 November 2015 20:17

Building Joomla Modules - Part 3: Core module files

Written by 
Rate this item
(0 votes)

In this article I am going to demonstrate "core" module files. There are three important files. First two are located within module folder ( mod_tksdfractionslider.php and helper.php ) another is inside /tmp folder and its name is default.php ( it is our view ). Lets start from main module entry point which is in our case mod_tksdfractionslider.php.

<?php
/**
 * @package TKSD Fraction slider for Joomla 3+
 * @version 1.0.0
 * @author Tomasz Kisielewski
 * @copyright (C) 2014- tkstudiodesign
 * @website http://www.tkstudiodesign.com 
 * @license http://www.gnu.org/licenses/gpl-3.0.txt GNU/GPLv3
**/

defined('_JEXEC') or die; //add stylesheet $doc =& JFactory::getDocument(); require_once(dirname(__FILE__).'/helper.php'); $moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx')); $listofimages = mod_tksdfractionsliderHelper::getImages($params); mod_tksdfractionsliderHelper::load_jquery($params); $doc->addStyleSheet(JURI::base(true) . '/modules/mod_tksdfractionslider/assets/css/fractionslider.css', 'text/css' ); $doc->addStyleSheet(JURI::base(true) . '/modules/mod_tksdfractionslider/assets/css/style.css', 'text/css' ); $doc->addScript(JURI::base(true) . '/modules/mod_tksdfractionslider/assets/js/jquery.fractionslider.js'); require(JModuleHelper::getLayoutPath('mod_tksdfractionslider'));

We have typical php tag at the beginning of the file, followed by our header with all information about author, copyrights, licensing ect. Next we have very important line:

defined('_JEXEC') or die;

This checks if it is invoked within Joomla! environment not from outside, by checking if _JEXEC is defined. If not it stops execution, well..dies. Then we get document:

$doc=& JFactory::getDocument();

Next step is get helper.php file with its methods

require_once(dirname(__FILE__).'/helper.php);

As you know Joomla allows us to add additional suffixes for our module. It helps generally with styling. This way you can add additional class, but remember to add leading space! We escape user input with php function htmlspecialchars().

$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

In next step we create list of our images ( and captions ) We create variable $listofimages which is array populated by function from our helper file.

$listofimages = mod_resliderHelper::getImages($params);

Another function from our helper which basically loads jquery based on our xml configuration settings.

mod_resliderHelper::load_jquery($params);

Last part is very important. We attache css styles and jquery files for plugin. These files are what we downloaded with our plugin. If you want to attach more files, do it here.

$doc->addStyleSheet(JURI::base(true) . '/modules/mod_tksdfractionslider/assets/css/fractionslider.css', 'text/css' );

$doc->addStyleSheet(JURI::base(true) . '/modules/mod_tksdfractionslider/assets/css/styleDEF.css', 'text/css' );

$doc->addScript(JURI::base(true) . '/modules/mod_tksdfractionslider/assets/js/jquery.fractionslider.js');

Last bit for calling default view for our module.

require(JModuleHelper::getLayoutPath('mod_tksdfractionslider'));

HELPER

helper.php

This is where real fun begins. In this file we placed all our logic. As usually I put at the beginning licensing, author information and our “magic” _JEXEC sentence.

 

abstract class mod_tksdfractionsliderHelper{
	
	public static function getImages(&$params){	
	$imgsAndCaps = array(); 
	$i = 1;
	while($i < 10):
	
	if($params->get('image'.$i)){
		$step= $i;
		$sliderImage=JURI::root().$params->get('image'.$i);
		$imageAlt=$params->get('image'.$i.'alt');
		$captionOne=$params->get('image'.$i.'cap'.($i));
		$captionOneBGcolor=$params->get('image'.$i.'cap'.($i).'BackgroundColor');
		$captionOneAnimation=$params->get('image'.$i.'cap'.($i).'dataEaseIn'.($i));
		$captionOnePosX=$params->get('image'.$i.'cap'.($i).'dataPositionX'.($i));
		$captionOnePosY=$params->get('image'.$i.'cap'.($i).'dataPositionY'.($i));
		$captionOneDataIn1=$params->get('image'.$i.'cap'.($i).'dataIn'.($i));
		$captionOneDataOut1=$params->get('image'.$i.'cap'.($i).'dataOut'.($i));
		$captionTwo=$params->get('image'.$i.'cap'.($i+1));

See GitHub We create abstract class tksdfractionsliderHelper ( abstract means we cant create object of this class) and within class we declare two methods. First is

static function getImages(&$params)

For our image and captions which is called from mod_tksdfractionslider.php ( line:16)

$listofimages = mod_tksdfractionsliderHelper::getImages($params);

and another is:

static function load_jquery(&$params)

This method is responsible for jQuery plugin configuration options and like previous one is called from main module file

mod_tksdfractionsliderHelper::load_jquery($params);

I think you got picture, helper.php is like "storage" file where we create all required stuff and use it somewhere elase. Ok lets talk about first method which is getImages static function. We pass params as arguments.

class mod_resliderHelper{

 

public function getImages(&$params){

$imgsAndCaps = array();

$i = 1;

while($i < 10):

if(($params->get('image'.$i))&& ($params->get('image'.$i.'cap'.$i) || $params- >get('image'.

$i.'cap'.($i+1)) || $params->get

('image'.$i.'cap'.($i+2)))){

….

….

….

Lets talk about first method getImages(&$params). It accepts $params as partameters. First we create array to store our configuration options and assign it to variable $imgsAndCaps.

 

$imgsAndCaps = array();

 

Because we have more than one image, to make processing easier we added number to names ( I have already mentioned about naming conventions in this module like image1cap1BackgroundColor what is background color for caption first etc). For doing so we need to have our “step” variable $i which is initialized to one.

 

$i = 1;

 

Secondly we are using while block to set up data for 10 images ( you may change it as you wish )

 

while($i < 10):

 

next we are doing some checking. I have decided that for this slider to work we need image

 

if(($params->get('image'.$i))&& .....

 

and at least one caption, doesn't matter which one.

 

… $params->get('image'.$i.'cap'.$i) || $params->get('image'.$i.'cap'.($i+1)) || $params->get

('image'.$i.'cap'.($i+2)))){ …..

 

$params->get('nameOfParameter') is how you get parameters from XML configuration file ( mod_tksdfractionslider.xml ). How it works is simple. If we take first image, $i is equal to 1, we have $params->get('image'.$i.'cap'.$i) equal to “image1cap1” in our XML file ( <field name="image1cap1"...), 'image'.$i.'cap'.($i+1) gives us <field name="image1cap2" type=.....

This “if” statement is where I enforced my rule of presence image and at least one caption. After statement returns true we age going to use variable $i, what means that will be incremented every loop ( All configuration options will be this way connected to one particular image (image+$i).

 

Now we are assigning values from mod_tksdfractionslider.xml to variables.

 

$sliderImage=JURI::root().$params->get('image'.$i);

$captionOne=$params->get('image'.$i.'cap'.($i));

$captionOneBGcolor=$params->get('image'.$i.'cap'.($i).'BackgroundColor');

$captionOneAnimation=$params->get('image'.$i.'cap'.($i).'dataEaseIn'.($i));

$captionOnePosX=$params->get('image'.$i.'cap'.($i).'dataPositionX'.($i));

$captionOnePosY=$params->get('image'.$i.'cap'.($i).'dataPositionY'.($i));

$captionOneDataIn1=$params->get('image'.$i.'cap'.($i).'dataIn'.($i));

$captionOneDataOut1=$params->get('image'.$i.'cap'.($i).'dataOut'.($i));

$captionTwo=$params->get('image'.$i.'cap'.($i+1));

$captionTwoBGcolor=$params->get('image'.$i.'cap'.($i+1).'BackgroundColor');

$captionTwoAnimation=$params->get('image'.$i.'cap'.($i+1).'dataEaseIn'.($i+1));

$captionTwoPosX=$params->get('image'.$i.'cap'.($i+1).'dataPositionX'.($i+1));

$captionTwoPosY=$params->get('image'.$i.'cap'.($i+1).'dataPositionY'.($i+1));

$captionTwoDataIn2=$params->get('image'.$i.'cap'.($i+1).'dataIn'.($i+1));

$captionTwoDataOut2=$params->get('image'.$i.'cap'.($i+1).'dataOut'.($i+1));

$captionThree=$params->get('image'.$i.'cap'.($i+2));

$captionThreeBGcolor=$params->get('image'.$i.'cap'.($i+2).'BackgroundColor');

$captionThreeAnimation=$params->get('image'.$i.'cap'.($i+2).'dataEaseIn'.($i+2));

$captionThreePosX=$params->get('image'.$i.'cap'.($i+2).'dataPositionX'.($i+2));

$captionThreePosY=$params->get('image'.$i.'cap'.($i+2).'dataPositionY'.($i+2));

$captionThreeDataIn3=$params->get('image'.$i.'cap'.($i+2).'dataIn'.($i+2));

$captionThreeDataOut3=$params->get('image'.$i.'cap'.($i+2).'dataOut'.($i+2));

 

That all variables related to single image. Using $i variable we don't have to repeat this step 10 times as we deal with ten images. We are still “within the loop”, now we place all our variables for this iteration into array, where all data related to image1 will be inside array $imgsAndCaps[1], related to image number to inside $imgsAndCaps[2].

 

$imgsAndCaps[$i]=array(

"image"=>$sliderImage,

"caption1"=>$captionOne,

"caption1BackgroundColor"=>$captionOneBGcolor,

"caption1Animation"=>$captionOneAnimation,

"captionPositionX1"=>$captionOnePosX,

"captionPositionY1"=>$captionOnePosY,

"caption1DataIn1"=>$captionOneDataIn1,

"caption1DataOut1"=>$captionOneDataOut1,

"caption2"=>$captionTwo,

"caption2BackgroundColor"=>$captionTwoBGcolor,

"caption2Animation"=>$captionTwoAnimation,

"captionPositionX2"=>$captionTwoPosX,

"captionPositionY2"=>$captionTwoPosY,

"caption2DataIn2"=>$captionTwoDataIn2,

"caption2DataOut2"=>$captionTwoDataOut2,

"caption3"=>$captionThree,

"caption3BackgroundColor"=>$captionThreeBGcolor,

"caption3Animation"=>$captionThreeAnimation,

"captionPositionX3"=>$captionThreePosX,

"captionPositionY3"=>$captionThreePosY,

"caption3DataIn3"=>$captionThreeDataIn3,

"caption3DataOut3"=>$captionThreeDataOut3,

);

The last bits of this method are, incrementing our $i variable by one:

$i++;

Close our while loop

endwhile;

and of course we need to return our $imgsAndCaps variable, which is an array.

return $imgsAndCaps;

We get all this bunch of images and options when we call this method in mod_tksdfractionslider.php

$listofimages = mod_resliderHelper::getImages($params);

The last method of this class is for inclusion javascript files, check version of installed Joomla and acts accordiongly.

public function load_jquery(&$params){

if($params->get('load_jquery')){

JLoader::import( 'joomla.version' );

$version = new JVersion();

if (version_compare( $version->RELEASE, '2.5', '<=')) {

$doc = &JFactory::getDocument();

$app = &JFactory::getApplication();

$file=JURI::root(true).'/modules/mod_tksdfractionslider/assets/js/jquery-1.9.0.min.js';

$file2=JURI::root(true).'/modules/mod_tksdfractionslider/assets/js/noconflict.js';

$doc->addScript($file);

$doc->addScript($file2);

} else {

JHtml::_('jquery.framework');

}

}

}

}

 

default.php

 

This file is a “view” for our module. It contains HTML, CSS classes, javascript mixed with our configuration variables. It is located in /tmp directory and starts with standard sentences package, licensing, visioning, author information and “magic” _JEXEC statement.

 

<?php

/**

* @package TKSD Fraction slider for Joomla 3+

* @version 1.0.0

* @author Tomasz Kisielewski

* @copyright (C) 2014-2016- tkstudiodesign

* @website http://www.tkstudiodesign.com

* @license GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html

**/

 

defined('_JEXEC') or die;

 

?>

 

Before we start codding php is worth to look at pure html file, which is in our downloaded fractionslider package ( fractionslider/example/index.html )

You can see that there are setting which are easy to replace with php code and Joomla! parameters.

We use similar structure, but not that many images. I leave room for you to improve this module. After all if you get how it is done in Joomla, you will be able to work and experiment with any jquery slider trying to fit it into your needs.

<div class="slider">
  <div class="fraction-slider">
  <div class="fs_loader"></div>
  	<?php
  	foreach($listofimages as $key => $value){?>
        <div class="slide" data-in="fade">
       <?php if(isset($listofimages[$key]["caption1"])){?>
        <p class="teaser small" style="background-color:<?php echo $listofimages[$key]["caption1BackgroundColor"];?>; width:20% !important;" data-position="<?php echo $listofimages[$key]["captionPositionX1"];?> ,<?php echo $listofimages[$key]["captionPositionY1"];?>" data-in="<?php echo $listofimages[$key]["caption1DataIn1"]; ?>" data-out="<?php echo $listofimages[$key]["caption1DataOut1"]; ?>" data-step="1" data-ease-in="<?php echo $listofimages[$key]["caption1Animation"];?>" data-delay="500"><?php echo $listofimages[$key]["caption1"]; ?> </p><?php } ?>   
        <?php if(isset($listofimages[$key]["caption2"])){?>

 

TO BE CONTINUED.....SOON

 

 

Read 739 times