This plugin enables you to include a panelBar on top of your site which gives you direct access to some administrative functions. The panelBar will only be visible to logged in users who are eligible to access the panel.

Requires PHP 5.3+ and Kirby 2.1 or higher

Please support the development by buying a moral license!

1. Setup
2. Usage
3. Elements
4. Standard Elements
5. Default Set of Elements
6. Customize
7. Custom Set of Elements
8. Custom Elements
9. Element Builders
10. Custom CSS/JS
11. Hooks
12. Output CSS/JS
13. Assets Guide
14. Options
15. Default Position
16. Responsiveness
17. Remember State
18. Enhanced JS
19. Keyboard Shortcuts
20. Known Problems
21. Help & Improve
22. Changelog

1. Download the panelBar plugin
2. Copy the whole folder to site/plugins/panel-bar

Include in your site/snippets/footer.php (or equivalent) before the </body> tag:

<?php echo panelBar::show() ?>

If you want the panelBar hidden when the page loads:

<?php echo panelBar::hide() ?>

If you want to use caching with Kirby, please make sure to only activate it if the visitor is not a logged-in user:

if(!site()->user()) c::set('cache', true);

The panelBar provides several standard elements:

The pre-defined default set of elements consists of panel, add, edit, toggle, files, user and logout. You can define your own custom set of elements.

You can define a custom set of elements in site/config/config.php:

c::set('panelbar.elements', array(…));

Or pass them as a parameter when calling ::show() or ::hide():

<?php echo panelBar::show(array('elements' => array(…))) ?>

To include standard elements in your custom set, simply name them:

c::set('panelbar.elements', array(
  'panel', 
  'edit', 
  'languages',
));

Or you can add your custom set of elements to the default set of elements using ::defaults() which returns either just the default set or merges it with any array of elements if provided as a parameter:

<?php
$elements = panelBar::defaults(array(
  'customDropdown',
  'custom2'
));

echo panelBar::show(array('elements' => $elements));
?>

The panelBar can include custom elements. You can either include the custom element's output code directly in the elements array or use the name of a callable function in the array, which returns the output code:

<?php
// custom callable element
function customSongs() {
  return '<div class="panelbar-element panelbar-drop"><span><i class="fa fa-headphones "></i><span>Songs</span></span><div class="panelbar-drop__list"><a href="https://www.youtube.com/watch?v=BIp_Y28qyZc" class="panelbar-drop__item">Como Soy</a><a href="https://www.youtube.com/watch?v=gdby5w5rseo" class="panelbar-drop__item">Me Gusta</a></div></div>';
}

// array of elements
$elements = array(
  'panel',
  'add',
  'edit',
  '<div class="panelbar-element panelbar-btn"><a href="http://mydomain.com/pictureofmum.jpg"><i class="fa fa-heart "></i><span>Mum</span></a></div>',
  'customSongs',
);

// output panelBar
echo panelBar::show(array('elements' => $elements));
?>

For more complex custom elements, have a look at panelBar's assets guide on its core CSS and Javascript elements.

The panelBar plugin includes four builder method, which can be used to create custom elements. All builders require some basic parameters:

panelBar::builder(array(
  'id'      => 'theID',             // unique identifier
  'icon'    => 'heart',             // FontAwesome icon (without fa-)
  'label'   => 'Just the label',    // text used as label
  'mobile'  => 'label',             // what's showed in mobile view (default: icon)
  'compact' => false                // show it in compact view (default: false)
));

The following element builders are available and require additional parameters if referenced:

1. Label

   panelBar::label(array(
     …,
   ));

2. Link

   panelBar::link(array(
     …,
     'url' => site()->url().'/panel',  // URL to which the button links
   ));

3. Dropdown

   panelBar::dropdown(array(
     …,
     'items' => array(     // array of dropdown elements
       0 => array(
         'label' => …,     // label of the dropdown element
         'url'   => …,     // URL to which dropdown element links
       ),
       …
      ),
   ));

4. Textbox

   panelBar::box(array(
     …,
     'content' => '<b>Important information</b>', // (HTML) content of the textbox
   ));

With the builders you can easily create custom elements and add them to your custom set of elements - for example:

<?php
// custom callable element using the dropdown builder
function customDropdown() {
  return panelBar::dropdown(array(
    'id'    => 'songs',
    'icon'  => 'headphones',
    'label' => 'Songs',
    'items' => array(
      array(
        'url'   => 'https://www.youtube.com/watch?v=BIp_Y28qyZc',
        'label' => 'Como Soy',
      ),
      array(
        'url'   => 'https://www.youtube.com/watch?v=gdby5w5rseo',
        'label' => 'Me Gusta',
      ),
     )
  ));
}

// array of elements
$elements = array(
  'panel',
  panelBar::link(array(
    'id'    => 'mum',
    'icon'  => 'heart',
    'label' => 'Mum',
    'url'   => 'http://mydomain.com/pictureofmum.jpg',
  )),
  'customDropdown',
);

// output panelBar
echo panelBar::show(array('elements' => $elements));
?>

If you use any builders in the config.php, you must prepend the following line:

kirby()->plugin('panel-bar');

To include your custom CSS and JS with panelBar (e.g. for a custom element), the best way would be to use asset hooks in your custom element function. However, you can also pass custom CSS and JS as parameters to the ::show() and ::hide() methods:

<?php echo panelBar::show(array('css' => '.mylove{}', 'js' => 'console.log("hello");')) ?>

There are two types of hooks in panelBar: asset hooks and output hooks. Asset hooks are divided into css and js. Output hooks all refer to HTML but are included at different positions in the panel bar: as element, before and after. To make use of assets and output hooks, the plugin passes the $output and $assets objects to callable custom element functions:

<?php
// custom callable element using assets and output hooks
function customHelpElement($output, $assets) {
  $assets->setHook('css',      '.mylove{}');
  $assets->setHook('js',       'console.log("hello");');
  $output->setHook('elements', panelBar::label(…));
}

// array of elements
$elements = array(
  'panel',
  'customHelpElement',
);

// output panelBar
echo panelBar::show(array('elements' => $elements));
?>

If you do not want to directly set hooks, you can return an array instead and the plugin will take care of hooking the CSS, JS and/or HTML into the panelBar:

// custom callable elements returning array to register hooks
function customHelpElement() {
  return array(
    'element' => '…',
    'assets'  => array(
      'css' => '.mylove{}',
      'js'  => 'console.log("hello");',
    ),
    'html'    => array(
      'before' => '…',
      'after'  => '…',
    )
  );
}

// array of elements
$elements = array(
  'panel',
  'customHelpElement',
);

// output panelBar
echo panelBar::show(array('elements' => $elements));

At default, panelBar includes the necessary CSS styles and JS scripts in its output. If you not want to output the CSS and/or JS directly with the panelBar (e.g. separately within the <head> section), you first have to disable their output:

<?php echo panelBar::show(array('css' => false, 'js' => false) ?>

To output the CSS and/or JS wherever you want it, just use ::css() or ::js():

<?php echo panelBar::js() ?>

If you use a custom set of elements, please make sure to also pass the array of elements:

<?php echo panelBar::js(array('elements' => $elements)) ?>

You can also still pass your custom CSS/JS to these methods:

<?php echo panelBar::css(array('elements' => $elements, 'css' => '.mylove{}') ?>

All options refer to settings in the site/config/config.php if not stated otherwise.

To change the default position of the panelBar to bottom include:

c::set('panelbar.position', 'bottom');

To deactivate the javascript that makes the panelBar responsive to mobile devices include:

c::set('panelbar.responsive', false);

The panelBar will be loaded on default at the defined positon and visible whether you included it in your templates with ::show() or ::hide(). But it also tries to remember its state across page loads (e.g. it loads on top, you move it to bottom and you want it to be still on bottom after clicking on a link) via your browser's local storage. If you want to disable this, you need to include:

c::set('panelbar.remember', false);

By default, the panelBar comes with some javascript functionalities (e.g. loading the edit mode in an iFrame). If you want to disable these functionalities and just use the panelBar elements as plain links, you need to include:

c::set('panelbar.enhancedJS', false);

By default the panelBar features a few keyboard shortcuts:

If you want to deactivate these keyboard shortcuts, you have to include:

c::set('panelbar.keys', false);

X-Frame-Options
If you have set the X-Frame-Options in your .htaccess to DENY, panelBar will not be able to display the panel in its embedded iFrame mode. panelBar tries to detect this barrier and then switch to plain links.

If you find any bugs, have troubles or ideas for new elements or further configuration options, please let me know by opening a new issue.

So far the plugin has been free of charge and open for everyone to use it. Still, if it helps you with your work and/or life and you can share, I would really appreciate your support by buying a moral license.