Sunday, 22 November 2015 20:20

Building Joomla modules - Part 2: Configuration

Written by 
Rate this item
(0 votes)

mod_tksdfractionslider.xml

This is our “manifest” we are going to put there all configuration setting and file is going to be big! Have a look at GitHub repositories to see full mod_tksdfractionslider.xml . Lets have a look inside this file.

First it declares XML version and encoding. Then we have our extension type which in our case is module, version, client=”site” ( this is frontend module ) as oppose to client=”administrator” for backend modules. method=”upgrade” it is important, otherwise it will wipe out all data if this module had been previously installed on the system.

 

?xml version="1.0" encoding="UTF-8"?>
<extension type="module" version="1.6" client="site" method="upgrade">
	<name>tksdfractionslider</name>
	<author>Tomasz Kisielewski</author>
	<creationDate>August 2014</creationDate>
	<copyright>Copyright (C) 2014 Tomasz Kisielewski / tkstudiodesign</copyright>
	<license>http://www.gnu.org/licenses/gpl-3.0.txt GNU/GPLv3 </license>
	<authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail>
	<authorURL>http://www.tkstudiodesign.com</authorURL>
	<version>1.0</version>
	<description>TKSD fractionslider.A joomla responsive image slider module.</description>	

See GitHub

 

This part is pretty self explanatory and there is no need to spend time on it. Second part of our manifest is about files structure:

       <files>
		<filename>mod_tksdfractionslider.xml</filename>
		<filename module="mod_tksdfractionslider">mod_tksdfractionslider.php</filename>
		<filename>helper.php</filename>
		<filename>index.html</filename>
		<folder>tmpl</folder>
		<folder>assets</folder>
		<folder>language</folder>
	</files>	

See GitHub

This is basically list of files and directories. We have three main files mod_tksdfractionslider.xml ( configuration file ), mod_tksdfractionslider.php ( main module file), helper.php ( useful stuff goes here ) and don't forget to add empty index.html. Presence of this file prevents web server from listing directories and files. Index.html should be placed within every directory. Folders are: /tmp for templates, /assets place for css styles and javascript, /language contains translated translation strings. Only requirements is that module must include translation for English language.

         <config>
		<fields name="params">
			<fieldset name="basic">
				<field name="load_jquery" type="radio" default="1" label="Enable jQuery?" description="Turn on or off inlcuded jQuery. Will also call in a noconflict script.">
					<option value="1">Yes</option>
					<option value="0">No</option>
				</field>				
			</fieldset>

See GitHub

This is begin of our configuration section. Configuration is wrapped inside config tag and we have sets of fieldsets and fields. Above lines of codes produces output as on image below.

 

 

There are few fieldsets: basic, moreoptions, advanced, images etc. Correspond to general slider settings , fractionslider plugin options ( http://jacksbox.de/stuff/jquery-fractionslider/plugin-options-reference/ )

 

 

 

Below how I made these options into XML document. Have a look how it is made. Joomla's beauty is in simple configuration xml files which are readable and easy to maintain. After you get familiar with xml configuration, you will discover how easy is to add extra options to your template, or convert other plugins into Joomla!

 

 

			<fieldset name="moreoptions" label="More Slider Options">
				<field name="fullWidth" type="radio" default="1" label="Enable Full Width?" description="Enable full width">
					<option value="1">Yes</option>
					<option value="0">No</option>
				</field>
				<field name="controls" type="radio" default="1" label="Enable Controls?" description="Enable slider controls">
					<option value="1">Yes</option>
					<option value="0">No</option>
				</field>
				<field name="pager" type="radio" default="1" label="Enable Pager?" description="Enable Pager">
					<option value="1">Yes</option>
					<option value="0">No</option>
				</field>
				<field name="responsive" type="radio" default="1" label="Responsive" description="Enable responsive slider">
					<option value="1">Yes</option>
					<option value="0">No</option>
				</field>
				<field name="pauseOnHover" type="radio" default="1" label="Pause on hover" description="Pauses slider on hover">
					<option value="1">Yes</option>
					<option value="0">No</option>
				</field>
				<field name="backgroundAnimation" type="radio" default="0" label="Background Animation" description="Background Animations">
					<option value="1">Yes</option>
					<option value="0">No</option>
				</field>
				<field name="increase" type="radio" default="1" label="Increase" description="if set, slider is allowed to get bigger than basic dimensions">
					<option value="1">Yes</option>
					<option value="0">No</option>
				</field>
				<field name="pager" type="radio" default="1" label="Pager" description="Pager">
					<option value="1">Yes</option>
					<option value="0">No</option>
				</field>
				<field name="dimension1" type="text" default="1500" label="Width" description="Width"/>
				<field name="dimension2" type="text" default="850" label="Height" description="Height"/>
				<field name="slideTransitionSpeed" type="text" default="2000" label="Slide Transition Speed" description="Slide Transition Speed in miliseconds"/>
			</fieldset>	

See GitHub

Image below presents this tab in Joomla module manager. We will use these values later in our php files.

 

 

XML is very good choice for defining configuration settings although sometimes can become hard to read because of its size and nested complexity.

Next tab is Images and Captions. It is the biggest part because consist all detailed settings for every caption! It is a bit intimidating but most of it is just list options for jQuery animations. Please pay attention to naming conventions it is important when you work with php later on. Now I just show you small part of this section. We have two snippets of configuration for two images.

<fieldset name="images" label="MOD_TKSDFRACTIONSLIDER_IMAGES_LABEL">
				<field name="image1" type="media" directory="stories" label="Image 1"/>
				<field name="image1alt" type="text" default="" label="Alt tag"/>			
				<field name="image1cap1" type="textarea" default="" label="Image 1 caption 1" description="Caption for first image" filter="raw"/>
				<field name="image1cap1BackgroundColor" type="color" default="red" label="MOD_TKSDFRACTIONSLIDER_CAP1_BG_COLOR_LABEL" description="MOD_TKSDFRACTIONSLIDER_CAP1_BG_COLOR_DESCRIPTION" />
				<field name="image1cap1dataEaseIn1" type="list" default="easeOutBounce" label="MOD_TKSDFRACTIONSLIDER_EASE_IN" description="MOD_TKSDFRACTIONSLIDER_DATA_EASE_IN_DESCRIPTION">
					<option value="linear">linear</option>
					<option value="swing">swing</option>
					<option value="easeInQuad">easeInQuad</option>
					<option value="easeOutQuad">easeOutQuad</option>
					<option value="easeInOutQuad">easeInOutQuad</option>
					<option value="easeInCubic">easeInCubic</option>
					<option value="easeOutCubic">easeOutCubic</option>
					<option value="easeInOutCubic">easeInOutCubic</option>
					<option value="easeInQuart">easeInQuart</option>
					<option value="easeOutQuart">easeOutQuart</option>

See GitHub

It is worth noting translation string which we translate later in en-GB.mod_tksdfractionslider.ini file.

<fieldset name="images" label="MOD_TKSDFRACTIONSLIDER_IMAGES_LABEL">

as you can see names are organized image1 – image1cap1(for caption first) - image1cap1BackgroundColor( background color for caption first etc ) and for next image image2- image2cap1 - image2cap1BackgroundColor .

<field type="spacer" name="myspacer" hr="true" />			
				<field name="image2" type="media" directory="stories" label="Image 2"/>
				<field name="image2alt" type="text" default="" label="Alt tag"/>
				<field name="image2cap2" type="textarea" default="" label="Image 2 caption 1" description="Caption 1 for second image" filter="raw"/>
				<field name="image2cap2BackgroundColor" type="color" default="red" label="MOD_TKSDFRACTIONSLIDER_CAP1_BG_COLOR_LABEL" description="MOD_TKSDFRACTIONSLIDER_CAP1_BG_COLOR_DESCRIPTION" />
				<field name="image2cap2dataEaseIn2" type="list" default="easeOutBounce" label="MOD_TKSDFRACTIONSLIDER_EASE_IN" description="MOD_TKSDFRACTIONSLIDER_DATA_EASE_IN_DESCRIPTION">
					<option value="linear">linear</option>
					<option value="swing">swing</option>
					<option value="easeInQuad">easeInQuad</option>
					<option value="easeOutQuad">easeOutQuad</option>

See GitHub

I think you got “the pattern”. The last final bit of our xml file is advanced tab

<fieldset name="advanced">
				<field name="layout" type="modulelayout" label="JFIELD_ALT_LAYOUT_LABEL"
				description="JFIELD_ALT_MODULE_LAYOUT_DESC"/>
				<field name="moduleclass_sfx" type="text" label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
				description="COM_MODULES_FIELD_MODULECLASS_SFX_DESC"/>
				<field name="cache" type="list" default="1" label="COM_MODULES_FIELD_CACHING_LABEL"
				description="COM_MODULES_FIELD_CACHING_DESC">
					<option value="1">JGLOBAL_USE_GLOBAL</option>
					<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
				</field>
				<field name="cache_time" type="text" default="900" 
				label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
				description="COM_MODULES_FIELD_CACHE_TIME_DESC"/>
				<field name="cachemode" type="hidden" default="itemid">
					<option value="itemid"></option>
				</field>
			</fieldset>
		</fields>
	</config>
</extension>

See GitHub

This code creates tab advanced like on image below.

 

 

Of course we have to end config and extension tab for XML document to be valid. Next stop: PHP files, "proper" module stuff.

 

 

 

 

 

 

 

 

Read 1067 times