Table of Contents

Jaws Gadgets

Here I will try to make you more familiar with the Jaws structure and in a step-by-step tutorial you will write your first gadget for Jaws. This article assumes you are familiar with PHP, SQL, a little HTML and you are using Jaws 0.6.

Developing for jaws is an absolutely straight-forward job, one of the jaws goals is to be very easy for web-site management but in the same time a fully developer-friendly project.

Jaws is entirely based on the MVC method, as maybe you know, this method will give you the most meaning of the “Developer will develop & Designer will design”, it means that you as a developer will develop your own gadgets without any worry about the design limitations.

After this tutorial you will have a Quote gadget, that will show a quote by random from the database.

You could get the Quote source code from http://www.iranamp.com/data/files/Quote.tar.gz

Gadget's Structure

If you want to be familiar with the gadget’s structures have a glimpse on the Skeleton gadget, this gadget like it’s name gives you an overview of the necessary skeleton for a jaws gadget to be implemented by jaws gadget’s manager, As maybe you realized these files are very important:

GadgetInfo.php, GadgetModel.php and GadgetHTML.php. We will be more familiar with this files and their roles in a gadget through this tutorial.

Developing Started

Let’s start with the QuoteInfo.php, in this file you should specify your gadget’s properties like it’s version, the required jaws version to work properly, ACL Keys and ….

class QuoteInfo extends JawsGadgetinfo 
{ 
	/** 
	 * Set the Quote gadget information 
	 * 
	 * @access public 
	 */ 
	function QuoteInfo() 
	{ 
		parent::Init('Quote'); 
		$this->GadgetName(_t('QUOTE_NAME')); 
		$this->GadgetDescription(_t('QUOTE_DESCRIPTION')); 
		$this->GadgetVersion('0.1.0'); 
		$this->RequiresJaws('0.6.0'); 
		 
		// Acls's 
		$this->ACLKey('/ACL/gadgets/Quote/default', 
					  _t('QUOTE_ACL_ADMIN')); 
		$this->ACLKey('/ACL/gadgets/Quote/AddQuotes', 
					  _t('QUOTE_ACL_ADD')); 
		$this->ACLKey('/ACL/gadgets/Quote/ModifyQuotes', 
					  _t('QUOTE_ACL_EDIT')); 
		$this->ACLKey('/ACL/gadgets/Quote/DeleteQuotes', 
					  _t('QUOTE_ACL_DELETE')); 
		 
		$this->Requires('ControlPanel'); 
	} 
}

This is an absolutely simple file, just somethings that should be mentioned here are:

  • _t(): This function is the Jaws translator, you should pass this function the name of the constant that contains the treated message. You should have all these strings in a file named like the gadget name in the specific folder of the language. for example we have QUOTE_NAME in the “Quote.php”; that is in the “en” sub-folder of languages that you should create in your gadget’s directory. try to don’t hard-code the strings into the source code, you always should read them from the language files, this will helps a lot the jaws localization.
  • ACL Keys: These options are for specifying the access levels of users to the different sections of a gadget, for example you want the user “A” be able to add new quotes but the user “B” doesn’t have this ability and just be able to delete the quotes and so on…. You are free to put unlimited limitations, but surely you should handle all of them!

Well, now let’s work with QuoteModel.php, that is the responsible of Model section of the MVC method, where you should put the logic of your gadget.

class QuoteModel extends JawsModel 
 
{
 
	/**
 
	 * Initialize the model
 
	 *
 
	 * @access public
 
	 */
 
	function QuoteModel()
 
	{
 
		$this->_Name = 'Quote';
 
	}

This is the first part, extending JawsModel.

Surely one of the most important parts of a gadget, is it’s installation process, It’s where you should use InstallGadget function.

You should check all of the parameters that your gadget want to work properly, in some cases like the Skeleton we have not an installation, for example your gadget just want to give the user some information about the Jaws total posts, in such these cases it’s not necessary to have an InstallGadget function in the model section, you could simply use this function in the view section and make it to simply returns true.

But in some cases like the banner gadget, because the user want to upload images, you should verify the write access in the directories, and in some other cases you want to work with the DB, it’s where you should create your tables.

One of the most improvements in the 0.6 is that Jaws using MDB2 as it’s Database Abstraction Layer, and one of the greatest features of MDB2 for more portability is keeping the tables structures in an XML file.You are able to create your tables with the special XML tags, for more information about these, have a look at: http://www.backendmedia.com/MDB2/docs/xml_schema_documentation.html

Have a look at the current.Quote.xml that is in the schema subfolder of the Quote directory to be more familiar with it’s structure.

After installing the Jaws, the other codes is not such depended on Jaws behaviors, it’s PHP codes that are responsible of gadget’s working.

After that we should have a look at QuoteHTML.php, where you should make the output data.

class QuoteHTML extends JawsGadgetHTML 
 
{
 
	/**
 
	 * Constructor
 
	 *
 
	 * @access public
 
	 */
 
	function QuoteHTML()
 
	{
 
		$this->Init('QuoteModel');
 
		// Add actions
 
		$this->NormalAction('DefaultAction');
 
		
 
		$this->LayoutAction('Display',
 
				    _t('QUOTE_ACTION_DISPLAY'),
 
				    _t('QUOTE_ACTION_DISPLAY_DESC'));
 
 
 
			
 
		$this->AdminAction('Admin');
 
		$this->AdminAction('AddQuotes');
 
		$this->AdminAction('SaveAddQuotes');
 
		$this->AdminAction('EditQuotes');
 
		$this->AdminAction('SaveEditQuotes');
 
		$this->AdminAction('DeleteQuotes');
 
	}

The constructor is very important, here you should define various gadget’s actions, like Normal Actions that simply works, without any HTML returns, the Layout Actions that are responsible for Viewing the output to the user, and admin actions that are for the gadgets admininstration.

To be continued …

 
  /var/www/wiki/htdocs/data/jaws/development/gadgets/writegadgets.txt · Last modified: 2007/11/02 16:27