Modules Tutorial Part 4

In part 3 of this series we ended up with a multi-ingual, custom styled module. In this part we will add some Javascript to make the module interactive.

The source code for this example is available from the redaxscript-third-party repository on GitHub. Building on the previous examples, you need to add a new folder to contain scripts and by default a couple of Javascript files.

modules

example3

index.php
install.php
languages

de.php
en.php
fr.php

styles

example3.css

scripts

example4.js
startup.js

install.php

The install file is just like the previous three examples; only the module name is changed.

index.php

The loader function is extended to load the scripts in addition to the styles.

/**
 * example4 loader start
 *
 * @since 2.0.0
 * @deprecated 2.0.0
 *
 * @package Redaxscript Third Party
 * @category Modules
 * @author Gary Aylward
 */

function example4_loader_start()
{
	global $loader_modules_styles, $loader_modules_scripts;
	$loader_modules_styles[] = 'modules/example4/styles/example4.css';
	$loader_modules_scripts[] = 'modules/example4/scripts/startup.js';
	$loader_modules_scripts[] = 'modules/example4/scripts/example4.js';
}

A new function is added to make the module's language strings available to Javascript.

/**
 * example4 loader scripts transport start
 *
 * @since 2.0.0
 * @deprecated 2.0.0
 *
 * @package Redaxscript Third Party
 * @category Modules
 * @author Gary Aylward
 */

function example4_loader_scripts_transport_start()
{
	$output = languages_transport(array(
		'example4_hello',
		'example4_world',
		'example4_click_here'
	));
	echo $output;
}

There are many ways of integrating a Javascript-based module with the rest of the site. This example uses a very simple method. The index.php file contains an example4() function that simply generates the HTML code for a button with a class that can be used to link to the Javascript function. The reason for using PHP to create the button is that we can use the language array to translate the button text.

/**
 * example4
 *
 * @since 2.0.0
 * @deprecated 2.0.0
 *
 * @package Redaxscript Third Party
 * @category Modules
 * @author Gary Aylward
 *
 * @return string 
 */

function example4()
{
	return '<button type="button" class="js_example4 example4_button">' . l('example4_click_here') . '</button>';
}

Class js_example4 is used to link the button to the Javascript, class example4_button is used to apply styling to the button via the CSS in the module.

Language Files

The language files each require the addition of a translation for the button text.

en.php

<?php

/* example4 */

$l['example4_hello'] = 'Hello';
$l['example4_world'] = 'world';
$l['example4_click_here'] = 'Click here';
?>

de.php

?php

/* example4 */

$l['example4_hello'] = 'Hallo';
$l['example4_world'] = 'zusammen';
$l['example4_click_here'] = 'Hier klicken';
?>

fr.php

<?php

/* example4 */

$l['example4_hello'] = 'Bonjour';
$l['example4_world'] = 'tout le monde';
$l['example4_click_here'] = 'Cliquez ici';
?>

example4.css

/**
 * @tableofcontents
 *
 * 1. example4 button
 *    1.1 hover effect
 *
 * @since 2.0.0
 *
 * @package Redaxscript Third Party
 * @author Gary Aylward
 */

/* @section 1. example4 button */

.example4_button
{
	-moz-border-radius: 0.25em;
	-webkit-border-radius: 0.25em;
	background: #3b3b3b;
	border: 1px solid #151515;
	border-radius: 0.25em;
	color: #ccc;
	display: inline-block;
	font: bold 0.875em/2.5em arial;
	padding: 0 0.75em;
	text-align: center;
	text-decoration: none;
	text-shadow: 0 1px rgba(0, 0, 0, 0.8);
	text-transform: uppercase;
}

/* @section 1.1 hover effect */

.example4_button:hover
{
	background: #474747;
	color: #eee;
}

The CSS file contains a section for the button style, and a sub-section for the hover effect. The button is styled as a simplified version of the Redaxscript admin buttons. Sizes should be specified in ems so that everything scales with the font size selected by the user. Borders and shadows are about the only exceptions where pixel sizes are preferred.

Javascript

Note: There is a difference between Redaxscript version 1.2.1 and version 2.0.0 In version 1.2.1 (and earlier) the Redaxscript modules object is called r.module (singular) whereas in version 2.0.0 (and later) it is called r.modules (plural). This example is written for version 2.0.0 so the plural form is used. If writing for earlier versions of Redaxscript you will have to change all instances of r.modules to r.module

Redaxscript includes both jQuery and Zepto libraries. This example shows the module Javascript written as a jQuery plugin. This is a very simple example just to illustrate how to incorporate Javascript into a Redaxscript module. For more information on jQuery, see the documentation at jQuery.com

There are two Javascript files required, startup.js defines the plugin as part of the Redaxscript r.modules object and sets the value of options to be passed to the plugin. example4.js contains the actual plugin code.

startup.js

/**
 * @tableofcontents
 *
 * 1. example4
 *
 * @since 2.0.0
 *
 * @package Redaxscript Third Party
 * @author Gary Aylward
 */

/* @section 1. example4 */

r.modules.example4 =
{
	startup: true,
	selector: 'button.js_example4',
	options:
	{
		name: l.example4_world
	}
};

The start up file defines the module as r.modules.module_name and sets a number of parameters. The startup parameter causes the module to be loaded at startup. The selector parameter defines the selector that the jQuery plugin attaches to. For this example, the code will attach to a button of class js_example4 which is the class we defined in the example4() function in index.php above.

There could be any number of options for the plugin, for this example we have only one. The default value of the name is the translated "world" string.

example4.js

/**
 * @tableofcontents
 *
 * 1. example4
 * 2. startup
 *
 * @since 2.0.0
 *
 * @package Redaxscript Third Party
 * @author Gary Aylward
 */

(function ($)
{
	'use strict';

	/* @section 1. example4 */

	$.fn.example4 = function (options)
	{
		/* extend options */

		if (r.modules.example4.options !== options)
		{
			options = $.extend({}, r.modules.example4.options, options

{});
		}

		/* return this */

		return this.each(function ()
		{
			$(this).on('click', function ()
			{
				$.fn.dialog(
				{
					message: l.example4_hello + ' ' + options.name + l.exclamation_mark
				});
			});
		});
	};

	/* @section 2. startup */

	$(function ()
	{
		if (r.modules.example4.startup)
		{
			$(r.modules.example4.selector).example4(r.modules.example4.options);
		}
	});
})(window.jQuery

|| window.Zepto);

The code is written as a jQuery plugin so everything is wrapped in

(function($)
{
...
})(window.jQuery

|| window.Zepto);

The first section is the actual module function. First of all the default options are extended by any options which are passed in by the function call.

All of the real work is done in the return this.each section. This simple example has only one function, a simple onclick handler to display a dialog box. The message is composed from the translated language strings and the name value passed in.

The second section is the startup function which attaches the code to the selector and calls it with the default options.

This is a very simple example of the use of Javascript in a module. More complex examples can be found in the Redaxscript core modules.

Hopefully this series of articles has proved useful and shown how to create modules for use in Redaxscript using PHP, CSS, Javascript and the Redaxscript language system. All the example modules can be seen in use here.

No comment present.