Epoz API reference

Epoz can be customized in several ways: controls can be customized or hidden
using CSS, elements can be modified using TAL (modifying the macro) and more
advanced customization can be done by extending (or modifying, although this is
usually not advised) the JavaScript, either in the macro or in seperate .js
files. This document will give a short description of how to use and extend the
Epoz JavaScripts and a reference of the public Epoz API.

HOW TO USE EPOZ

The EpozEditor and EpozUI objects

Generally the body tag of the document will contain a call to the initEpoz
function. This is the glue code of Epoz, here's where all the objects get 
instantiated and tied together to form the application. When doing large 
customizations, this function will usually be overwritten or extended. The
default implementation takes 1 argument (the id of the iframe it will control)
and return a reference to the core object, EpozEditor. 

    epoz = initEpoz("epoz-editorframe");

The EpozEditor object (in this case called 'epoz') will be the object with 
which you can control the iframe, the UI and tools. Customizations should 
generally not involve extending the EpozEditor object, but rather by 
plugging in new tools. Usage is quite straightforward, for a reference of
the public methods see below.

The UI object holds event handlers for the toolbar buttons. This is a core
Epoz object and should generally be left untouched. The event handlers, 
although the preferred method of attaching events is dynamic from
inside the objects rather then from HTML, should be attached to the buttons
from the template (this made the code a lot cleaner, it might change in future
versions though). Therefore a reference to the UI object must be retrieved 
from the EpozEditor object using the getTool method:

    epozui = epoz.getTool('ui');

Note that the reason why this method is called getTool is that the UI is 
essentially treated as a tool, more about those later. The string 'ui' is 
the id by which the object is registered in initEpoz. Usually the ui object
and the button bindings can just be copied from the epozmacros.html macro
(if you don't just use the macro file), if not a reference of how this can be
done can be found in the macros, so I won't spend any time on discussing that
here.

Tools and extending Epoz

Tools are extensions of Epoz. A tool can be seen as a plugin in the Epoz 
editor, providing additional functionality. Tools will usually be the objects 
that will be extended or overridden. 
A tool should usually subclass EpozTool and will usually override the 
initialize method (which will be called when the tool is registered to the 
EpozEditor object) and the updateState method (which will be called on click 
and certain keyup events on the iframe so that the state of the tool (e.g. 
add or edit mode) can be controlled. Events on elements should generally be 
bound to the methods from inside the tools.
The initialize method will be called with a single argument, a reference to 
the editor object. The method should at least store that reference on this. 
Note that if you don't override the method, the EpozObject class provides 
a default implementation that does exactly that.
The updateState method will be called with 2 arguments, the first is a 
reference to the current selected element and the second the event object.
If the tool doesn't want to react to state changes, it doesn't have to 
override the method: the superclass will provide a dummy implementation.

Usually a tool will be created and registered inside initEpoz, although it
can also be done from an external document or the HTML. An object is registered 
to the EpozEditor object as such:

    var myTool = new MyTool();
    epoz.registerTool('my-tool', myTool);

As shown above, the getTool method of the EpozEditor object can be used to
retrieve a reference to the tool later on (so there's no need to store a
reference in the global namespace or anything).

For a nice, small example of a tool, see the PathTool in the epozeditor.js
file. For a more complex (and useful) example see the LinkTool.

PUBLIC API

Methods on EpozObject:

    registerTool(id, tool) 
        - register a tool

    getTool(id)
        - return a previously registered tool

    updateState(event)
        - trigger the updateState machinery

    saveDocument()
        - save the document

    getSelectedNode()
        - returns the currently selected node

    getDocument()
        - returns the document object

    getInnerDocument()
        - returns the iframe.contentWindow.document

    insertNodeAtSelection(node)
        - insert a new node on the cursor location

    logMessage(message, severity)
        - log a message with the logger, message is the message to log and
            severity is an integer that can be 0 (default) for debug messages,
            1 for warnings and 2 for errors (different loggers can be plugged
            into Epoz, but a severity of 2 will usually make the logger raise
            an exception).

Useful helper methods on the EpozEditor object:

    _getBrowserName()
        - return the name of the client browser, will return IE, Mozilla
            or raise an exception if the client uses a non-supported one.

    _addEventHandler(element, event, method, context)
        - bind <method> to <event> on <element>, using <context> as context
            ('this' inside the method body).

Methods on tools (methods beginning with an underscore are either private
    or helper methods):

    EpozTool - the baseclass for tools

        initialize(editor)
            - initialize the tool

        updateState(selectedNode, event)
            - update the state of the tool if required

        _addEventHandler(element, event, method, context)
            - bind <method> to <event> on <element>, using <context> as context
              ('this' inside the method body). This method is duplicated from
              EpozEditor._addEventHandler and will probably be removed in future
              versions.

        _selectSelectItem(select, item)
            - select an item from an HTML <select> element

Of the remaining tools only public method will be described.

    ColorchooserTool - the color picker (part of the toolbar)

        openFgColorChooser()
            - open the colorchooser to pick a foreground color

        openBgColorChooser()
            - open the colorchooser to pick a background color

        chooseColor()
            - event handler for a click inside the colorchooser

        show()
            - show the colorchooser

        hide()
            - hide the colorchooser

    PropertyTool - set the title and metadata of a document

        updateProperties()
            - set the properties on the document from the form data

    LinkTool - add and edit hyperlinks

        addLink()
            - add a link according to the form data

        updateLink()
            - update the current link according to the value in the input
              field, this method may be removed in the future

    ImageTool - add images

        addImage()
            - create image according to form data

    TableTool - add and edit tables

        addTable() 
            - add a table according to the data in the form

        addTableRow()
            - add a row underneath the current selected one

        delTableRow()
            - delete the current table row

        addTableColumn()
            - add a column to the right of the current one

        delTableColumn()
            - delete the current table column

        setColumnAlign()
            - set the alignment of the current column according to the form
              data

        setTableClass()
            - set the table class according to the form data

    ListTool - manage lists (part of the toolbar)

        addUnorderedList()
            - add an unordered list

        addOrderedList()
            - add an ordered list

        setUnorderedListStyle()
            - set the style of the nearest unordered list parent according to
              the form data

        setOrderedListStyle()
            - set the style of the nearest ordered list parent according to
              the form data

    ShowPathTool - show the path to the current node in the status bar

        no methods besides updateState()

Additional helper objects and methods:

    Logger objects:

        When the EpozEditor gets initialized, it expects a logging object
        with one method (log(message, severity)) to be passed along as an
        argument. Two loggers are defined: 1 called DebugLogger that will
        alert all messages and 1 called PlainLogger that should be
        instantiated with the ids of the element in which debug messages will
        be shown and the maximum number of messages as arguments, that will
        show all debug messages and warnings to the debug window and will
        raise an exception for all errors.

    ContextFixer:
        
        A helper class to fix the contexts in methods when called in a specific
        way (usually when used as an event handler). In some cases the 'this'
        variable inside functions can change, this class helps in resetting it
        to the object on which the method is defined (and actually it can help
        in setting a different context as well, although this will not
        generally be advised). For more information see the source.

    Timer:
        
        A herlper class to overcome a problem with window.setTimeout(), this
        has the problems that it isn't usable to call object methods without
        very nasty complications and that it doesn't allow usage of variable
        references as arguments (both because the argument that is executed is
        a string that will be evalled in global context). For more information
        see the source.

    Array.prototype.contains(element):

        - a helper method added to the prototype of Array that will return
          true if element is in the array, false if it isn't.
