www.zope.org

old.zope.org
- /Products
- /Members

Log in

Forgot your password?

The EpozDocument presentation

This is the copy of the README.txt file included with the latest EpozDocument.

The EpozDocument Product 0.3.0

An EpozDocument is a pure content HTML object which edit tab has the Epoz widget.

Main features

Edition of the content through Epoz, using your stylesheet if provided. A full featured Epoz toolbox creates links or inserts images with absolute or relative URLs.
An EpozDocument may be published through a template through its own URL: apply your stylesheet and HTML formatting when publishing an EpozDocument.
External editor aware: you can edit an EpozDocument content with your favorite text or HTML editor.
ZCatalog awareness: Your content is automatically indexed in a ZCatalog. You may now use a ZCatalog with id other than Catalog (new in this release).
Keeps the real DateTime of the last edit moment in the lastEditDate property. Unlike bobobase_modification_time(), this is an export/import and copy/cut/paste safe date (new in this version).
Base for ZClass: customize EpozDocument for your own needs (new in this version).
Executes the EpozDocumentPostEditHook script if found if you want to tweak programmatically the EpozDocument content after editing it (new in this version).
Comes with a demo: install .../EpozDocument/demo/demo.zexp (new in this version). New users should install this demo to learn the "best practice" rules when publishing an EpozDocument based site.

Requirements

Epoz of course... get it from http://zope.org/Members/mjablonski/Epoz . EpozDocument now requires a 0.6 or greater version of Epoz (CSS support).
An Epoz aware browser (see Epoz documentation) with - preferably - cookies enabled otherwise you will edit the content with a poor HTML <textarea> widget :-(

Publishing an EpozDocument

When publishing an EpozDocument, it will look :

For a template which id is in its EpozDocumentTemplate string property in its acquisition path.
For a template called EpozDocumentTemplate in its acquisition path, if the former property is missing, empty or doesn'find an object.

The template may be either DTML method, ZPT or a Python script.

If found, this template gets the EpozDocument features through:

here: in a ZPT
this() or the namespace: in a DTML method. The EpozDocument is pushed on top of the DTML namespace in that case.
context: in a Python script

If no object matching above stated criteria is found, the EpozDocument is published directly.

Remember in any case, that the content of EpozDocument is its html attribute.

A ZPT sample :

   ...
   <h2 tal:content="here/title">The title of the EpozDocument</h2>
   <div tal:replace="structure here/html">
    The HTML content of the EpozDocument
   </div>
   <div>
    This page was updated
    <span tal:replace="python: here.lastEditDate.strftime('%Y/%m/%d')">
     2004/1/24
    </span>
   </div>
   ...

Anyway, you can always publish the content of an EpozDocument the old way you did for HTML Files you included explicitely in templates :

   ...
   <div tal:define="myepozdocument here/tal/path/to/epozdocument"
        tal:omit-tag="">
    <h2 tal:content="myepozdocument/title">
     The title of the EpozDocument
    </h2>
    <div tal:replace="structure myepozdocument/html">
     The HTML content of the EpozDocument
    </div>
    <div>
     This page was updated
     <span tal:replace="python: myepozdocument.lastEditDate.strftime('%Y/%m/%d')">
      2004/1/24
     </span>
    </div>
   </div>
   ...

Use with the External Editor

Just add this section to your client $HOME/.zope-external-edit file (Unix) or X:\Program Files\ZopeExternalEditor\ZopeEdit.ini (Windows) equivalent :

   [meta-type:EpozDocument]
   extension = .html

ZCatalog awareness

Your EpozDocument contents is automatically indexed:

Add a ZCatalog named Catalog
You may add the following indexes:
- id : FieldIndex as usual
- title : FieldIndex too
- lastEditDate : DateIndex
- path : PathIndex
- html : TextIndex or ZCTextIndex, the content of an EpozDocument
- SearchableText : TextIndex or ZCTextIndex, title + html of an EpozDocument
- PrincipiaSearchSource is an alias for SearchableText.
- any additional Property of your EpozDocument with appropriate index type.

If you want to add the content of string or text properties to SearchableText/PrincipiaSearchSource, just add a tokens property named SearchableTextAdd, and include the name of those properties you want to merge together with the title and html contents.

Warning: Changing/adding/deleting properties doesn't reindex the EpozDocument. You must edit the object again to have it reindexed. I didn't find an easy way to reindex the object when editing properties since Zope doesn't provide hooks to Products when properties are created/changed/deleted. If you got an idea to do this, feel free to contact me.

If the id Catalog doesn't suit your site (i.e. you need a specific ZCatalog for a subset of your site or whatever), you may change it through the ZCatalog ZMI tab (new in this release). Be warned that this standard Zope feature fails silently (and I can't help). This mean if there's no ZCatalog with the id you chose, or you chose the id of a non ZCatalog compatible object, no error message is issued.

In case you need something else than Catalog for your ZCatalog id, you should consider fixing this with a ZClass that subclasses EpozDocument (see later in this README). This can be done easily in your ZClass object constructor Python (script) like this... :

   ...
   obj = context.manage_addProduct['MyProduct'].MyZClass.createInObjectManager(yourId, context.REQUEST)
   obj.manage_editCataloger('MyZCatalogId')
   # Your own other inits ?
   ...

Edit with your site stylesheet

Add somewhere in the acquisition path of your EpozDocument objects (typically in the root folder of your site) an object called EpozDocumentCssUrl that provides... the URL to your favorite css file.

The easiest way to do this is a Python script like this one:

   ## Script (Python) "EpozDocumentCssUrl"
   ##bind container=container
   ##bind context=context
   ##bind namespace=
   ##bind script=script
   ##bind subpath=traverse_subpath
   ##parameters=
   ##title=CSS File for EpozDocument widget
   ##
   return container.my_favorite_stylesheet_css.absolute_url()

Warning: Test carefully your EpozDocumentCssUrl otherwise, you couldn't edit your EpozDocuments if this object:

raises an error
returns a nasty URL
or the URL provides a crappy CSS

Post processing an EpozDocument content

When clicking "Save Changes" in the EMI edit tab or saving from the External Editor, a Python (script) or External Method named EpozDocumentPostEditHook is searched in the acquisition path. If found, it is executed. This script is expected to have 2 arguments:

The EpozDocumentObject itself
Its html content

The value returned by this script replaces the HTML content of the EpozDocument.

Warnings:

Test carefully your own EpozDocumentPostEditHook in a sandbox before installing it in a production site. In no event the autor will have any responsability of content/data loss due to any use of EpozDocumentPostEditHook.
As mentioned in Epoz documentation:
(a) the EpozDocument content is transformed into XHTML by mxTidy (if installed) and...

(b) it will be processed by the EpozPostTidy script (if found at the Zope root) prior being processed by EpozDocumentPostEditHook.

This example shows how tho change automatically <HR> tags :

   ## Script (Python) "EpozDocumentPostEditHook"
   ##bind container=container
   ##bind context=context
   ##bind namespace=
   ##bind script=script
   ##bind subpath=traverse_subpath
   ##parameters=objekt, html
   ##title=Post (external) edit hook
   ##
   html = html.replace('<hr>', '<hr style="width: 50%">')
   return html.replace('<HR>', '<HR STYLE="width: 50%">')

Base for ZClass

If you want to add easily your methods and/or properties to specific EpozDocuments for your site, the easiest way to achieve this is to create an EpozDocument based ZClass.

This document won't learn you how to make a ZClass. If you dunno about ZClasses, read the dedicated chapter of the Zope Book.

When creating your ZClass, just select EpozDocument: EpozDocument as base class, then add your features (propertysheets, templates, scripts...).

Warning: The ZClass features have not been deeply tested, and - due to the nature of the ZClasses - cannot be tested in depth. Thus, I consider this feature as alpha despite I didn't find bug till now.

Security (specific permissions)

Adding an EpozDocument requires the Add Documents, Images and Files permission.
Changing an EpozDocument requires the Change Images and Files permission.

Bug reports

Before reporting bugs, please ensure first your browser enables cookies, and try to reproduce the bug with the latest versions of EpozDocument and Epoz.

Please provide a test case, the used browser/OS and the versions of EpozDocument, Epoz and Zope.

Please note that this version is not supposed to support Epoz 1.x (aka EpozNg), since I started EpozDocument before hearing of it. A future EpozDocument release will support Epoz 1.x when I'll get more time, and perhaps a little support :o)

Feedback

Gilles Lenfant < [email protected] >

Upgrades

Check periodically http://zope.org/Members/gillou/EpozDocument for upgrades.

License

This software is provided under terms of the ZPL . Means that you can do anything you want with it except changing the credits and terms of the license.

Credits

Many thanks to Maik Jablonski for Epoz