diff --git a/docs/ZMI.rst b/docs/ZMI.rst index f9931792cd..82ab41e13f 100644 --- a/docs/ZMI.rst +++ b/docs/ZMI.rst @@ -98,3 +98,165 @@ 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 ``
``. +Ususally
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. + +.. raw:: html +
+ +
+ +
+
+ +The following buttons are constructed as div element with the classname +``zmi-controls``; the buttons use systematically the bootstrap class pair +``btn btn-primary``. + +.. raw:: html +
+ +
+ +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``) + +.. raw:: html + + + + + +
+ +

+ 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 browse button to select a local file to upload. +

+ +
+ + +
+ +
+ +
+
+
+ +
+ + +
+ + + + + + +
+ +
+ + +
+
+
+ + +
+
+ +
+
+
+ + +
+ + + +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 +```` 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 ``
``-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. \ No newline at end of file