Editable Regions

With the introduction to the tags over, let us now take a look at, arguably, the most important tag in Couch - the Editable tag.
You can use it to define areas within your HTML template that you wish to make editable.

As an example, suppose the following is a chunk of HTML from a template named property.php -

<div class="prop_desc">
    <b>Property Description:</b>
    <span class="gray">
        Condo pricing starts at just under $700,000.
        Waterfront Private Residences.
        Jack Nicklaus Signature Golf Course.
    </span>
    <br class="clear"/>
</div>

The highlighted part is the description of some property. Suppose you wish to allow the user to edit this part himself.
To do so, simply enclose this part by an editable tag -

<div class="prop_desc">
    <b>Property Description:</b>
    <span class="gray">
        <cms:editable name='prop_desc' >
        Condo pricing starts at just under $700,000.
        Waterfront Private Residences.
        Jack Nicklaus Signature Golf Course.
        </cms:editable>
    </span>
    <br class="clear"/>
</div>

Editable tag accepts several parameters but only one is mandatory - name. It has to be unique within a template.

Now, while being logged in as the super-admin, visit the template in your browser.
For example, if the template was property.php, visit http://www.yoursite.com/property.php

At the risk of repeating ourselves - for your changes to show up in the admin panel, you'll always need to run the modified template in the browser while being logged in as the super-admin.

Now visit the admin panel and access property.php and you'll find that Couch has created a textarea for the editable region.

If you enclose some text between the opening and closing Editable tags, this will cause Couch to display the text as default text within the editable region. Sometimes you do not wish have any default text displayed at all. For such cases, you can use the Editable tag as a self closing tag.

<cms:editable name='prop_desc' />

Input or edit the text within this textarea and save your changes.
Visiting the template in your browser again should show up the edited text on the webpage.

TYPES OF EDITABLE REGIONS

In the example above, the type of the editable region that Couch created to allow editing was a textarea.
You have a choice of several other types of editable regions that you can ask Couch to create, depending on the kind of data that will be inputted into it.
For example, the textarea created above is suitable when you wish the users to input only plain text (i.e. not formatted by HTML tags). However, when the type of text that will be inputted requires HTML formatting, you can get Couch to create a richtext editor instead.
Similarly, sometimes a single line of text input is all that is needed.
The type parameter of Editable text can bet set to the kind of editable region you wish to create.

e.g. setting the type to 'richtext' -

<cms:editable name='prop_desc' type='richtext'>..</cms:editable>

- will result in Couch now displaying a WYSIWYG editor instead of the plain textarea.

The followng are the different types of editable regions currently supported by Couch -

You can define any number of editable regions in a template.

V.IMP: Editable tags cannot be nested within other editable tags.

ACCESSING THE CONTENTS OF EDITABLE REGIONS

There are four ways the contents of an editable region defined within a template may be accessed. The first two can be used only within the templates that defined the editable regions while the last two can be used in any template - even those that did not define the regions.

1. As the output of the editable tag defining it -

You might recall from our previous discussion about tags that, every tag after executing its function returns back it output (which could be a blank).

The editable tag, as its function, checks if the editable region has not already been created in the Admin Panel. If not, it creates one. After executing its function, the editable tag fetches back the contents of the editable region and returns it as its output.

Thus you can see that in the resulting webpage, the editable tags are replaced by the current contents of the associated editable regions.

2. As variables automatically set by Couch -

When a page is executed, Couch makes available the current contents of all the editable regions contained within the page as variables of the same names.
Thus in the example above, since the name of the editable region is prop_desc, a variable by the same name will also be set by Couch during the execution of this page.
So if you use the following snippet anywhere within your template -

<cms:show prop_desc />

the current contents of the editable region will be output by show.

[See: Variables available in Views]

3. As variables set by the pages tag -

The pages tag is used to list (all or specific) pages cloned from a template. The tag, as it fetches the pages, makes vailable all the variables pertaining to the pages - these include the variables that represent the editables regions defined for the pages.

SEPARATING THE DEFINITION OF EDITABLE REGION FROM ITS DISPLAY

In the examples above we have been creating the editable regions exactly at the spot where we wanted their outputs to appear. In effect we have been using the editable tag to both define the editable regions as well as to display their contents.

In complex templates (clonable templates, specifically) with several editable regions it is sometimes more manageable to define all the editable regions together at a single place.

For such cases, we can use the editable tag to only define the editable regions and use the show tag to display the contents.
A good practice is to define together all editable regions used by the template somewhere at the very top of the template -

<cms:template title='Index' clonable='1' >
    <cms:editable name="body" label="Body" type="richtext" />
    <cms:editable name="excerpt" label="Excerpt" type="textarea" />
</cms:template>

The editable tags themselves can be enclosed within template tag (more about it in a little while) because this is a key tag in clonable templates and also because this tag has no output of its own and thus it 'swallows up' the default output of the enclosed editable tags, which otherwise would have appeared on the webpage.

If you do not wish to enclose the editable tags within template tag, set the hidden parameter of each to '1' and this will turn off the output of the tags.

The content of these editable regions can be displayed where ever required by using the show tag -

<cms:show body />
<cms:show excerpt />