Permalink
Fetching contributors…
Cannot retrieve contributors at this time
225 lines (141 sloc) 6.29 KB
eZ publish Enterprise Component: Component, Design
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Author: Jan Borsodi
:Revision: $Revision$
:Date: $Date$
Design description
==================
Note: Widgets will not be handled for version 1.0, it might also be split into
a separate component.
Blocks
^^^^^^
User interface
``````````````
- display
Displays a widget using its run-time display method::
{display $widget [as view] [context string]}
Parameters:
- view - The specific view to display the widget in, if not supplied widget
should pick a suitable default.
- context - The current context to render in, e.g. text/plain or HTML. If not
supplied the current context is used.
- render
Renders the specified widget as Op-Codes, this can be used to have widget
components such as buttons and edit fields but not have the run-time overhead
of using real PHP objects::
{render <widget> [as view] [context string] [parameters...]}
{render button label="OK"}
{render line-edit text="Default text..."}
{render content-view as line nodeId 5}
Parameters:
- view - The specific view to display the widget in, if not supplied widget
should pick a suitable default.
- context - The current context to render in, e.g. text/plain or HTML. If not
supplied the current context is used.
The rest of the parameters are passed on to the widget. If there is a
mismatch between parameter name, their types or content it will generate an
exception.
Widgets
^^^^^^^
Widgets are reusable user interface objects which can be queried for
information or can be called to display itself in a given way (e.g. using
another template). The widget encapsulates much of the information you would
normally pass as multiple variables and allows extensions to extend some of the
functionality it handles.
.. figure:: template_widget.png
Widget interface and their supporting classes.
A widget consists of:
- id
A unique name for the widget, the component/module name should be part of
this to make it really unique. This is used to identify widgets in use.
This id can also be used as HTML id for CSS markup and Javascript usage.
- class
A classification for the widget which can tell what kind of widget it is,
e.g. push-button or line-edit. Multiple widget classes can exist for one
*class* allowing for specialization.
This name is used for fetching widgets dynamically.
- name
A name which can be displayed to the end user.
- tooltip
A short description of the widget which can be placed in the HTML.
- whatsThis
Description of the widget, what it does and how to use it. Can be shown as
help text or popped up by Javascript code.
- properties
Widgets are PHP objects so properties are accessed as any other object.
- enabled
Controls if the widget can be used or not, this can be used to turn off
certain elements of the page when for instance editing is active.
- hidden
Whether the widget is to be shown at all or not. If hidden the widget cannot
display itself anymore.
- sizeHint
Controls how the widget wants to size itself. e.g. to use as much space as
possible. This information can be tied together with CSS to get the correct
display.
- layout
Controls how to render itself, e.g. to choose the basic CSS layout (not
colors).
- control
Can return Javascript for controlling the widget dynamically.
- signals/slots
Signals the widget can emit, e.g. when the widget is displayed it can send a
signal about it which can be connected to other widgets or objects.
Also slots for signals to connect to.
- files
A list of files involved in the making of the widgets, this includes PHP
code, template files, CSS files, images and settings.
- parent
The widget which is the parent of the current one.
- children
A list of child widgets the current one is composed of.
Also all widgets supports events. Events are the communication method between
the webbrowser and the widgets. Events are generated from the input parameters
(path, request method and request parameters) and passed to a specific widget.
The same events can also be triggered by Javascript code for dynamic behaviour
(AJAX), in this case the event will trigger an event response which can be read
by the JS code.
Examples of what can be conceived as widgets (taken from eZ publish 3.x):
- The tree structure menu in the admin interface.
- The display of a content object in the admin interface consists of several
widgets, one of them is for instance the child listing.
- The navigator (google) used in most lists.
- The left and right toolbar, these again contains sub-widgets.
- The login/user box on the right.
- Each datatype in the edit field or display field of content objects.
- Smaller UI elements like buttons and edit fields can be widgets, might be too
much overhead?
The benefits of using widgets are:
- All parts related to the widgets is encapsulated in one place. Figuring out
what files belongs to a widget is easy.
- Widgets are easily reusable meaning you can build interfaces quite quickly.
- The properties of a widget makes it easy to configure, it is very clear what
each property controls. No longer does one have to figure out which variables
to pass on to an included template file.
- No more need for attribute_view_gui, attribute_edit_gui etc. The widget knows
how to display itself.
- Widgets are classes so they can be extended in PHP code to give them more
functionality.
- Widgets can be combined with dynamic Javascript code (e.g. AJAX) to change
them dynamically or fetch them on demand.
- Can in many cases replace fetch() calls.
- Widgets can be registered globally in the system so one can know what is
available for usage. A admin interface can be provided for examining
widgets.
- Fetching HTTP POST/GET variables and other processing can be done by PHP
code instead of in templates.
Questions:
1. Should classes like eZContentObjectTreeNode be a widget or should it return
a widget.
Being a widget::
{display $node}
Returning a widget::
{display $node.widget}
Keeping the widget separate is generally a good idea code wise, also this
will make it easier to override the widget returned by a custom made one.
..
Local Variables:
mode: rst
fill-column: 79
End:
vim: et syn=rst tw=79