J1.5

Using the JToolBar class in the frontend

From Joomla! Documentation

Revision as of 06:36, 8 July 2011 by Enav (talk | contribs) (syntax error on adminForm)

The "J1.5" namespace is an archived namespace. This page contains information for a Joomla! version which is no longer supported. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

Anyone whom has used the very useful JToolbarHelper class in an administration component has probably already realised that there is nothing quite so useful for the frontend. The good news is that we can create our own very simply using the JToolbar class.

First lets create the helper class. I tend to make a different helper class for each component as they will each have a different toolbar. I like to keep all my helpers in the administration end as they can often be used for both sides of the component. So firstly create a helpers directory in your component.

/administrator/components/com_yourcom/helpers

and create a file called toolbar.php

The following is an example of a very simple toolbar helper class. Copy and paste this into your toolbar.php file. Don't forget to change 'yourcom' to the name of your component. Notice also that we've included the Jtoolbar class at the top of the file.

 // no direct access
 defined('_JEXEC') or die('Restricted access');
 jimport('joomla.html.toolbar');
 
 class YourcomHelperToolbar extends JObject
 {	
 	function getToolbar() {
 		
 		
 		$bar =& new JToolBar( 'My Toolbar' );
 		$bar->appendButton( 'Standard', 'new', 'New Record', 'new', false );
 		$bar->appendButton( 'Separator' );
 		$bar->appendButton( 'Standard', 'delete', 'Delete Record', 'delete', false );
 		
 		
 		return $bar->render();
 	
 	}
 	
 }

Lets look at this code. When the 'getToolbar' function is called it creates a new instance of the JToolbar class.

 $bar =& new JToolBar( 'Associations Toolbar' );

We can then add buttons to this object.

 $bar->appendButton( 'Standard', 'new', 'New Record', 'new', false );

The first parameter is the button type. have a look a the JToolbar or JButton docs for a full list of these.

The second parameter is the class to apply to the button ( this will help us to apply an image to it as in the backend )

The third parameter is the text to display on the button.

The fourth is the task to set. When the button is pressed the javascript submitButton function is called and the hidden field 'task' is set to this value. We will see this later in our template file.

The fifth states whether a selection must be made from an admin list before continuing.

we then simply return our bar object.


We now have a choice of where to render this bar object. You can create it in a view and apply it to a template if you wish. I personally prefer to render it in the entry point file. In this example this would be yourcom.php and would look something like this. Notice that we have also included our helper file here.

 // no direct access
 defined('_JEXEC') or die('Restricted access');
 
 // Require the base controller
 require_once (JPATH_COMPONENT.DS.'controller.php');
 
 // Require specific controller if requested
 if($controller = JRequest::getVar('controller')) {
 	require_once (JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php');
 }
 
 // Component Helper
 jimport('joomla.application.component.helper');
 
 
 // Load the toolbar helper
 require_once( JPATH_COMPONENT_ADMINISTRATOR.DS.'helpers'.DS.'toolbar.php' );
 
 // render the toolbar on the page. rendering it here means that it is displayed on every view of your component.
 echo YourcomHelperToolbar::getToolbar();
 
 // Create the controller
 $classname	= 'YourcomController'.$controller;
 $controller = new $classname( );
 
 // Perform the Request task
 $controller->execute( JRequest::getVar('task'));
 
 // Redirect if set by the controller
 $controller->redirect();

Having created this the toolbar you created should render on the page but there are a few more things we need to do to make it work. We need to ensure that every view template page has an admin form for the submitButton function to work.

 <form action = "index.php" method =  "post" id = "adminForm" name = "adminForm" />
 
 <input type = "hidden" name = "task" value = "" />
 <input type = "hidden" name = "option" value = "com_yourcom" />
 </form>

Now when one of the buttons is clicked the submitbutton function will set the hidden field 'task' to the task identifier you specified in the toolbar class.

 $bar->appendButton( 'Standard', 'delete', 'Delete Record', 'new', false );

In the above button the task would be 'new' ( the fourth parameter );


If this task is going to be run we had better make sure that it's available in our controller. Open up your controller.php and add the following.

 function new() 
 	{
 		JRequest::setVar('view' , 'new');
 		
 		parent::display();
 	}

This will display your 'new' view assuming you've already created one. You could put any code in here you like.


There we go that should create a nice easy to use toolbar class. There is one last thing though. You may have noticed that the icons are not displaying as they do in the backend. To make this work we have to 'steal' some images and some CSS from the backend.

open up the folder

administrator/templates/khepri/images 

and copy the directory 'toolbar' directory to your frontend templates/rhuk_milkyway/images folder

It should now look like this

templates/rhuk_milkyway/images/toolbar

and be filled with png images

Now you could hunt around through the backend css to find the correct code to display the buttons but I've saved you the trouble. In your templates/css folder create a file called icon.css and paste in the following code.

 /* toolbar */
 div.toolbar { float: right; text-align: right; padding: 0; }
 
 table.toolbar    			 { border-collapse: collapse; padding: 0; margin: 0;	 }
 table.toolbar td 			 { padding: 1px 1px 1px 4px; text-align: center; color: #666; height: 48px; }
 table.toolbar td.spacer  { width: 10px; }
 table.toolbar td.divider { border-right: 1px solid #eee; width: 5px; } 
 
 table.toolbar span { float: none; width: 32px; height: 32px; margin: 0 auto; display: block; }
 
 table.toolbar a {
    display: block; float: left;
 	white-space: nowrap;
 	border: 1px solid #fbfbfb;
 	padding: 1px 5px;
 	cursor: pointer;
 }
 
 table.toolbar a:hover {
 	border-left: 1px solid #eee;
 	border-top: 1px solid #eee;
 	border-right: 1px solid #ccc;
 	border-bottom: 1px solid #ccc;
 	text-decoration: none;
 	color: #0B55C4;
 }
 
 /** toolbar icons **/
 .icon-32-send 			{ background-image: url(../images/toolbar/icon-32-send.png); }
 .icon-32-delete 		{ background-image: url(../images/toolbar/icon-32-delete.png); }
 .icon-32-help 			{ background-image: url(../images/toolbar/icon-32-help.png); }
 .icon-32-cancel 		{ background-image: url(../images/toolbar/icon-32-cancel.png); }
 .icon-32-config 		{ background-image: url(../images/toolbar/icon-32-config.png); }
 .icon-32-apply 		{ background-image: url(../images/toolbar/icon-32-apply.png); }
 .icon-32-back			{ background-image: url(../images/toolbar/icon-32-back.png); }
 .icon-32-forward		{ background-image: url(../images/toolbar/icon-32-forward.png); }
 .icon-32-save 			{ background-image: url(../images/toolbar/icon-32-save.png); }
 .icon-32-edit 			{ background-image: url(../images/toolbar/icon-32-edit.png); }
 .icon-32-copy 			{ background-image: url(../images/toolbar/icon-32-copy.png); }
 .icon-32-move 			{ background-image: url(../images/toolbar/icon-32-move.png); }
 .icon-32-new 			{ background-image: url(../images/toolbar/icon-32-new.png); }
 .icon-32-upload 		{ background-image: url(../images/toolbar/icon-32-upload.png); }
 .icon-32-assign 		{ background-image: url(../images/toolbar/icon-32-publish.png); }
 .icon-32-html 			{ background-image: url(../images/toolbar/icon-32-html.png); }
 .icon-32-css 			{ background-image: url(../images/toolbar/icon-32-css.png); }
 .icon-32-menus 			{ background-image: url(../images/toolbar/icon-32-menu.png); }
 .icon-32-publish 		{ background-image: url(../images/toolbar/icon-32-publish.png); }
 .icon-32-unpublish 	{ background-image: url(../images/toolbar/icon-32-unpublish.png);}
 .icon-32-restore		{ background-image: url(../images/toolbar/icon-32-revert.png); }
 .icon-32-trash 		{ background-image: url(../images/toolbar/icon-32-trash.png); }
 .icon-32-archive 		{ background-image: url(../images/toolbar/icon-32-archive.png); }
 .icon-32-unarchive 	{ background-image: url(../images/toolbar/icon-32-unarchive.png); }
 .icon-32-preview 		{ background-image: url(../images/toolbar/icon-32-preview.png); }
 .icon-32-default 		{ background-image: url(../images/toolbar/icon-32-default.png); }

We now have to include this css in to your template so add the following line to the top of your template index.php

 <link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/rhuk_milkyway/css/icon.css" type="text/css" />

(if you are using the toolbar on a component that other people will be installing it would be better to use:

$mainframe->addCustomHeadTag ('<link rel="stylesheet" href="'.$this->baseurl.'/components/com_**yourcomponent**/filename.css" type="text/css" media="screen" />');

And finally - you will require the javascript file used in the backend to enable the buttons to work ;-)

$mainframe->addCustomHeadTag ('<script type="text/javascript" src="/includes/js/joomla.javascript.js"></script>');

And that's it. your toolbar should now render exactly as it does in the backend. This is a very simple toolbar helper. You could equally copy the JToolbarHelper class exactly in to your toolbar helper and use the functions in the same way as the backend. This would allow you to reuse your jtoolbar helper in multiple components.

To use JToolbarHelper Class in frontend section of your component, add this code to your component's entry point ( components/com_yourcom/yourcom.php )

require_once(JPATH_ADMINISTRATOR.DS.'includes'.DS.'toolbar.php');
$doc =& JFactory::getDocument();
$doc->addScript("includes/js/joomla.javascript.js");

Using JToolBar in 1.6[edit]

It's even simpler to use JToolBar in the front end, as it only requires two steps. First (Using the MVC architecture of 1.6),add a function definition to view.html.php file in the view you wish to add the toolbar to.

	function getToolbar() {
		// add required stylesheets from admin template
		$document    = & JFactory::getDocument();
		$document->addStyleSheet('administrator/templates/system/css/system.css');
		//now we add the necessary stylesheets from the administrator template
		//in this case i make reference to the bluestork default administrator template in joomla 1.6
		//EXCEPT for the IE6 file (which bluestork doesn't have, so i grab that one from the
		//one that's in hathor. (NOTE: this doesn't fix ALL the issues in IE6 - but I'm no css whizz so
		//i'll leave that up to someone else to fix up.
		$document->addCustomTag(
			'<link href="administrator/templates/bluestork/css/template.css" rel="stylesheet" type="text/css" />'."\n\n".
			'<!--[if IE 6]>'."\n".
			'<link href="administrator/templates/hathor/css/ie6.css" rel="stylesheet" type="text/css" />'."\n".
			'<![endif]-->'."\n".
			'<!--[if IE 7]>'."\n".
			'<link href="administrator/templates/bluestork/css/ie7.css" rel="stylesheet" type="text/css" />'."\n".
			'<![endif]-->'."\n".
			'<!--[if gte IE 8]>'."\n\n".
			'<link href="administrator/templates/bluestork/css/ie8.css" rel="stylesheet" type="text/css" />'."\n".
			'<![endif]-->'."\n".
			'<link rel="stylesheet" href="administrator/templates/bluestork/css/rounded.css" type="text/css" />'."\n"
			);
		//load the JToolBar library and create a toolbar
		jimport('joomla.html.toolbar');
		$bar =& new JToolBar( 'toolbar' );
		//and make whatever calls you require
		$bar->appendButton( 'Standard', 'save', 'Save', 'savetask', false );
		$bar->appendButton( 'Separator' );
		$bar->appendButton( 'Standard', 'cancel', 'Cancel', 'canceltask', false );
		//generate the html and return
		return $bar->render();
	}

Now in the corresponding tmpl file, you simply need to add code like the following (added here to a default.php file in the tmpl folder of the view to which the code above was added to the view.html.php file. Note I say "like" the following, changes may be required. I'm including the <form> declaration html (the toolbar MUST be in a form with the id of "adminForm" in order for it to work.

	<form action="index.php" method="post" id="adminForm" name="adminForm">

<?php
	echo $this->getToolbar();
?>
		<input type = "hidden" name = "task" value = "" />
		<input type = "hidden" name = "option" value = "com_yourcom" />
	</form>
<div class="clr"></div>

You'll note the [div class="clr"] which you may or may not need depending on your own design requirements. If you don't add the div tag, slapping this code into an existing component front end will place the buttons to the right and level with the content on the left. Also, and as explained above, you'll need to add functions within the controller that is called when one of the toolbar buttons is pressed, to process the request gracefully.