[4.0][RFC][WIP] New Toolbar Interface (for PHP)

[asika32764]

This is a new toolbar interface design on PHP part. Related to #18392 and #19635

• Complete Dropdown buttons logic
• Add Toolbar class to service provider
• Sync php code with [4.0][RFC] Custom Element: Joomla! Toolbar button #19635
• Code style and docblock
• Test
• Write a guide about how to us new interfaces.

Introduction

Currently we use JToolbarHelper to add buttons to component view. But there are some problems of this interface.

First, too many arguemnts on some methods, for instance:

public static function preferences($component, $height = '550', $width = '875', $alt = 'JToolbar_Options', $path = '')

Second, hard to add a custom button, the Toolbar::appendButton() has no type hint, we must look every Button classes to learn how to use them.

$bar->appendButton('Standard', 'name', 'JTOOLBAR_BUTTON', 'item.new', true, false);

Then, it is impossible to customize some standard buttons or add dropdown. All standard buttons are hard coded.

The Changes

I try to create a fluent interface that provides a flexible Toolbar button definition process:

$toolbar = Toolbar::getInstance('toolbar');

// Use core button class or custom class.
$toolbar->appendButton(new StandardButton('new'))
    ->text('JTOOLBAR_NEW')
    ->task('article.add')
    ->icon('icon-plus');
    
// Use pre-defined megic methods
$toolbar->popupButton('preview')
    ->text('COM_FOO_TOOLBAR_PREVIEW')
    ->url(Route::_('...'))
    ->icon('icon-eye')
    ->listCheck(true)
    ->iframeWidth(640)
    ->iframeHeight(480)
    ->setOption('foo', 'bar');

All arguments are options.

$button->task('item.save');

// Same as

$button->setOption('task', 'item.save');

And IDE friendily

Layout

Buttons can override layout and HTML classes:

$toolbar->linkButton('back')
	->text('COM_FOO_TOOLBAR_BACK')
	->url(Route::_('...'))
	->icon('fa fa-arrow-left') // If icon not set, will fallback to `icon-back` like original code
	->buttonClass('btn btn-primary btn-sm')
	->layout('com_foo.toolbar.link');

Button Group

Use callback to easily customize your dropdown buttons.

$toolbar->dropdownButton('group')
	->text('Group')
	->toggleSplit(false)
	->icon('fa fa-globe')
	->buttonClass('btn btn-success btn-sm')
	->configure(
		function (Toolbar $childBar)
		{
			$childBar->standardButton('ok', 'Button 1');
			$childBar->standardButton('star', 'Button 2');

			$childBar->divider('HEADER');
			$childBar->standardButton('remove', 'Button 3');
			$childBar->standardButton('folder', 'Button 4');

			$childBar->divider();
			$childBar->standardButton('trash', 'Button 5');
			$childBar->standardButton('question', 'Button 6');
		}
	);

Confirm Button

$toolbar->confirmButton('clear')
	->text('Clear')
	->icon('fa fa-refresh')
	->buttonClass('btn btn-sm btn-danger')
	->message('Are you sure you want to clear all data?');

Pre-Defined Buttons

$toolbar->addNew('articles.add')->listCheck(true);
$toolbar->publish('articles.publish')->listCheck(true);
$toolbar->unpublish('articles.unpublish')->listCheck(true);
$toolbar->archive('articles.archive')->listCheck(true);
$toolbar->checkin('articles.checkin')->listCheck(true);

No B/C break

If a component was using ToolbarHelper or $bar->appendButton(), it should fully B/C.

---

This PR is WIP, I changed com_content component to use new Toolbar syntax, it works very well:

• https://github.com/joomla/joomla-cms/pull/19670/files#diff-768783efa9acc6038e68770acac92aec
• https://github.com/joomla/joomla-cms/pull/19670/files#diff-dd27b3b67199eb49f1a592f47d1f5cf9

[dgrammatiko]

@asika32764 @Fedik can you please coordinate this task?
Just for reference @Fedik already proposed something for the client side: #19635

[asika32764]

I think the php side still need much discussion (Since it is a big change). If the concept of this PR accepted, I can try to integrate @Fedik 's code into my PR or merge #19635 first then I sync the code base.

What do you think @Fedik ?

[photodude]

@asika32764 Please take the time to correct the Codestyle items here. It will help with the overall consideration of your proposal.
http://ci.joomla.org/joomla/joomla-cms/3102/4

You can use the PHPCS codestyle autofixers to automatically fix a number of the items in your PR. Just remember to keep it to the files related to your PR.

[asika32764]

Still Work in process, will fix all CS and docblock later.

[houndci-bot]

Line should be indented 4 spaces, but was indented 6 spaces

[samarthsharma36]

After applying the patch , I am getting this error when i tried creating "New Article"

[asika32764]

did you use patchtester to test it? Maybe is the same reason of #19670 (comment)

[samarthsharma36]

@asika32764 , yes. I used patch tester to test it

[wilsonge]

@asika32764 can we get this upto date with 4.0 please. I really like this concept and would like to get it in :)

[asika32764]

OK. A little busy that I stop developing this PR. Well continue finish this maybe this weekend.

[wilsonge]

OK I've fixed the conflicts myself and made the decision to merge this for now so we can all work on it in the main repo :)

[wilsonge]

Thanks for the hard work that went into this!!

[asika32764]

Thank you, sorry for the delayed since there are some serious projects I must to complete in this month.

[asika32764]

I still must write some documentation. If you need the doc, please tag me.

[wilsonge]

Don't worry :) Thankyou so much for doing what you could!

[N6REJ]

were docs ever created for this?

[Quy]

No. See #19670 (comment)