python-zope.html 2.2.0-0ubuntu8 / usr / share / pyshared / zope / html / docinfo.txt

======================================
Management of supplemental information
======================================

The `zope.html` package provides additional views on files containing
HTML and XHTML data that allow editing the files over the web.  The
files may contain either complete documents or fragments that may be
composed into larger documents.  Preview views are also provided.

The editing and preview views rely on getting supplemental information
about the file being edited using the `IEditableHtmlInformation`
adapter for the file.  That adapter uses annotations on the content
object to store information that needs to be persisted.

The `IEditableHtmlInformation` interface is very simple; there's only
one field defined, and it's a simple boolean value: whether the file
should be treated as a fragment or not.  Let's create a simple content
object that we can use for testing::

  >>> import zope.file.file
  >>> import zope.interface
  >>> import zope.annotation

  >>> class File(zope.file.file.File):
  ...     zope.interface.implements(
  ...         zope.annotation.IAttributeAnnotatable)
  ...
  ...     def __init__(self, text=None):
  ...         super(File, self).__init__("text/html", {"charset": "utf-8"})
  ...         f = self.open("w")
  ...         f.write(text)
  ...         f.close()

Let's create a file and the corresponding `IEditableHtmlInformation`
object::

  >>> import zope.html.docinfo

  >>> file = File("This is a <em>fragment</em>.")
  >>> info = zope.html.docinfo.EditableHtmlInformation(file)

We can now check that the initial value of the `isFragment` attribute
is computed reasonably::

  >>> info.isFragment
  True

The user can cause the `isFragment` flag to be toggled from the UI, so
it should remember the current state of the flag::

  >>> info.isFragment = False
  >>> info.isFragment
  False

A new instance of the `IEditableHtmlInformation` instance should also remember the last value of the setting::

  >>> zope.html.docinfo.EditableHtmlInformation(file).isFragment
  False