========
epoz API
========

This document explains the epoz API for the server side (skins,
macros, views). The target audience are people who want to customize
or extend epoz. A description of the ECMA script API can be found in
JSAPI.txt.

Overview
--------

Most of the epoz magic happens client side, namely in the
browser. That's why epoz is above-all a skin containing code
interpreted by the browser. While the ECMAScripts and the button
images are static, the HTML is to be internationalized. However, that
is the only dynamic part of epoz core.

The real customization is done through custom CSS styles for the looks
and custom configuration for the logic. That concept, separating
configuration and presentation from the actual application, allows us
to use epoz in Zope2, CMF, Plone and Zope3 all the same.

The 'common' layer contains epoz core elements and default styles and
configuration. Target platform layers like 'plone' or 'zope3'
containing styles and configuration specific to that platform are set
up on top of that.

ZPT macros and slots
--------------------

The markup necessary to display the editor widget is generated in
epozmacros.html. This template defines the following macros:

* epoz_styles

  Contains the necessary default CSS includes for epoz.

* epoz_jsincludes

  Includes the java scripts necessary for epoz. Slots:

  - jsincludes: Fill this slot to provide all ECMAScript includes
  yourself.

  - extra_scripts: Fill this slot if you want to include custom
  ECMAScripts to override/extend epoz's scripts.

* epoz_fulleditor

  Contains the full editor, i.e. buttons and the rich text widget. No
  slots are defined on this level. All of the slots of the submacros
  can be filled, though.

  Submacros:

  * epoz_toolboxes

    Contains epoz tools, such as a search box for making links to
    other content objects. Slots:

    - extra_toolbox: Fill this slot if you want to add another toolbox

  * epoz_toolbar

    Displays the epoz toolbar containing the format selector and
    buttons. Slots:

      - extra_buttons: Fill this slot if you want to add more buttons
      to the toolbar

      - extra_toolbar: Fill this slot if you want to add another
      widget to the toolbar (which is not a button; use extra_buttons
      for adding buttons)

  * epoz_editorframe

    Contains the editor iframe and the invisible textarea. Slots::

     - epoz_inputfield: Fill this slot to include your custom input
     field (typically a text area). This is usefull for telling epoz
     the name of the field, for example.

Non-standard XHTML attributes for configuration
-----------------------------------------------

  * dst

    The destination of a PUT action (save).

  * usecss

    Makes the editor produce CSS whenever possible. Works only in
    Mozilla.

  * reloadsrc

    Reload the source after a save action. Due to some problem with
    Mozilla, setting this to "1" will make the full page reload
    instead of just the editor frame.
