
**************************************************************************
itools 0.15.0
**************************************************************************

1. itools.catalog
=================

The search interface has changed to include new features and to be more
performant.

Before:

    >>> documents = catalog.search(query)
    >>> n_documents = catalog.how_many(query)

Now: 

    >>> results = catalog.search(query)
    >>> documents = results.get_documents()
    >>> n_documents = results.get_n_documents()


2. itools.xml
=============

The XML parser has been rewritten in C, as a side effect the programming
interface has some small changes:

  - Now we import the type "Parser" instead of the function "parse":

  - We have the new events XML_DECL, PI and CDATA

  - The event NAMESPACE has been removed, to replace it the event
    START_ELEMENT returns the namespace declarations.

To illustrate these changes see the example below.

Before:

    from itools.xml.parser import parse
    from itools.xml.parser import START_ELEMENT, NAMESPACE
    ...
    for event, value, line_number in parse(data):
        if event == START_ELEMENT:
            namespace_uri, local_name, attributes = value
            ...
        elif event == NAMESPACE:
            ...

Now:

    from itools.xml.parser import Parser
    from itools.xml.parser import START_ELEMENT, XML_DECL
    ...
    for event, value, line_number in Parser(data):
        if event == XML_DECL:
            ...
        elif event == START_ELEMENT:
            namespace_uri, local_name, attributes, ns_decls = value
            ...


3. itools.stl
=============

3.1 Variable substitution
·························

A new syntax has been implemented for variable substitution, it replaces the
attributes "stl:content" and "stl:attributes".

Before:

  <a stl:attributes="href object_uri" stl:content="object_title" />

Now:

   <a href="${object_uri}">${object_title}</a>


3.2 Expressions
···············

Now STL expressions do not accept parameters anymore. This feature was
not documented, and experience has shown it useless.


4. itools.cms
=============

4.1 The config file
···················

The format of the configuration file has changed from INI [1] to a more
simple and UNIX-like format. The file is renamed from "config.ini" to
"config.conf".

The configuration file will be automatically changed with the "icms-update"
script.


4.2 Users
·········

Now users are internally identified with a number, the only visible change
in the user interface is that numbers will appear in the path instead of
the user's login.

The register and login screens have been updated so the user's email will
be used to identify the him/her (instead of a username). The registration
interface requires confirmation by email to validate the registration
proces, this way we are sure the email address is good.

The upgrade code is made so for the existing users we will still use the
username, so they won't be disturbed.


4.3 Roles
·········

Roles are now stored in the metadata file. This allows files to have roles
associated to them, not just folders.

The programming interface has changed too.

Before:

    >>> handler.is_in_role(rolename, username)
    >>> handler.del_roles(username)
    >>> handler.set_role(rolename, username)

Now:

    >>> handler.has_user_role(username, rolename)
    >>> handler.set_user_role(username, None)
    >>> handler.set_user_role(username, rolename)

In the method "has_user_role" more than one rolename may be given. In the
method "set_user_role" the parameter "username" may be a list of usernames.

The methods "has_role", "get_role" and "get_roles" have been removed.


4.4 Widgets and the "browse list" view
······································ 

The widget "Table" has been removed. To see how to do the same thing now
check the method "Folder.browse_list".


4.5 Rewrite URLs (was "set_template_prefix")
············································ 

The way to rewrite the URLs has changed. Now we do it in one step, instead
of two, so it is faster. The template language STL provides the feature now.

Before:

    handler = self.get_handler('.../template.xhtml')
    # Rewrite the URLs
    here = uri.Path(here.get_abspath())
    there = uri.Path(handler.get_abspath())
    handler = XHTML.set_template_prefix(handler, here.get_pathto(there))
    # STL
    body = stl(handler, namespace)

Now:

    handler = self.get_handler('.../template.xhtml')
    # STL and rewrite the URLs
    prefix = uri.Path(handler.get_abspath())
    body = stl(handler, namespace, prefix=prefix)


5. Packaging
============

5.1 Dependencies
················

Now we use the library tidy (through "utidylib") instead of the calling
the command line programm "tidy". Download "utidylib" from:

  http://utidylib.berlios.de/

5.1 Imports
···········

Very few imports have changed in this release:

Before:

  from itools.csv.itools_csv import CSV
  from itools.cms.csv_ import CSV

Now:

  from itools.csv.csv import CSV
  from itools.cms.csv import CSV

