Skip to content

Commit

Permalink
Merge pull request #329 from zopefoundation/docs_zmi
Browse files Browse the repository at this point in the history 
added documentation about zope4 ZMI template updating
  • Loading branch information
@dwt
dwt authored Oct 2, 2018
2 parents 1d78cfa + 68a6d63 commit 655812b
Showing 1 changed file with 165 additions and 0 deletions.
165 changes: 165 additions & 0 deletions docs/ZMI.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,3 +98,168 @@ The properties can have one of the following types:
The value of the property has to be one or more paths/URLs to CSS resp.
JavaScript which will be included in the HTML of the ZMI. (Paths have to be
resolvable by the browser aka not simple file system paths.)


Update your Zope2 ZMI template code
+++++++++++++++++++++++++++++++++++

The old Zope2 styling rules did not allow a modern and responsive design. Nnow
the Zope4 ZMI uses some basic CSS class names of the bootstrap CSS framework
and structuring concepts for page layout and forms. A ZMI page usually sequences
following templates nesting the page core:

1. manage_page_header()
2. manage_tabs()
3. page core
4. manage_page_footer()

The page core of any form or object listing ZMI template is starting by the
html element ``<main class="container-fluid">``.
Ususally <main> is nesting a p-element for a help-text and the actual form.
To make specific form styling possible the form-element has following CSS names:

1. zmi-$classname
2. zmi-edit|-add


In general specific functional ZMI elements are declared by a CSS class with a
prefixed ``zmi-`` whereas the basic layout is done by usual bootstrap classes
fowllowing the typical element nesting:
any form element has a bootstrap-like form-group structure containing a label
and an input field. Important: The width of the input field is defined by the
nesting div-container using the responsive grid classes ``col-sm-9 col md-10``.
With the classes ``col-sm-3 col-md-2`` for the label, a complete bootstrap row
of 12 is filled.

.. code-block:: html

<div class="form-group row">
<label for="title" class="form-label col-sm-3 col-md-2">Title</label>
<div class="col-sm-9 col-md-10">
<input id="title" class="form-control" type="text" name="title" value="<dtml-if title>&dtml-title;</dtml-if>" />
</div>
</div>

The following buttons are constructed as div element with the classname
``zmi-controls``; the buttons use systematically the bootstrap class pair
``btn btn-primary``.

.. code-block:: html

<div class="zmi-controls">
<input class="btn btn-primary" type="submit" name="submit" value="Save" />
</div>

The following example code shows a whole restructed DTML template rendering the
Zope4 ZMI

**Example: updated DTML template**
(from: ``../Zope/src/OFS/dtml/documentEdit.dtml``)

.. code-block:: html
:linenos:

<dtml-var manage_page_header>

<dtml-var manage_tabs>

<main class="container-fluid">

<p class="form-help">
You may edit the source for this document using the form below. You
may also upload the source for this document from a local file. Click
the <em>browse</em> button to select a local file to upload.
</p>

<form action="manage_edit" method="post" class="zmi-dtml zmi-edit">

<dtml-with keyword_args mapping>
<div class="form-group row">
<label for="title" class="form-label col-sm-3 col-md-2">Title</label>
<div class="col-sm-9 col-md-10">
<input id="title" class="form-control" type="text" name="title"
value="<dtml-if title>&dtml-title;</dtml-if>" />
</div>
</div>
<div class="form-group">
<textarea id="content" data-contenttype="html"
class="form-control zmi-code col-sm-12" name="data:text" wrap="off"
rows="20"><dtml-var __str__></textarea>
</div>
</dtml-with>

<div class="zmi-controls">
<dtml-if wl_isLocked>
<input class="btn btn-primary disabled" type="submit" name="submit" value="Save Changes" disabled="disabled" />
<span class="badge badge-warning" title="This item has been locked by WebDAV"><i class="fa fa-lock"></i></span>
<dtml-else>
<input class="btn btn-primary" type="submit" name="submit" value="Save Changes" />
</dtml-if>
</div>

</form>

<dtml-unless wl_isLocked>
<form action="manage_upload" method="post" enctype="multipart/form-data" class="zmi-upload mt-4">
<div class="input-group" title="Select Local File for Uploading">
<div class="custom-file">
<input type="file" name="file" class="custom-file-input" id="file-data" value=""
onchange="$('.custom-file label span').html($(this).val().replace(/^.*(\\|\/|\:)/, ''));" />
<label class="custom-file-label" for="file-data"><span>Choose file</span></label>
</div>
<div class="input-group-append">
<input class="btn btn-outline-secondary" type="submit" value="Upload File" />
</div>
</div>
</form>
</dtml-unless>

</main>

<dtml-var manage_page_footer>

More details
------------

**Textarea:**
A textarea element for editing template or script code uses the JS library
``ace`` for syntax high-lighting and line numbering. Textarea elements which
are declared by the CSS class ``zmi-code`` are transformed into an ace-editor
field. Moreover this element has an attribute ``data-contenttype`` which is
needed by ace-editor to determine the fitting syntax high-lighting.
ZPT-Example see: ``../Zope/src/Products/PageTemplates/www/ptEdit.zpt``

**File upload element:**
The file upload element has it's own form container (classfied as ``zmi-upload``).
All subsequent elements are nested as 'input-group' containing a div classified as
``custom-file`` nesting the actual input element. An inline JS fired on the
onchange-event beautifies the file name showed after selecting it.
ZPT-Example see: ``../Zope/src/Products/PageTemplates/www/ptEdit.zpt``

**Hints and Warnings:**
Some input fields show additional information; these are added as element
``<small>`` directly following the referred inout field. (Both element are nested
by the width defining div-container). Possible text colors are declared by
typical bootstrap class names like ``text-warning``.

**Icons:**
Zope4 object classes which are shown in the ZMI have declared a class variable
``zmi_icon``; this string corresponds to an appropiate font icon-CSS class
supplied by the Fontawsome web font (https://fontawesome.com/icons)

**Tables:**
Bootstraps requires an explicit CSS class ``table`` for any table; especially
long item lists should get an additional CSS class ``table-sm`` and maybe another
class ``table-striped`` for a better readability. Finally it is recommended
to add a specific id attribute like "zmi-db_info". The general table structure is
compliant to bootstrap standard table (https://getbootstrap.com/docs/4.1/content/tables/).

**ZMI-classes:**
All basic stylings of the zmi-elements are defined in the CSS file, see:
``../Zope/src/zmi/styles/resources/zmi_base.css``

**Implicit handling of old Zope2 ZMI templates:** Old templates which do not
contain the ``<main>``-element are automattically postprocessed by a Javascript
function in the browser. The DOM is minimally modified, so that old forms will fit
*somehow* into the Zope4 layout. In the page footer a hint about this autoamtic
customizing is shown.

0 comments on commit 655812b

Please sign in to comment.