Latest revision as of 00:14, 22 May 2008

Basic Page Contents

The editor may be represented in many different ways in the page. The toolbars may be attached to the editing area, placed away of it, or even totally hidden. Even the editing area itself is totally optional, or can be replaced by other things, like a pure source editor, or even a ready only panel. There is just one thing that we'll always have at a minimum: a textarea element.

Each editor instance will always be represented by a textarea. That textarea can either be present on the page right from the start, or created by the editor API itself. This textarea is the form element to be used to hold the editor data on form posting.

On browsers with JavaScript disabled, we'll have our plain textarea rendered, making it possible to the user to type inside of it and still post the data. On unsupported browsers, we'll have this same behavior, which is the expected result.

To exemplify, the following is the minimum code present in the page:

<textarea name="MyEditor"></textarea> 

Page Loading and Transformation

Somehow, the editor API is called and a textarea is identified as an editor instance. At this point, the first transformations start to happen.

It is important to note that there are two ways to create the editor interface in a page:

• Inline when loading the HTML, so the editor interface will be visible as soon as the page displays. This method brings some delay to see the page structure.
• On window.onload, so the entire page becomes visible without the editor, and then the editor is downloaded and its interface created after it. This option makes it possible to the user to start reading the page earlier because the page should load a bit faster.
  

More important for the second loading option than for the first one, the very first thing to be done is making the textarea invisible:

<textarea name="MyEditor" style="visibility:hidden"></textarea> 

The above is done to avoid strange/ugly rendering effects with the textarea while rendering the page, even before the editor interface be ready. For example, there will not be a flashing textarea visible on half page loaded.

At this point, the API knows about the textarea, and that an UI must be created for it.

UI Creation

As soon as the API is fully loaded, the UI creation starts for each registered editor instance. Newly registered instances have their interfaces rendered immediately.

There are two code blocks involved at this point:

• UI Builder: produces the markup that goes in the page, dialogs, etc. It's limited to the structure definition.
• UI Components: fills the UI Builder markup placeholders with design.
  

Both the UI Builder and the UI Components are plugins, which can be completely replaced. It means that the UI is not supposed to be fixed. It also means that compatibility must be guaranteed between the UI Builder and the UI Components plugins.

Default UI Builder

By default, the editor includes a "classic" UI Builder, which provides placeholders for the most common editor structure, containing three horizontal spaces grouped inside a single box:

• "Top": a dynamic height space, by default used for the toolbar.
• "Middle": a full expanded height space, by default used for the editing area.
• "Bottom": a dynamic height space, by default used for the elements path and resize handle.
  

The default UI Builder will place the entire interface space inside a box with the size and position of the replaced textarea.

Default UI Components

As soon as the UI Builder completes the structure creation, its placeholders are ready to be filled with graphical elements. This job is done by the registered UI Element plugins.

By default, the editor provides a basic set for the most common UI needs, containing:

• Toolbar (at "Top" placeholder): the default toolbar groups a set of graphical interface elements to be used to manipulate the editor and its contents.
• WYSIWYG Editing Area (at "Middle" placeholder): is the default editing space, where users can type text, include layout elements like images or table, having an immediate preview of the final results.
• Source Editing Area (at "Middle" placeholder): a plain textarea space used to edit the raw data representing the contents (by default HTML).
• Elements Path (at "Bottom" placeholder): a space listing the full elements hierarchy for the current selection in the WYSIWYG editing area.
• Resize Handle (at "Bottom" placeholder): a graphical element that can be used to resize the editor.
• Context Menu (placeholder independent): just like the toolbar, it groups a set of graphical interface elements to be used to manipulate the editor and its contents. The main difference with the toolbar is that this menu is contextual to the current selection in the editing area.
  

Data Loading

Once the UI is ready, the first data load finally happens. The API calls the plugins registered to handle the data manipulation and rendering.

The editor is ready to be used.