Actions

J1.5

Difference between revisions of "How to create a custom button"

From Joomla! Documentation

m (adding version/tutor)
(13 intermediate revisions by 9 users not shown)
Line 1: Line 1:
The scripts below are used for using the back end toolbar when developing components or modules.
+
{{version/tutor|1.5}}{{cookiejar}}
 +
{{incomplete}}
 +
[[Category:Development]]
  
Put this script on your component or module code to make a custom button:
+
The code below is used for adding buttons to the back-end toolbar when developing components and modules.
'''
+
==Explanation of  JToolBarHelper button functionality==
JToolBarHelper::custom("task",'''
+
* When you add a JToolBarHelper function into an admin view it will display the icon and preform the corresponding function listed in the controller when pressed.
'''"icon",'''
+
* You can modify the default function that is run by using the $this->registerTask('add', 'edit'); to redirect logic, in this example a call from the default button add is directed to the edit function.
'''"icon over",'''
+
'''"alt",'''
+
'''boolean,'''
+
'''boolean);'''
+
  
For a back button you can use this one:
+
==Default Buttons / Functions Included with Joomla 1.5==
 +
<source lang="php">
 +
JToolBarHelper::title();
 +
JToolBarHelper::spacer();
 +
JToolBarHelper::divider();
 +
JToolBarHelper::custom();
 +
JToolBarHelper::customX();
 +
JToolBarHelper::preview();
 +
JToolBarHelper::help();
 +
JToolBarHelper::back();
 +
JToolBarHelper::media_manager();
 +
JToolBarHelper::addNew();
 +
JToolBarHelper::addNewX();
 +
JToolBarHelper::publish();
 +
JToolBarHelper::publishList();
 +
JToolBarHelper::makeDefault();
 +
JToolBarHelper::assign();
 +
JToolBarHelper::unpublish();
 +
JToolBarHelper::unpublishList();
 +
JToolBarHelper::archiveList();
 +
JToolBarHelper::unarchiveList();
 +
JToolBarHelper::editList();
 +
JToolBarHelper::editListX();
 +
JToolBarHelper::editHtml();
 +
JToolBarHelper::editHtmlX();
 +
JToolBarHelper::editCss();
 +
JToolBarHelper::editCssX();
 +
JToolBarHelper::deleteList();
 +
JToolBarHelper::deleteListX();
 +
JToolBarHelper::trash();
 +
JToolBarHelper::apply();
 +
JToolBarHelper::save();
 +
JToolBarHelper::cancel();
 +
JToolBarHelper::preferences();
 +
JToolBarHelper::addEntry();
 +
</source>
  
'''JToolBarHelper::back();'''
+
* The icons associated with these functions are stored at:
 +
<source lang="bash">
 +
www/administrator/templates/khepri/images
 +
</source>
  
Calcel button:
+
==Custom button==
'''
+
* The syntax for a custom button that can be added into a view
JToolBarHelper::cancel();'''
+
<source lang="php">
 +
/**
 +
* Writes a custom option and task button for the button bar
 +
* @param string The task to perform (picked up by the switch($task) blocks
 +
* @param string The image to display
 +
* @param string The image to display when moused over
 +
* @param string The alt text for the icon image
 +
* @param boolean True if required to check that a standard list item is checked
 +
* @param boolean True if required to include callinh hideMainMenu()
 +
*/
  
Apply button:
+
JToolBarHelper::custom( 'task', 'icon', 'icon over', 'alt', boolean, boolean );
 +
</source>
  
'''JToolBarHelper::apply();'''
+
* The Default Admin Toolbar Icons are stored at:
 +
<source lang="bash">
 +
www/administrator/templates/khepri/images
 +
</source>
 +
 
 +
* From here you will notice that the icons are linked to display through the CSS file at:
 +
<source lang="bash">
 +
www/administrator/templates/khepri/css/icon.css
 +
</source>
 +
 
 +
* This icon CSS file is automatically included through the admin template. If we would like to add a custom toolbar icon into an installable component it is useful to follow the same structure. We will have to manually include our new CSS file.
 +
 
 +
* An example of the icon CSS statement:
 +
<source lang="css">
 +
.icon-32-iconname {
 +
background-image: url(../../images/menu/icon-32-iconfile.png);
 +
}
 +
</source>
 +
 
 +
* As you can see iconname and iconfile do not necessarily have to be the same.
 +
** JToolBarHelper will look for the iconname at the end of .icon-32- and the filename must be preceded by icon-32-
 +
 
 +
* The following would create this custom toolbar icon, notice the iconname dose not correspond to the actual file name but the CSS allows the reference.
 +
 
 +
<source lang="php">
 +
JToolBarHelper :: custom( 'someFunction', 'iconname.png', 'iconname.png', 'alt text', false, false );
 +
</source>
 +
 
 +
* You can place your icon file and css file at any point in your installable component, which will allow it to be easily transferable.
 +
 
 +
* To include a new CSS file to your entire admin side it may be useful to include it in the entry point.
 +
 
 +
<source lang="php">
 +
JHTML::_('stylesheet', 'THISCOMPONENTNAME.css', 'components/THISCOMPONENT/assets/css/');
 +
</source>
 +
 
 +
* A Custom button relies on javascript from includes/js/joomla.javascript.js to execute the task indicated by the user:
 +
<source lang="javascript">
 +
function submitbutton(pressbutton) {
 +
  submitform(pressbutton);
 +
}</source>
 +
* In more complex cases a user can override this javascript by implementing his own submitbutton function. To keep the toolbar buttons in working order, the user has to replace the document.adminForm.task.value with the pressbutton value:
 +
<source lang="javascript">
 +
function submitbutton(pressbutton) {
 +
// Some conditions
 +
  document.adminForm.task.value=pressbutton;
 +
// More conditions
 +
  submitform(pressbutton);
 +
}</source>
 +
 
 +
==Upload button==
 +
* Method 1:
 +
<source lang="php">
 +
// Add an upload button and view a popup screen width 550 and height 400
 +
$alt = "Upload";
 +
$bar=& JToolBar::getInstance( 'toolbar' );
 +
$bar->appendButton( 'Popup', 'upload', $alt, 'index.php', 550, 400 );
 +
</source>
 +
* Method 2:
 +
<source lang="php">
 +
// You view button for popup media manager tools
 +
JToolBarHelper::media_manager( '/' );
 +
</source>
 +
[[Category:Tutorials]][[Category:Component Development]]

Revision as of 20:54, 17 September 2012

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.
Quill icon.png
Content is Incomplete

This article or section is incomplete, which means it may be lacking information. You are welcome to assist in its completion by editing it as well. If this article or section has not been edited in several days, please consider helping complete the content.
This article was last edited by Tom Hutchison (talk| contribs) 2 years ago. (Purge)

The code below is used for adding buttons to the back-end toolbar when developing components and modules.

Contents

Explanation of JToolBarHelper button functionality

  • When you add a JToolBarHelper function into an admin view it will display the icon and preform the corresponding function listed in the controller when pressed.
  • You can modify the default function that is run by using the $this->registerTask('add', 'edit'); to redirect logic, in this example a call from the default button add is directed to the edit function.

Default Buttons / Functions Included with Joomla 1.5

JToolBarHelper::title();
JToolBarHelper::spacer();
JToolBarHelper::divider();
JToolBarHelper::custom();
JToolBarHelper::customX();
JToolBarHelper::preview();
JToolBarHelper::help();
JToolBarHelper::back();
JToolBarHelper::media_manager();
JToolBarHelper::addNew();
JToolBarHelper::addNewX();
JToolBarHelper::publish();
JToolBarHelper::publishList();
JToolBarHelper::makeDefault();
JToolBarHelper::assign();
JToolBarHelper::unpublish();
JToolBarHelper::unpublishList();
JToolBarHelper::archiveList();
JToolBarHelper::unarchiveList();
JToolBarHelper::editList();
JToolBarHelper::editListX();
JToolBarHelper::editHtml();
JToolBarHelper::editHtmlX();
JToolBarHelper::editCss();
JToolBarHelper::editCssX();
JToolBarHelper::deleteList();
JToolBarHelper::deleteListX();
JToolBarHelper::trash();
JToolBarHelper::apply();
JToolBarHelper::save();
JToolBarHelper::cancel();
JToolBarHelper::preferences();
JToolBarHelper::addEntry();
  • The icons associated with these functions are stored at:
www/administrator/templates/khepri/images

Custom button

  • The syntax for a custom button that can be added into a view
/**
* Writes a custom option and task button for the button bar
* @param string The task to perform (picked up by the switch($task) blocks
* @param string The image to display
* @param string The image to display when moused over
* @param string The alt text for the icon image
* @param boolean True if required to check that a standard list item is checked
* @param boolean True if required to include callinh hideMainMenu() 
*/
 
JToolBarHelper::custom( 'task', 'icon', 'icon over', 'alt', boolean, boolean );
  • The Default Admin Toolbar Icons are stored at:
www/administrator/templates/khepri/images
  • From here you will notice that the icons are linked to display through the CSS file at:
www/administrator/templates/khepri/css/icon.css
  • This icon CSS file is automatically included through the admin template. If we would like to add a custom toolbar icon into an installable component it is useful to follow the same structure. We will have to manually include our new CSS file.
  • An example of the icon CSS statement:
.icon-32-iconname       { 
        background-image: url(../../images/menu/icon-32-iconfile.png); 
}
  • As you can see iconname and iconfile do not necessarily have to be the same.
    • JToolBarHelper will look for the iconname at the end of .icon-32- and the filename must be preceded by icon-32-
  • The following would create this custom toolbar icon, notice the iconname dose not correspond to the actual file name but the CSS allows the reference.
JToolBarHelper :: custom( 'someFunction', 'iconname.png', 'iconname.png', 'alt text', false, false );
  • You can place your icon file and css file at any point in your installable component, which will allow it to be easily transferable.
  • To include a new CSS file to your entire admin side it may be useful to include it in the entry point.
JHTML::_('stylesheet', 'THISCOMPONENTNAME.css', 'components/THISCOMPONENT/assets/css/');
  • A Custom button relies on javascript from includes/js/joomla.javascript.js to execute the task indicated by the user:
function submitbutton(pressbutton) {
  submitform(pressbutton);
}
  • In more complex cases a user can override this javascript by implementing his own submitbutton function. To keep the toolbar buttons in working order, the user has to replace the document.adminForm.task.value with the pressbutton value:
function submitbutton(pressbutton) {
// Some conditions
  document.adminForm.task.value=pressbutton;
// More conditions
  submitform(pressbutton);
}

Upload button

  • Method 1:
// Add an upload button and view a popup screen width 550 and height 400
$alt = "Upload";
$bar=& JToolBar::getInstance( 'toolbar' );
$bar->appendButton( 'Popup', 'upload', $alt, 'index.php', 550, 400 );
  • Method 2:
// You view button for popup media manager tools
JToolBarHelper::media_manager( '/' );