Author Archive

One of interesting novelty of Java6 is a possibility to access compiler via special API.
Let’s look on this feature a bit closer.

In order to have an access to compilation subsystem we should use classes located at javax.tools package [http://java.sun.com/javase/6/docs/api/javax/tools/package-summary.html].
In the future in this package possibly appear classes to work with different external utilities,
but at this moment we have only access to the compiler.

As simple example let’s look on request to compile:

	JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();

	Iterable<SimpleJavaFileObject> srcList =  Arrays.asList(new SimpleJavaFileObject[]{
		new SimpleJavaFileObject(URI.create(”string:///myclass.java”), Kind.SOURCE) {

			@Override
			public CharSequence getCharContent(boolean ignoreEncodingErrors) {
				return “class myclass {}”;
			}
		}
	});
       JavaFileManager fileManager = compiler.getStandardFileManager(null, null, null);
       compiler.getTask(null, fileManager, null, null, null, srcList).call();

Let’s try to understand how it’s work:

The compiler access input data not directly but via objects inherited form JavaFileObject.
Therefore depending on needs of developer information for compilation can be received from any place:
network, file, memory; for that we need to implement successor of JavaFileObject.
It is better to do it by inheriting class-gag SimpleJavaFileObject

In our example implementation of SimpleJavaFileObject returns source of class as constant string.

It is slightly harder with output data. There is another abstraction layer called JavaFileManager that is
object factory per se.

Standard file manager that we receive in our example let us work with files on the disk. If you need to place output data
on the network on in the memory you need to override JavaFileManager. It is better to do it inheriting
ForwardingJavaFileManager, this class retarget request to provided during creation file manager.
At the same time you can handle only those request that you need.

Last string of example creates compilation command and execute it at once. As a result of execution we have file
in the execution directory of example with name myclass.class that contains bytecode of appropriate class.

It is noteworthy that classloaders of system know nothing about existence of given class and so call
Class.forName(“myclass”) throws ClassNotFoundException.
Let’s complete our example to get class bytecode as byte array. For that we need to implement our own file manager:

public class JavaMemFileManager extends ForwardingJavaFileManager {

	class ClassMemFileObject extends SimpleJavaFileObject {
		ByteArrayOutputStream os = new ByteArrayOutputStream();

		ClassMemFileObject(String className) {
			super(URI.create("mem:///" + className + Kind.CLASS.extension), Kind.CLASS);
		}
		byte[] getBytes() {
			return os.toByteArray();
		}

		@Override
		public OutputStream openOutputStream() throws IOException {
			return os;
		}
	}

	private HashMap<String, ClassMemFileObject> classes =
			new HashMap<String, ClassMemFileObject>();

	public JavaMemFileManager() {
		super(ToolProvider.getSystemJavaCompiler().getStandardFileManager(null, null, null));
	}

	@Override
	public JavaFileObject getJavaFileForOutput(Location location,
			String className, Kind kind, FileObject sibling) throws IOException {
		if (StandardLocation.CLASS_OUTPUT == location && JavaFileObject.Kind.CLASS == kind) {
			ClassMemFileObject clazz = new ClassMemFileObject(className);
			classes.put(className, clazz);
			return clazz;
		} else {
			return super.getJavaFileForOutput(location, className, kind, sibling);
		}
	}

	public byte[] getClassBytes(String className) {
		if (classes.containsKey(className)) {
			return classes.get(className).getBytes();
		}
		return null;
	}
}

As you see our file manager override method getJavaFileForOutput that complier calls to receive output file object.
Here we check destination, for new classes it should be StandardLocation.CLASS_OUTPUT and type.
If it correspond to newly compiled class then we create new file object: we save it and pass it to the compiler.
Then we can receive access to the bytecode with method getClassBytes(className) passing the name of the class.

Let us change previous example to use new functionality:

	....
	JavaFileManager fileManager = new JavaMemFileManager();
	compiler.getTask(null, fileManager, null, null, null, srcList).call();

	byte[] myClassBytes = ((JavaMemFileManager)fileManager).getClassBytes(“myclass”);
	….

And yet one feature of example execution in our case will be absence of file on the disk.

Finally I made a library that makes easier access to Java6 Compiler API.
See details on: [ http://opensource.helion-prime.com/jruntime/ ]

0. go through basic Joomla! documentation

Joomla! Beginners guide: [http://docs.joomla.org/Beginners]

Joomla developer network: [http://dev.joomla.org/]
which includes very useful:
Joomla framework API: [http://api.joomla.org/]
Joomla! tutorials on Wiki: [http://dev.joomla.org/component/option,com_jd-wiki/Itemid,32/]

Joomla! forum: [http://forum.joomla.org]

1. project structure

It is useful during development to keep the code in only one place. You can easy use this structure with your
IDEs [http://en.wikipedia.org/wiki/Integrated_development_environment] and VCS [http://en.wikipedia.org/wiki/Version_control_system]

It is recommended to use next structure:

project-root
	com_component
		site
			...
			lang
				...
				en-GB.com_component.ini
				de-DE.com_component.ini
			component.php
		admin
			...
			lang
				...
				en-GB.com_component.ini
				de-DE.com_component.ini
			admin.component.php
			install.sql
			uninstall.sql
		component.xml
	mod_module
		...
		lang
			...
			en-GB.mod_module.ini
			de-DE.mod_module.ini
		module.php
		module.xml
	plg_plugin
		...
		lang
			...
			en-GB.plg_group_plugin.ini
			de-DE.plg_group_plugin.ini
		plugin.php
		plugin.xml
	tpl_temlate
		template.xml
	...

After creation of project structure prepare installation packages with help of Joomla! tutorials and install them to Joomla!.
We will work with local installation (or dedicated server in your LAN) because another variants decries performance of developers.

After extensions installation process change files of extensions installed to Joomla! with GNU/Linux symbolic links
[http://en.wikipedia.org/wiki/Symbolic_link] or Windows Vista symbolic links [http://en.wikipedia.org/wiki/NTFS_symbolic_link]
of your project files.
Note: Don’t forget to use option “Options +FollowSymLinks” for Apache web-server for directory where your Joomla!
installed to use symbolic links.

In Joomla! filenames of extensions has special structure. In mentioned structure names of corresponding extensions in
filenames and directories replaced with words component, module, and plug-in.
The word group in files of plugin replaces name of group to which plug-in relate to [content, editors, search, system, user].
Every group defines set of events on which plug-in will be triggered.

Ready to use project has following structure of relations: (<== symbol means symbolic link)

PRJ-ROOT/COM_COMPONENT/SITE <== J_ROOT/COMPONENTS/COM_COMPONET
PRJ-ROOT/COM_COMPONENT/SITE/LANG/en-GB.com_component.ini <== J_ROOT/LANGUAGE/en-GB/en-GB.com_component.ini
PRJ-ROOT/COM_COMPONENT/SITE/LANG/de-DE.com_component.ini <== J_ROOT/LANGUAGE/de-DE/de-DE.com_component.ini

PRJ-ROOT/COM_COMPONENT/ADMIN <== J_ROOT/ADMINISTRATOR/COMPONENTS/COM_COMPONET
PRJ-ROOT/COM_COMPONENT/ADMIN/LANG/en-GB.com_component.ini <== J_ROOT/ADMINISTRATOR/LANGUAGE/en-GB/en-GB.com_component.ini
PRJ-ROOT/COM_COMPONENT/ADMIN/LANG/de-DE.com_component.ini <== J_ROOT/ADMINISTRATOR/LANGUAGE/de-DE/de-DE.com_component.ini

PRJ-ROOT/MOD_MODULE <== J_ROOT/MODULES/MOD_MODULE
PRJ-ROOT/MOD_MODULE/LANG/en-GB.mod_module.ini <== J_ROOT/LANGUAGE/en-GB/en-GB.mod_module.ini
PRJ-ROOT/MOD_MODULE/LANG/de-DE.mod_module.ini <== J_ROOT/LANGUAGE/de-DE/de-DE.mod_module.ini

PRJ-ROOT/PLG_PLUGIN/plugin.php <== J_ROOT/PLUGINS/GROUP/plugin.php
PRJ-ROOT/PLG_PLUGIN/LANG/en-GB.plg_group_plugin.ini <== J_ROOT/ADMINISTRATOR/LANGUAGE/en-GB/en-GB.plg_group_plugin.ini
PRJ-ROOT/PLG_PLUGIN/LANG/de-DE.plg_group_plugin.ini <== J_ROOT/ADMINISTRATOR/LANGUAGE/de-DE/de-DE.plg_group_plugin.ini

As you see languages files of plug-ins installed to administration part of Joomla!. Why so we should ask Joomla! developers.

2. internationalization (i18n)

Most of extensions require internationalization. This mechanism is simple to use in Joomla!, but it has some ambiguous decisions.

To use internationalization support of text messages in the code of extensions instead of output of simple strings we should
use next construction: JText::_(’text message’);
This call check current locale and using appropriate localization file returns required string.

For instance if current locale is ‘en-GB’ then it seek for appropriate file:
for “site part” of Joomla!: joomla-root/language/en-GB/en-GB.com_component.ini
and in that file I look for sting with id ‘TEXT MESSAGE’

If it can’t find appropriate file then it returns passed string.

Structure of localization file:
identifier=value

identifier – is a string, it should be written in UPPER CASE.
Value – is a localized value.

Example:
We need to output 2 internationalized strings
echo JText::_(’This is test message.’);
echo JText::_(’Hello world.’);

Then we create localization file for appropriate locale
en-EN.com_component.ini:
THIS IS TEST MESSAGE=This is test message.
HELLO WORLD.=Hello all.

de-DE.com_component.ini:
THIS IS TEST MESSAGE=Das ist testen Meldung.
HELLO WORLD.=Halo eine Welt.

I want to note that in order to use that mechanism for plug-ins you should invoke method loadLanguage of class Jplugin:

loadLanguage(
[name of localization file],
[path to root directory of site part of admin part of Joomla!]

name of localization file, by default plg_group_plugin.ini
path to root directory, can be: “j_root/administrator” or “j_root” (by default)

3. layouts

Layouts is a handy mechanism which let us to avoid using of “if construction” in “view” of the MVC model
[http://en.wikipedia.org/wiki/Model-view-controller] which Joomla! 1.5 began to use actively for extensions development.

By default structure of extensions presentation in Joomla (for modules, and components) has next structure:

EXTENSION-ROOT
	VIEWS
	   VIEW
               TMPL
		 default.php
	     view.html.php

Here “view.html.php” file is a common part of presentation which can commonly contains invocations of “model” (MVC)
or in other words where we extract data that necessary for data output, and some simple logic.
There is a rule to place mature logic to model or controller(MVC).
In the “TMPL” directory we keep different presentations. They contain markup or in other words exact presentation of data.
An file “default.php “ is a default layout, so it will be used if we wasn’t selected another one.
You can easily create additional layouts adding them to ‘TMPL’ directory files with name “layoutname.php”.
In order to select specific layout you should in the controller(MVC) before invocation of display() function
select its name with command: JRequest::setVar(’layout’, ‘layoutname’);

4. using of AJAX

It is hardy to imagine an application that can be developed nowadays without AJAX. [http://en.wikipedia.org/wiki/Ajax_%28programming%29]

It is much easier to use some javascript library like jquery, mootols, dojo, etc.. to invoke Ajax-based methods.
I like jquery [http://jquery.com]. However Joomla! Developers have selected another Javascript library – mootols [http://mootools.net] and so I earnestly recommend to you to use for ajax methods invocations Mootools library.
If you anyway want to use your favorite JavaScript library you must switch your library to the compatibility mode.
For instance for Jquery it can be do it with:
var jq = jQuery.noConflict();
then instead of ‘$’ you should use ‘jq’ but anyway keep in mind that most of extensions for JavaScript libraries don’t use that mode and so you will have Javascript error because of name collisions.

Example of MVC flow using Ajax invocation:
- Create task in the controller, ex.: getAjaxData

	“controller.php”:
	function getAjaxData() {
		JRequest::setVar('view', 'viewname');
		JRequest::setVar('layout', 'ajaxlayout');

		parent::display();
	}

- Create layout, ex: ajaxlayout

	“viewname/tmpl/ajaxlayout.php”:
	<?php defined('_JEXEC') or die('Restricted access'); 

	global $mainframe;
	echo <ajax data>;	

	$mainframe->close();
	?>

Important note:
You should add invocation: $mainframe->close();
in order to create output flow or it will add Joomla! standard page after result of you Ajax method.
Thus creating concrete layout you can pass any data, don’t forget to setup appropriate header.
For XML [http://en.wikipedia.org/wiki/Xml] it can be: header(”Content-type: text/xml;charset=utf-8″);

On client-side yous should make invoke defined method using Ajax call, using URL like:
JURI::root().’index.php?option=com_component&task=getajaxdata’;

5. mapping of tables to the Database

Joomla! using simple ORM system [http://en.wikipedia.org/wiki/Object-relational_mapping].
In order to use this mechanism you should describe your DB structure with sets of objects that inherit JTable.

For example:
foo.php:

<?php
defined('_JEXEC') or die('Restricted access');

class TableFoo extends JTable {
	var $id = null;
	var $bar = null;

	function TableFoo(& $db) {
		parent::__construct('#__foo', 'id', $db);
	}

	function bind( $from, $ignore=array() ) {
		$from['bar'] = strtoupper($from['bar']);
		return parent::bind($from, $ignore);
	}

	function check() {
		if (empty($this->bar)) {
			$this->setError( ‘Error message’);
			return false;
        		}
		return true;
	}	

	function delete( $oid=null ) {
		$res = parent::delete($oid);

		// here if you need you can define mechanism
		// to delete linked tables
		return $res;
    	}
}
?>

First of all it is necessary to define public variables that corresponding to fields names of table.
Then you should pass name of the table and name of primary key to the constructor.

key methods:

Bind() method using in order to transfer data from external sources (ex.: requst) into object.
Overriding that method you can execute specific data transformations of data before adding to the fields of the object.

Check() method make checking of data in the fields, for example it can check that fields not empty or filled with required range of values, etc.

Delete() method can add specific behavior during deletion of records. For example deleting of linked records.

Also JTable class contains set of other handy methods overriding which you can add appropriate specific behavior.
See Joomla! documentation for details.

possible use:

You can get object in the model (MVC) with following: $row =& $this->getTable(’foo’);

to delete record you invoke: $row->delete($id)

to store record to db:
$row->bind($data);
$row->check();
$row->store();

If then you need get value of primary key you can simply take the value from the object: $row->id;

Surely it is better to add to described calls check of result of methods executions.

sidebar and widgets

Sidebar – is an area that take place on the left or on the right from main area. Usually on sidebar placed blog common or quick access elements. This elements called widgets.
Common examples: authors, tags, categories, etc.

In the world of WordPress widget is a plugin subtype. That is activation/deactivation of widgets realized thru the control panel of plug-ins.

Status control of widgets managed in the Design/Widgets panel. There you can add/remove widgets from/to sidebar and change their parameters.

1. How to add new widget

Since widget is plug-in it is behavior like common plug-in in WordPress. In other words it is php-script which placed in directory/subdirectories “/wp-content/plugins”. For correct information representation widget(plug-in) should has header like above:

/*
Plugin Name: Simple Wordpress Sidebar Widget
Plugin URI: http://open.helion-prime.com/Simple-Wordpress-Sidebar-Widget
Description: Simple wordpress sidebar widget.
Version: 1.0
Author: Helion-Prime Solutions Ltd.
Author URI: http://helion-prime.com/
*/

‘Plugin Name’ field described symbolic plug-in name in the system.
‘Plugin URI ‘ contains link to plug-in description.
‘description’ description.
‘version’ version
‘Author’ author name
‘Author URI’ uniform resource identifier

In the upshot in order to add new widget to the system we should:
create file “simple-sidebar-widget.php”
add to file described header
copy file to directory “/wp-content/plugins”

Then in the plug-in control panel we have new plug-in with our name:
‘Simple Wordpress Sidebar Widget’

simple-sidebar-widget.php

<?php
/*
Plugin Name: Simple Sidebar Widget
Plugin URI: http://open.helion-prime.com/Simple-Wordpress-Sidebar-Widget
Description: Simple wordpress sidebar widget.
Version: 1.0
Author: Helion-Prime Solutions Ltd.
Author URI: http://helion-prime.com/
*/
?>

2. Plug-in registration

In the first step we have added simplest plug-in (but not widget yet)
In order to transform it to the widget, we should register it.

Code for sidebar registration:

function simple_sidebar_widget_content_gen($args) {
}

function simple_sidebar_widget_register() {
	if (!function_exists('register_sidebar_widget')) {
			return;
	}

	register_sidebar_widget(__('Simple Sidebar Widget ', 'simple-sidebar-widget'),
		'simple_sidebar_widget_content_gen');
}

add_action('init', 'simple_sidebar_widget_register');

To work widget should contain at least 2 functions:
*initialization (here simple_sidebar_widget_register)
*content generation (here simple_sidebar_widget_content_gen)

To get control in the our code we should create hook on some event. We have 2 events to select from. In our case I have selected ‘init event’ (raised when system loaded and initialized).
Hook created with help of add_action function, as parameter to it passed ‘name of event’ (init) and name of handler function (simple_sidebar_widget_register).

If event raised function simple_sidebar_widget_register receive control and perform following actions:
*check possibility to create widget with help of accessibility of widget registration function – function_exists(’register_sidebar_widget’).
* if required function is accessible it register widget

As you see register_sidebar_widget function receive 2 parameters:
first contain localized name of widget in the widget control panel.
second link to functionality of content-generator (’simple_sidebar_widget_content_gen’).

Now we have full-fledged widget that can be viewed in the widget control panel, it can be added to sidebar (don’t forget to activate it in the plug-in control panel).

3. Representation

If you add our widget to the sidebar it will not show anything. To find any result :) you should add function of content generation in the following way:

function simple_sidebar_widget_content_gen($args) {
	extract($args);

	$title = __('Simple Sidebar Widget ', 'simple-sidebar-widget');
	$widget_content = __('This is simple sidebar widget', 'simple-sidebar-widget');

	echo $before_widget ;
	echo $before_title . $title . $after_title;
	echo '<p>'.$widget_content .'</p>';
	echo $after_widget;
}

First thing that we do is from array of arguments of function that extract variables we create set of variables.

Mainly it is special variables that should be used. Then we create content of widget: in fixed order we output values of special(which contain basic widget markup) and defined variables.

Now we can see our widget on sidebar.

4. Widget setup

If you want to have possibility to setup widget you should change code to the following:

function simple_sidebar_widget_control_gen($widget_content, $show_content) {
?>
<p>
	<label for="widget-content"><?php _e('Content:', 'simple-sidebar-widget'); ?>
		<input class="widefat"
			id="widget-content" name="widget-content"
			type="text" value="<?php echo attribute_escape($widget_content); ?>"
		/>
	</label>
</p>
<p>
	<label for="show-content">
		<input class="checkbox" type="checkbox"
			id="show-content" name="show-content"
			<?php echo $show_content ? 'checked="checked"' : ''; ?>
		/>
		<?php _e('Show content.', 'simple-sidebar-widget'); ?>
	</label>
</p>
<input type="hidden"
	   id="simple-sidebar-widget-submit" name="simple-sidebar-widget-submit"
	   value="1"/>
<?php
}

function simple_sidebar_widget_control() {
	$options = $newoptions = get_option('simple_sidebar_widget');

	if ($_POST['simple-sidebar-widget-submit']) {
			$newoptions['widget-content'] = strip_tags(stripslashes($_POST['widget-content']));
			$newoptions['show-content'] = isset($_POST['show-content']);
	}

	if ($options != $newoptions) {
		$options = $newoptions;
		update_option(’simple_sidebar_widget’, $options);
	}

	simple_sidebar_widget_control_gen(
		$options['widget-content'], $options['show-content']);
}

function simple_sidebar_widget_content_gen($args) {
	extract($args);

	$title = __(’Simple Sidebar Widget ‘, ’simple-sidebar-widget’);

	$options = get_option(’simple_sidebar_widget’);
	$show_content = $options['show-content'] ? true : false;
	$widget_content =empty($options['widget-content']) ?
		__(’This is simple sidebar widget’, ’simple-sidebar-widget’) :
		$options['widget-content'];

	echo $before_widget ;
	echo $before_title . $title . $after_title;
	if ($show_content) {
		echo ‘<p>’.$widget_content .’</p>’;
	}
	echo $after_widget;
}

function simple_sidebar_widget_register() {
	if (!function_exists(’register_sidebar_widget’)) {
			return;
	}

	register_sidebar_widget(__(’Simple Sidebar Widget ‘, ’simple-sidebar-widget’),
		’simple_sidebar_widget_content_gen’);
	register_widget_control(__(’Simple Sidebar Widget ‘, ’simple-sidebar-widget’),
		’simple_sidebar_widget_control’);
}

What changed in our code:

In function ’simple_sidebar_widget_register’ one invocation added (’register_widget_control’), it register function which catch widget configuration change event (’simple_sidebar_widget_control’).

In the generator of widget content additional code added that receives current configuration of widget get_option(’simple_sidebar_widget’).
Here parameter ’simple_sidebar_widget’ is identifier of parameters set that used in our widget.
Then into variables $show_content and $widget_content extracted current values of parameters.

As I already noted for event processing of configuration changes we should add appropriate event-handler function (’simple_sidebar_widget_control’). In this function we extract parameters from request and analyze changes, also this function create content of configuration form (this functionality moved to ’simple_sidebar_widget_control_gen’).

After we added above code in the parameters of widget we have 2 fields.
One field contains content that should be outputted.
Second field is a switch which allow/forbid output of content.

In closing I want to note that widgets work only with themes that support sidebar.
Described methodology work for WordPress >=2.5, although it is almost the same for previous versions.

related links:
plug-in development - http://codex.wordpress.org/Writing_a_Plugin
list of actions - http://codex.wordpress.org/Plugin_API/Action_Reference
localization: http://codex.wordpress.org/Translating_WordPress