Layout builder specs

Overview

Thiblo layout builder is a tool, inside the account page, designed to help users in creating custom templates for their journals. This goal is achieved by providing a GUI tool for editing template's structure and content boxes.

This spec was accepted by Baldvin (June 26, 2008). However, comments are always welcomed.

Non Goals

This version will not support the following:

• WYSIWYG (or similar) tool for designing content boxes. Users will have to edit boxes' source code manually, in a special field.
• Drag and drop feature for content boxes.
• Syntax highlighting for the raw mode.
• Undo feature (we may add it later though). So, if user deletes the box, it is gone. Completely. Like never existed.

Modes

Layout builder supports three general modes: edit, preview and raw. User can switch from one mode to another at any time while working with layout builder. However, their mistakes may stop the switch until resolved (more on this below).

You can found a static sketch of the layout builder here:  http://anton.kovalyov.net/labs/js/layout_builder/

Edit mode

In the edit mode, user can design his template core structure in a WYSIWYG way by visually building an HTML table. In it, each cell is bordered so it is easy to distinguish on from another.

If user moves a mouse over the cell, it is highlighted and its action links are activated.

Layout builder supports the following action links for each cell:

• Add a cell (to the left, right, top and bottom) links;
• Expand a cell (to the left, right, top and bottom) links;
• Merge a cell (to the left, right, top and bottom) links;
• Delete current cell;
• Set a cell's content (it can be either a content box or a nested table);
• Edit cell's properties and source code (if it is a content box).

NOTE: Action links (for a particular cell) are not visible until the mouse is over the cell.

Clicking on empty area of a cell does nothing.

Preview mode

In the preview mode, actual result is shown, without any technical borders and higlightings. All content boxes are filled with test data (see below). Here, user can do no more than preview his work and switch to another mode.

Raw mode

In the raw mode, user can manually tweak the code for his template core structure in a special field.

User can switch to any other mode *only* if his code is valid. In any other case, the message is shown and the switch is stopped.

Also, in this mode, user can edit a stylesheet for the template. CSS, defined in the raw mode is stored on a file system and linked in the database as an 'external_stylesheet'.

Features details

Name and description

User can update template's name and description by filling appropriate fields.

Action links

Add links

If user clicks on the add link, a new cell is appended to the appropriate side and the table is updated (link here). User can add as many cells as his moral rules allow.

Example. A cell added to the bottom of the Cell 2:

Cell 1

Cell 2

→

Cell 1

Cell 2

New!

 

NOTE: A new cell is just an intermediate step. In order to use the cell, user has to choose if it going to be a content box or a nested table.

Example:

Content box or nested table

After the new cell is added, the system checks if the resulting table is valid and appends new empty cells where needed if it is not.

Expand links

If user clicks on the expand link, the current box increases its colspan (or rowspan) properties.

Example. Cell 1 is expanded to the right.

Cell 1	Cell 3
Cell 2	Cell 4

→

Cell 1		Cell 3
Cell 2	Cell 4

 

After the expansion (i.e. when col/rowspan property is increased) the system checks if the table is valid (in sense of XHTML) and appends empty cells where needed if it is not.

Merge links

If user clicks on the merge link, the current box increases its colspan (or rowspan properties) and drops the cell if there is any on the selected side. So, actually, it is a "merge two cells by keeping only one (active one, to be precise) of the contents" operation.

In the example below, user clicks on the merge link on the right side of cell 'a'. Selected cell is expanded to the right (colspan + 1) and cell 'b' is deleted.

a b c d

→

a c d

If no ordinary cell exists on the selected side while merging, this operation acts just like 'expand'.

Delete

If user clicks on the 'delete' link, the current box is deleted and the table is appropriately updated.

Edit properties

If user clicks on the 'edit properties' link, a new pseudo-popup window is open. There, he can edit box properties, its source code and define CSS rules for this box. Each box can have its own CSS rules.

NOTE: There is an open issue related to this feature. See 'Open Issues' section.

GUI for the propeties/source code editor is as simple as this (opens just like standalone wcb window):

(properties tab is a name-value table just like in journal's properties)

User can save the source or properties if and only if they are valid in a sense of syntax and allowed values. In any other case, an error message is shown.

The source code, for the box, is a combination of HTML and Django template language.

Empty automatic cells

In order to keep the table valid (i.e. to keep a balance rows and columns), after each add, expand or delete a cell operation empty cells automatically added where needed.

Example. After the Cell 1 is expanded to the right, new empty cell is added next to the Cell 4.

Cell 1	Cell 3
Cell 2	Cell 4

→

Cell 1		Cell 3
Cell 2	Cell 4

 

NOTE: Empty automatic cells has transparent background and no borders at all.

Empty automatic cells are reusable: if user wants to use their space, the system will allow it. For example, if user wants to add a new cell to the bottom of the active one and there is already an empty cell exists, the system will replace this empty cell with a new cell. In the example below, user adds a new cell 'e' next to the cell 'a'. Then, an automatic empty cell is added just under the new cell 'e' (we can't just move 'd' to that place because if user has placed it under the 'b', he may have some intentions and we can't mess with them). This empty cell is just like nothing (used only to keep a resulting table valid).

Then, user tries to add a new cell 'f' just under the cell 'e' (and we have an empty cell there). Because, as mentioned above, empty cells are nothing, system simply replaces the empty cell under the cell 'e' with brand new cell 'f'.

a b c d

→

a e b c   d

→

a e b c f d

The system acts this way no matter what operation, add, expand or merge, is fired.

Nested tables

Cells can have nested tables as their data. It means, that user is able to use just the same actions on nested tables as on their parents (i.e. add or expand cells, manage properties of the content boxes and even add more nested tables).

Test data

Each cell is given a static, random test data for the special variables 'articles' and 'article' no matter what query func is used.

Box import

Users can easily clone every box on every public weblog powered by Thiblo. To clone/import a blog, user selects a content box on his own weblog (in the edit mode), opens properties wizard (see Edit properties section above) and clicks on the 'import' link.

After that, a new browser-like pseudo-window (like in the account page) opens. There, user can enter URL of the blog from where he wants to import a box. Then this blog opens in a special import-mode which means that all information is filled with static, random test data and boxes are selectable (like in the edit mode, however, user can't edit or delete boxes there). To import a box, user clicks on it. Pseudo-window closes and properties wizard gets an updated information about new box's properties (NOTE: on this stage, box is not saved yet).

After user updates new box's source code and/or properties, he clicks on a 'save' button. Done!

My drafts: