OpenOffice::OODoc::Styles 2.026 review

OpenOffice::OODoc::Styles is a Perl module for document styles and layout processing. This class is designed to handle styles, whe

License: Perl Artistic License File size: 209K Developer: Genicorp, S.A.

0

OpenOffice::OODoc::Styles is a Perl module for document styles and layout processing.

This class is designed to handle styles, whether automatic or named, contained in styles.xml or content.xml. It inherits from the common OpenOffice::OODoc::XPath class and brings style-focused features.

This class should not be explicitly used in an ordinary application, because all its features are available in the OpenOffice::OODoc::Document class, in combination with other features. Practically, the present manual is provided to describe the style processing features of OpenOffice::OODoc::Document (knowing that these features are technically supported by the OpenOffice::OODoc::Styles component of the API).

Remember that named styles are those that the end user can see and edit using the Stylist tool in OpenOffice.org. Such styles usually have meaningful names and are stored in the styles.xml member. But an OpenDocument-compliant style may own two names, so-called 'name' and 'display-name'. The 'display-name' is the name as it's displayed by the office software, while the 'name' is the main identifier. Both are displayable character strings, but they often differ. For a given 'display-name', the application software is allowed to set any arbitrary 'name'. For example, with OpenOffice.org 2, the well-known pre-defined style whose display name is "Text body" is named "Text_20_body" (the space character is replaced by its hexadecimal value between two "_" characters). In the other hand, the 'name' and the 'display-name' generally don't differ when they contain letters and/or digits only. Remember that the 'name' (and not the 'display-name') is the main identifier of a style element. So, such a method as getStyleElement("style name") uses the 'name' attribute to retrieve a style descriptor (unless you change this behaviour through the 'retrieve_by' document property).

Care should be taken particularly with predefined base styles in OpenOffice.org. These styles are described in styles.xml just like named styles, but they appear to the end user with localised names (in their local language), so the really displayed style name is neither the 'name' nor the 'display-name' stored attributes. For example, in the French distribution of OpenOffice.org, the "Text body" style appears as "Corps de texte", while its "display-name" is "Text body" and its "name" is "Text_20_body". However, this is not a problem for user-defined styles as the stored display-name is exactly the same as the effective display name.

There are also numerous "automatic" styles in a document which are created implicitly by the office application each time a particular set of presentation attributes is given to an element, but where no named style is referenced. Automatic styles which apply to the document body are stored in content.xml (but in an XML element isolated from the content). An automatic style's name can change randomly each time the document is edited or saved in OpenOffice.org.

Applications which access automatic styles will not want to indicate them using "hard-coded" names. The best way is to retrieve each automatic style via an object that is known to use it. Using a "hard-coded" name is all right for styles created by a program (the createStyle() method requires it), but such a name should only be considered to be stable for the duration of the session. If you want a program-created style name to be then respected by OpenOffice.org, you must create it as a named style.

This is no more complicated, but it is better to avoid making hundreds of styles visible to the user that they do not need to see.
There are some structural differences between the old OpenOffice.org 1.0 format and the new OASIS Open Document (ODF) one. A few of these differences aren't made fully transparent by OpenOffice::OODoc. So, in some cases, a program including style definitions or updates doesn't produce exactly the same results with both OOo 1 and OOo 2 documents.

Some styles are more complex than others as they describe the page layout. These styles can themselves contain text and images. A page style, or a "master page", can actually define a header, a footer, margins, and a background. Headers and footers can contain text and images which can otherwise be handled by OODoc::Text and OODoc::Image. A background contains a colour and can also include a background image (several methods are possible).
Presentation of these objects is itself controlled by styles.

All of this leads to the conclusion that it is not enough just to associate each content element with a style. In reality, document styles form a rather complex network of interdependencies.
As for page styles, the OpenOffice.org format contains a concept which must be understood in order to use some of the following methods. By virtue of the principle of separation of content and presentation, the definition of a page style is based on two distinct objects: "master page" and "page layout". A "master page" object encompasses any page style content (i.e. the content of headers and footers) and links to a "page layout" object which describes page presentation characteristics (with large numbers of parameters from page dimensions to background colour to footnote separator size, etc.). Names which appear in the list of page styles in OpenOffice.org are actually names of "master pages". However, to work with physical aspects of the presentation, you have to access the associated "page layout".

To complicate matters, there are also header and footer styles. Each object contained in a header or footer (e.g. paragraph or image) has a style. The number and range of styles are much larger that you would imagine just looking at the Stylist tool in OpenOffice.org. Up to a point, OODoc::Styles methods make life easier for you by masking some of this complexity.
In OODoc::Styles methods, styles are normally indicated by their logical names (which must be unique), but, except where otherwise stated, they can also be indicated by their style element reference. Moreover, when a method is expecting a page layout as an argument but the programmer passes it a master page instead (whether by design or by mistake), it "knows" in most cases how to automatically select the associated page layout.

Defining a style requires a great many attributes. Some appear in code examples in this manual, but for a full list of possible attributes for each style, you must refer to the OpenOffice.org specification or publications derived from it.

OODoc::Styles module is designed to allow applications to manipulate any style and even create new ones. It is not recommended, however, to use it to create a presentation entirely from code. Here again, it is better to start from document templates which already contain at least a blank of each required style.

Requirements:
Perl