Contextual Links – Editable Blocks

One of the awesome things about Drupal is the contextual links. The contextual links provide a way to attach links to any block on the page for easy editing via UI or any purpose for that matter. In this post, we cover how to specify a region for which the context links should show up, then how to add the links and, at last, how to render them in the template.

1. Set the Region

First, we define a region in page that you like the context links show up when user hovers on top. If you have the default wrapping around the elements added by Drupal(not using block–no-wrap.tpl.php template) then this step is not necessary, because Drupal handles it for you. If you have custom element without any Drupal wrapped html, then you have to specify region for contextual links to show up. To do so, you add the class attribute with name ‘contextual-links-region’ to the outer html element as following:

<div class="contextual-links-region">
    //context links are rendered here
    //rest of the html comes here
</div>

The event on hover is used by context module to make contextual links visible. So by adding class name ‘contextual-links-region’ you are setting the region of the contextual links

2. Create and Add Context Links

To create contextual links, we use context module API:

$contextual_links = contextual_element_info();

This creates the renderable array without the links. The next, we add links we like to show up

    $contextual_links['contextual_links']['#contextual_links'] = array(
           'menu' => array('admin/structure/menu/manage', array('navigation')),
           'block' => array('admin/structure/block/manage', array('system', 'navigation')),
             'views' => array('admin/structure/views/view/'.$vars['view']->name, array($vars['view']->current_display)),
            );

Here, we have listed three different examples with already declared menu links referencing menu, block and views edit form. The index is the module name that declared the path in the menu system via hook_menu. The first parameter of contextual link is the base path of the link. The second parameter is for passing dynamic value that together combines the end path to the form. So, here are the possible paths from the above example:

admin/structure/menu/manage/navigation // for the 'menu' example
admin/structure/block/manage/system or admin/structure/block/manage/navigation //for the 'block' example\
admin/structure/views/view/VIEW_NAME/VIEW_DISPLAY_NAME //for the 'view' example

If you look into, you will find the paths – admin/structure/menu/manage/%/edit, admin/structure/block/manage/%/edit already declared via hook_menu in each of the modules – block, menu. The view path is also declared but in a little bit more dynamic format

2A – Adding Custom Menu Links

Sometimes you may need to add your custom form, then first you will have to do is register the path in the menu system:

//MENU FOR CONTEXT
function MODULE-NAME_menu() {
    $items['custom-path/%/edit'] = array(
        'title' => 'Edit',
        'type' => MENU_LOCAL_ACTION,
        'context' => MENU_CONTEXT_INLINE,
        'page callback' => 'ds_block_process',
        'page arguments' => array(1),
        'access callback' => TRUE,
    );
    // To use local task menu items, there must be a parent page.
    $items['custom-path'] = array(
        'title' => 'The contextual example page',
        'page callback' => 'ds_block_process',
        'page arguments' => array(1),
        'access callback' => TRUE,
    );

    return $items;
}

Here, we register path with pattern ‘custom-path/%/edit’ and the callback function builds the form. Please, see more on this in post – Add and Manipulate Pages with Menu System in Drupal

Afterwards, you add the path to the contextual links:

$contextual_links['contextual_links']['#contextual_links'] = array(
        'MODULE-NAME' => array('custom-path', array('some')),
  );

Here, the contextual link ‘custom-path/some/edit’ is added to the region. The second parameter(i.e. array(‘some’)) is the page arguments passed to the menu as declared above. Overall, adding custom link is just like adding predefined menu links, but only with our custom url and you have to specify module name that registers the path in the menu system.

4. Rendering Links

The last, the contextual menu is rendered in template:

    <?php print render($contextual_links['contextual_links']);?>

This will look up the theme function to context links. Now, for any authorized users who hover over the region, the contextual links will show up on the right corner of the region

Make it Overlay

Perhaps, you like to have your custom contextual links pull the page into overlay page, then the easiest is to declare the custom path to be an admin path:

function MODULE-NAME_admin_paths() {
    $paths = array(
        'custom-path/*/edit' => TRUE,
    );
    return $paths;
}

Now, your custom path for contextual link is an admin path and it automatically applies the overlay

Troubleshoot

1. Views contextual links doesn’t show up

Ensure the Views_UI module is enabled. If this doesn’t solve the problem, see whether the url you you specify in the contextual renderable array exists(i.e.’views’ => array(‘admin/structure/vie..[]’))

References

https://drupal.org/documentation/modules/contextual
https://api.drupal.org/api/drupal/modules!system!theme.api.php/function/hook_preprocess/7
http://dominiquedecooman.com/blog/drupal-7-tip-add-contextual-links-anything
https://api.drupal.org/api/drupal/modules%21system%21system.api.php/function/hook_menu_contextual_links_alter/7
https://api.drupal.org/api/drupal/modules%21contextual%21contextual.module/function/contextual_preprocess/7
http://bleen.net/blog/easier-way-add-contextual-links-drupal-7
http://deglos.com/blog/2011/02/06/hacking-contextual-links-drupal-7

Leave a Reply

Your email address will not be published. Required fields are marked *