Composr Supplementary: Inline editing in Composr

Inline editing (maintenance status) is achieved in Composr via an internal framework called fractional editing.
By default inline editing is implemented for some content titles (when shown as screen titles), and for some member profile fields.

Enabling and support status

Inline editing has to first be enabled from the configuration:
Admin Zone > Setup > Configuration > Feature options > Advanced

It is not enabled by default for 2 reasons:

1. The default inline editing experience is very basic
2. We do not like to impose overly-complex layout assumptions/requirements on themers

To this end inline editing is supported only as a feature for programmers to deploy, not as an out-of-the-box solution.

Limitations

Inline editing only supports fields that may be edited in a text-based way.

For title fields this will also be true.

For CPFs, this is hard-coded to the following field types (expressed as the raw hook codenames, hard-coded in sources/cns_members.php):

• long_text
• long_trans
• short_trans
• list
• short_text
• codename
• url
• integer
• float
• email

Using inline editing

Inline editing is either activated by an edit button, or by a special click.
By default it is by a special click. We will cover how to change that under 'Templating' below.

You can know if a special click may be used by a dashed border appearing when hovering the mouse. You need to hold down at least two keyboard modifier keys (e.g. Alt and Shift) and then click the field. We aren't completely specific on the fields because browsers sometimes reserve some of the keys, or keyboards might be missing them. On a Mac the Command key will also work as one of the fields, and on Windows the Windows key.

You conclude inline editing by pressing enter. You cancel by pressing escape.

Inline editing will run via an AJAX request, and then it will update the displayed field value with the new rendered value.

How it works

Fractional editing is literally the fractional handling of a standard Composr POSTed edit form.
It only works on edit forms that have been coded to support this.

Tempcode

Fractional editing is activated via the FRACTIONAL_EDITABLE directive.
The directive takes the following parameters:

• The first parameter [required] is the raw (unrendered) source text that is edited (e.g. raw Comcode)
• The second parameter [required] is the field name used in the normal edit form
• The third parameter [required] is a page-link to the edit actualiser (i.e. where the edit form goes to)
• The fourth parameter should be set to '1' if the field supports Comcode
• The fifth parameter should be set to '1' if visible editing links should be used (as opposed to needing a special click).
• The sixth parameter is '1' is if an access check passed otherwise '0' (if omitted, does an Admin Zone access check instead).

The inner content of the directive is the displayed (rendered) text (e.g. parsed Comcode, or at least HTML-escaped text) – it is what would be there anyway if there was no directive.
E.g.:
This example is using a page-link of a fake example module called cms_example, in the CMS zone. It has an actualiser screen at _edit, and ID #12 is being edited.

The sixth parameter may be given the value of this SUPPORTS_FRACTIONAL_EDITABLE symbol.
The symbol takes the following parameters:

• The first parameter [required] is the same page-link as the third parameter to the directive. This is used to check zone and page access to the edit page.
• The second parameter [required] is for further checks. In the below example I'm seeing if the current user is the content's original submitter.

E.g. {$SUPPORTS_FRACTIONAL_EDITABLE,cms:cms_example:_edit:12,{$EQ,{SUBMITTER},{$MEMBER}}}

Edit widgets

Before calling the FRACTIONAL_EDITABLE directive, you can set a Tempcode variable to identify what field widget to edit with.
You may use:

• line
• textarea
• Or, a |-separated list of list options

Example for line editing:

Example for text editing:

Example for list editing:
Or you can fetch the list values automatically:

Example for member profile editing

Imagine you want to deploy a CPF on a Custom Comcode page, and want to let a member edit their own CPF from that page.
This Tempcode would make it possible:
(where field_1 represents CPF with ID #1)

The CPF_VALUE symbol is being used to get a raw CPF value. Therefore to get the rendered field value we have to map it through the COMCODE symbol.
The editing page-link is under the view screen, as there's no separate actualiser screen for member profile editing, it's built into the tab display code.

PHP

From a PHP perspective, the edit code needs to assign special field values as the default for any field that is not passed.
These field values are:

• INTEGER_MAGIC_NULL
• STRING_MAGIC_NULL

The Composr query_update method will detect these values as fields to omit from the SQL UPDATE query.

This is enough in most cases. However, you can also call the fractional_edit() function to detect if a fractional update is happening.
Using this is necessary for reading in checkbox fields, as unchecked fields cannot be distinguished from omitted fields due to an unfortunate design flaw in HTML. For example:

Templating

These 3 templates are relevant to fractional editing:

1. FRACTIONAL_EDIT.tpl – implements the HTML for the fractional editable interface
2. fractional_edit.js – implements the JavaScript for the fractional editable interface
3. CNS_MEMBER_PROFILE_ABOUT.tpl – shows how CPFs are mapped to the FRACTIONAL_EDITABLE directive. It makes heavy use of extra field metadata passed from sources/hooks/systems/profiles_tabs/about.php

See also

• Tempcode programming

Feedback

Have a suggestion? Report an issue on the tracker.