Skip Navigation

Implementing Reason Inline Editing

Reason modules that support inline editing allow authorized users to make changes to content without using the Reason administrative interface. This guide describes the components of the inline editing implementation and presents best practices for implementing inline editing in custom modules.

Overview

Reason 4 Beta 8 includes inline editing support for page content and text blurbs. While any module can implement inline editing, only one module should be active for editing at a time. Modules that implement inline editing need to provide a toggle to turn editing on and off, and also need to use the Reason inline editing class to determine appropriate activation / deactivation parameters to avoid conflicts with other modules.

Inline Editing Class

reason_package/reason_4.0/lib/core/classes/inline_editing.php

The inline editing class manages all aspects of inline editing. Any module that implements inline editing needs to register with the a shared instance of this class that is obtained through the function &get_reason_inline_editing($page_id).

Modules should use the following class methods:

register_module(&$module, $available)

Any module that implements inline editing should pass a reference to itself, and a boolean value that indicates whether the current user has the appropriate privileges to inline edit. Typically, this would be users who have administrative access to a site, but a given module can user whatever criteria it wants to decide whether inline editing is available.

available_for_module(&$module)

This method should be used to determine whether or not inline editing is available. If it is available, this means that inline editing is available in Reason and that the current user has inline editing privileges for the module.

active_for_module(&$module)

This method should be used to determine whether or not inline editing is active. If it is active, this means that the proper activation parameters for the module are present in the $_REQUEST. Since the activation value for each module is unique, and the $_REQUEST key is shared, only one module can be active at a time when inline editing is properly implemented.

get_activation_params(&$module)

Returns an array with the appropriate key / value pair to activate inline editing for a particular module. The return value of get_activation_params should be used along with carl_make_link to create a URL that can be used to make an activation link.

get_deactivation_params(&$module)

Returns an array with the appropriate key / value pair to deactivate inline editing for a particular module. While the use of this is likely implementation specific, a common case would be to assemble a URL for redirection in the where_to phase of a save and finish action in an editing interface.

Implementation Example - the Content Module

We'll look at each relevant method of the content module (reason_package/reason_4.0/lib/core/minisite_templates/modules/content.php) to see how it implements inline editing.

init()

First, we must get the shared instance of the inline editing class and register the module with it.  When registering our module, we provide the user's inline-editing permissions:

$inline_edit =& get_reason_inline_editing($this->page_id);
$inline_edit->register_module($this, $this->user_can_inline_edit());

has_content()

The Content module implements this function with slightly different logic than usual.  A user should be able to do inline editing even if there is no preexisting content.  So, to determine whether or not this module "has content," it checks to see if inline editing is available for the module.  If it's not available, then calling parent::has_content() will be appropriate.  It is important to note that the available_for_module() method of the inline editing class also keeps track of the user's inline-editing permissions, whether or not inline editing is globally enabled, and whether or not inline editing is currently turned on for the session.

$inline_edit =& get_reason_inline_editing($this->page_id);
if ($inline_edit->available_for_module($this))
{
    return true;
}
else
{
    return parent::has_content();
}

run()

One common approach to implementing this function is to branch to a different function if inline editing is available--we'll call this function run_editable().  Here is what run() looks like in content.php:

$inline_edit =& get_reason_inline_editing($this->page_id);
if ($inline_edit->available_for_module($this))
{
    $this->run_editable();
}
else parent::run();

Now, run_editable() should do two different things if inline editing is currently active or not.  If it IS active, we'll provide the user with an editing form.  In content.php, we present the user with a small Disco form with an html editor and two different save buttons.  Of course for different modules, it might be appropriate for a form with different elements than the html editor.  Take a look at process_editable() and where_to_editable() in content.php to get an idea of how to update the contents of the Reason entities that the user is editing.  If inline editing is NOT currently active, we present the user with a simple button that turns on inline editing. 

To actually turn on inline editing, simply create a link using carl_make_link() with the inline editor's get_activation_params() method.  Here is an example from content.php of creating an "Edit Content" button that will turn on inline editing:

$inline_edit =& get_reason_inline_editing($this->page_id);
$url = carl_make_link($inline_edit->get_activation_params($this));
if (!carl_empty_html($this->content))
{
    $link = '<p><a href="'.$url.'" class="editThis">Edit Content</a></p>';
    $pre = '<div class="editRegion">';
    $post = '</div>';
    $output = $pre . $this->content . $link . $post;
}
else
{
    $link = '<p><a href="'.$url.'" class="editThis">Create Content</a></p>';
    $pre = '<div class="editRegion">';
    $post = '</div>';
    $output = $pre . $link . $post;
}
echo $output;

This code creates a differently-labeled button depending on whether or not there is preexisting content.