Pencils

A plugin to edit contents directly on the public site

A plugin for SPIP that makes it possible to edit the contents through your website’s public pages, without entering the admin area.

Pencils (or ’Crayons’ in french) is a plugin for SPIP that makes it possible to edit the contents through your website’s public pages, without entering the admin area.
Configuring templates to use the plugin is very easy. It consists in adding the class #EDIT{...} to elements you wish to make editable.

Update

Version 1.0 was published on 23 April 2008.

Overview

When the plugin is activated content can be eidted directly, “in situ” on the public pages of the site by those logged in with with the appropriate rights.

You need to adapt your templates to make them compatible with the plugin (Note: most of the templates available on spip-contrib are already compatible). The principle is simple: a field is editable if it contains the class crayon objet-champ-id. This class can be produced using the tag #EDIT{}. For example, in order to render the title of articles editable, you just need to replace the line

<h1>#TITRE</h1>
by
<h1 class="crayon article-titre-#ID_ARTICLE">#TITRE</h1>

Another example: to use “Crayons” on the text field of articles, change:
[<div class="texte">(#TEXTE|image_reduire{520,0})</div>]

to:
[<div class="#EDIT{texte} texte">(#TEXTE|image_reduire{520,0})</div>]

N.B. The pages in question must contain a </head> tag (written in small letters).

Operation

Server-side

When a page is loaded, the plugin acts using the pipeline affichage_final.

It checks:

• if the user is authorised;
• if the page contains at least once a series of characters “crayon xxxx-yyyy-nn”;
• and if the user has the permissions to edit at least one of the elements marked in this way.

If these conditions are satisfied, the plugin inserts the external script crayons.js in the <head> section of the page and also the configuration data. When the page is fully loaded the script executes, checking at regular intevals if new crayons have become available, in order to activate them if necessary.

When the page has finished loading (and if the visitor has editing permissions for the crayons present), the crayons.js script selects all the elements with the class crayon type-champ-id, and, for the ones for which the user is authorised, adds a clickable image (a pen) together with the class crayon-autorise to show that these texts are available for editing.

A click on the pen or a double-click on the element itself activates the editing form.

Activation of the crayon

A click on the “crayon” (or a double-click on the element) triggers a request to the server to send the editing form to replace the displayed element.

The request specifies the “type”, le “champ” (field) and the “id” for which the form has been requested.

Having checked that data exists and the permissions on it, the server sends the form (as JSON-format Javascript data). The type of form used and its dimensions are determined by the kind of element concerned and the space it occupies. The form contains the raw text of the field, as it was entered in the admin area, but the display size, font and colour of the characters are preserved.

crayon.js links this form to the underlying field and caches the contents of the latter.

The user can now edit the data.

N.B.: It is only the server which is able to display the final result. A click outside the editiing zone will once again show the original contents of the field.
When editing is interrupted in this way, a cogwheel alerts you that you have started changing the field. A click on the wheel or a double-click on the element takes you back to your changed version — the changes are not lost.
If you leave the page, a final reminder asks you if you wish to save your changes.

Saving the changes

The form has a series of buttons:

• OK (as well as the Enter key [1]) saves the changes,
• Annuler (as well as the Esc) abandons all changes made to the original text,
• A click outside the editing zones places the changes in cache and returns to the original display.

The form also contains the id of the data and the keys linked to it.

The form is submitted by POST using ajaxForm asynchronously. When it receives it, the server:

• analyses the data submitted, checking its consistency and its freshness (so as to annul it if the same data has been modified elsewhere in the meanytime);
• re-checks the editing permissions;
• calls the standard SPIP procedures to update the data.

Any updates are recorded in the version-tracking system in SPIP just as they would have been if they had been made in the admin area.

Configuration

Several configuration options are available through the use of the CFG plugin. In particular:
-  if it is necessary to confirm “OK” when nothing has been changed;
-  whether to show a warning about saving the page if you try to navigate away from the page while a change has not yet been confirmed;
-  the activation of the typographical shortcut bar;
-  colours which make it easier to see which zones are editable.

N.B. If the plugin is not installed or deactivated, the #EDIT{...} tag returns an empty string. This means that templates can be made “crayons compatible” without risk, even if in the end you decide not to use the plugin.

Extended use

Crayons can be used with all SPIP’s standard tables (articles, brèves, rubriques, etc.). It is also possible to use crayons for forums et les signatures, but, for these last two, the plugin “Autorité” also needs to be installed to allow modifications.

For all the tables, fields of “line” type (title, subtitle, etc.) and of “text area” type (text, description, summary/deck) can be edited.

logos can also be edited by using the crayon #EDIT{logo}; a control is provided to resize logos on the fly, during upload.

documents can be edited using #EDIT{fichier}. In this case the new document replaces the old one and the filesize, as well as, in the case of graphics, the height and width are updated in the database (N.B. Not yet compatible with remote documents).

Finally, but only with recent SVN versions of SPIP, it is also possible to edit the champs extra.

Notes:
-  Crayons can be used with any table, on the condition that it has a numeric primary key called id_xxx, where xxx is the name of the table.
-  If a “crayons” text is a MEDIUMTEXT or longer MySQL field, the plugin displays a TEXTAREA, in other cases it displays an INPUT field.
-  Only full administrators can use crayons on texts from non-SPIP tables.

To do

The editing form (« contrôleurs ») as well as the view obtained can be overridden using simple templates (see the examples in the plugin’s controleurs/ and vues/directories).

The forms can be used simultaneously to edit several fields of a record (article), or even several records from one or more tables: all the flexibility needed to build specialised and efficient editing interfaces.

As always, contributors are welcome!

Footnotes

[1Or, on the Mac, pressing Ctrl-S, and on PCs Alt-S or F8.

Les crayons ont un mode de débug activable en mettant dans mes_options.php la ligne suivante :
define('_DEBUG_CRAYONS', true);
Ce code ralentit un peu le fonctionnement, puisque le script est rechargé à chaque fois, mais facilite le repérage de bugs et le développement de nouvelles fonctionnalités.

Discussion

2 discussions

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

• Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
• Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
• version de SPIP, en bas de la partie privée
• version du plugin testé et des éventuels plugins nécessités
• version de PHP (exec=info en partie privée)
• version de MySQL / SQLite / PostgreSQL
• Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
• En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparait.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Who are you?
This form accepts SPIP shortcuts {{bold}} {italic} -*list [text->url] <quote> <code> and HTML code <q> <del> <ins>. To create paragraphs, just leave empty lines.