Editable Web Documentation

Loader †

To make a page editable, it needs a loader. The loader is a small dagger sign † at the top right of the page. You click on this to load up the editable web. One way to add the loader is by adding a script to the page's header, and make it's "src=" point to the directory on your webserver where you unzipped the Editable Web files.

<script type="text/javascript" defer
        src="/editable/editable.js"></script>

When you click the loader sign, the browser remembers it in a cookie. You won't need to click it again this session.

Greasemonkey Loader †

Users of Firefox/Greasemonkey can instead use a greasemonkey script (on the download page) to add the loader symbol to any page. By default it adds loader sign to every html page, but you'll no double set it to include only your own website.

If you're viewing a page http://myserver.com/a/b/c.html, then the greasemonkey loader looks first in /a/b/editable/* for the Editable Web directory that you unzipped, then /a/editable/*, then /editable/*.

Editable blocks

To edit a part of the web page, click on it or select some text in it. The Editable Web will put an "editing mark" † at the top right of its block. You click on the editing mark to start editing that block.

A block is defined as the smallest DIV or PRE or table cell which encompases the cursor and any text that's selected. So you can just click in a table cell to edit that cell, or you can select several cells to edit the whole table and what's outside it, and so on. (Control-click will instead select the largest enclosing block - i.e. the whole document).

Also, at the top-left of the page there's a small circle °. Click this to edit the page's title, description and keywords.

Editing Buttons < † ‡ o x

When you click an editing mark at the top right of a section, it switches into an editable thing that you can type into. There will be a few editing buttons at its top right:

< The revert button lets you revert back to an earlier version of the page.

† The edit button lets you edit the block in WYSIWIG mode, What You See Is What You Get.

‡ The raw-edit button lets you edit the block in plain raw markup mode, to edit the HTML source code.

o The submit button saves your changes once you're done.

x The cancel button undoes any editing you've been doing.

Markup blocks

If you hold down the Control key while you click on a block, it will go straight into raw markup editing rather than the WYSIWYG editor. In fact, it'll first fetch the exact page source code from the webserver before giving it to you to edit. This way it preserves your formatting perfectly.

You can make a block so it only does markup, i.e. prevent users from accidentally editing it in WYSIWYG mode. Do this by enclosing it inside <div editable="markup"> ... </div>.

Code block

Create a "code block" by clicking on the CODE button in the WYSIWYG toolbar (or, in raw markup mode, enclose it with <pre editable="code"> ... </pre>). A code block again operates on raw text, and preserves the formatting of that text. It also provides syntax-highlighting for C++, C#, Javascript, PHP and HTML. You'd use it if you're writing a web page with programming examples. Here's what it looks like:

void f(int x)
{ if (x<=0) return 1; else return x*f(x-1);
}

function f(s)
{ var m = /^(regular).*?(expression)$/.exec(s);
  if (m) return m[0]+"hello world"; else return m[1];
}

<html>
<body>
<p style="background-color:yellow;">This is yellow</p>
</body>
</html>

Comment blocks

A comment block is one enclosed by <div ip="123.1.2.127"> ... </div>, or some other IP number or machine name. Anyone who views the page can edit the comments they have made previously, based on an IP-number check. (This is not a robust check, but it's good enough for the sort of freeform collaborative editing that we want to see.) If there's a special comment block with ip="*" then anyone can click on it to add a new comment.

Notifications of changes

Whenever a page has been changed, or a comment added, the system looks for a file "editable_notify.txt" in the page's directory (or in higher directories if it couldn't find it there). In the file, you should put one notifyee per line, e.g.

someone@to.email.com
someone@else.email.com
changes.xml
../allchanges.xml

The xml files are RSS feeds. When you make an edit to your pages, these will be updated with a summary of that change. When someone visits your site and leaves a comment, it updates the RSS feeds and also sends emails to the people listed. This way you can stay aware of all changes, and visitors can too.