CodeBlog.ch

with concrete5 you usually put your add-on code in a package and don’t touch the core. This concept allows you to update the CMS core without overriding anything you’ve built on your own. In order to interact with the CMS you can use several functions helping you to integrate your add-on into the CMS interface.

In this short article we’re going to look at a simple example which will place a button next to the edit button and shows a dialog with a quote. Nothing fancy, just an example aimed at developers who want to use this feature in their add-ons.

This is how your button is going to look like:

But let’s start at the beginning, every package needs a controller to handle the installation process and in this case the integration of the button as well. The following code box shows the complete package controller you have to create at /packages/remo_toolbar_button/controller.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

<?php
defined('C5_EXECUTE') or die(_("Access Denied."));
 
class RemoToolbarButtonPackage extends Package {
 
   protected $pkgHandle = 'remo_toolbar_button';
   protected $appVersionRequired = '5.5.1';
   protected $pkgVersion = '1.0.0';
 
   public function getPackageDescription() {
      return t("Toolbar Button Example.");
   }
 
   public function getPackageName() {
      return t("Toolbar Button");
   }
 
   public function on_start() {
      if(version_compare(APP_VERSION,'5.4.1.1', '>')){
         $ihm = Loader::helper('concrete/interface/menu');
         $uh = Loader::helper('concrete/urls');
 
         $ihm->addPageHeaderMenuItem('help', t('Help'), 'left', array(
            'dialog-title'    => t('Help'),
            'href'            => $uh->getToolsUrl('help', 'remo_toolbar_button'),
            'dialog-on-open'  => "$(\'#ccm-page-edit-nav-help\').removeClass(\'ccm-nav-loading\')",
            'dialog-modal'    => "false",
            'dialog-width'    => '200',
            'dialog-height'   => "160",
            'class'           => 'dialog-launch'
         ), 'remo_toolbar_button');         
      }   
   }  
}

The function on_start is called in every installed package when a page is rendered. It allows us to inject code into the running process. There’s a helper method addPageHeaderMenuItem, first parameter is our id, second the text, followed by an array of attributes to create the link tag as well as the package name as the last parameter. Having a reference to the package is important because our button needs a few more files located in the package.

Let’s create those files! Within your package /package/remo_toolbar_button/, create a new directory structure called “elements/header_menu/help”. The last directory has to match the first parameter of addPageHeaderMenuItem. Within that directory, create a file called view.css and put this content in it:

1
2
3

#ccm-page-edit-nav-help {
   color: red ! important;
}

It’s pretty basic, just to show you where you have to put your CSS code to style your button. Next, create another file in the same directory called view.js with this content:

1
2
3

$(function() {
	$("#ccm-page-edit-nav-help").dialog();
});

The ID used in this little jQuery code is generated by addPageHeaderMenuItem in combination with the first parameter we’ve specified. We use this to launch our dialog.
Next, we have to create another controller, this time the button controller. Still in the same directory, create a file called controller.php and put the following content in it:

1
2
3
4
5
6
7
8
9

<?php 
defined('C5_EXECUTE') or die("Access Denied.");
class HelpConcreteInterfaceMenuItemController extends ConcreteInterfaceMenuItemController {
   public function displayItem() {
      // button is always enabled
      return true;
   }
}
?>

We always return true since our button has to be active all the time. Be careful with the name of the class, it must follow the concrete5 rule. Our ID is “help” which we start with a capital letter and put it as a prefix before “ConcreteInterfaceMenuItemController”. If our ID was help_me, the class name would have to be HelpMeConcreteInterfaceMenuItemController, after every underscode, we have to start with a capital letter (camel case).

There’s just one more file we have to create. The dialog we want to display needs some content. We’ve used this url

$uh->getToolsUrl('help', 'remo_toolbar_button')

when we’ve added our button. This file has to be located at /packages/remo_toolbar_button/tools/ and is named help.php. The content could look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<?php
defined('C5_EXECUTE') or die(_("Access Denied."));
$ih = Loader::helper('concrete/interface');
 
$quotes = array(
   array('The best way out is always through.', 'Robert Frost'),
   array('Whatever you do will be insignificant, but it is very important that you do it.', 'Mahatma Gandhi'),
   array('Failure is the condiment that gives success its flavor.', 'Truman Capote'),
   array('Experience is what you get when you don\'t get what you want.', 'Dan Stanford'),
   array('The best way to cheer yourself up is to try to cheer somebody else up.', 'Mark Twain')
);
 
$quote = $quotes[array_rand($quotes)];
 
echo "<b>{$quote[0]}</b><br/> - {$quote[1]}";
 
echo '<div class="dialog-buttons"><a href="javascript:void(0)" class="btn primary ccm-button-right" onclick="jQuery.fn.dialog.closeTop();">' . t('Close') . '</a></div>';
?>

Nothing but a simple PHP code to display a random quote as well as a button using the concrete5 style to close the dialog.

If everything works, you’ll see a dialog like this:

After you created all the file, you’ll have to hover the dashboard button and click on “Install” where you’ll see our new add-on available for installation.

If you had any problem with the code, click here to download the complete add-on.