At the time of writing, the latest version of eZ Publish is 4.0.2, with the eZODF extension version 2.0. Note that the concepts and procedures described in this article might vary somewhat for older or newer versions.
To get the most out of this article, the reader should be familiar with the eZ Publish content model. Also, note that this article is not intended to be a comprehensive guide to the eZODF extension. Please consult the documentation for more information.
ODF definitions
To those who are unfamiliar with the OpenDocument Format, it is similar in function to the formats that are natively used in Microsoft Office and other desktop office applications. However, it is an Open Source standard. The Wikipedia definition of ODF is as follows:
The OpenDocument format (ODF) is a file format for electronic office documents such as spreadsheets, charts, presentations and word processing documents. The specifications were originally developed by Sun.
Published ODF standards meet the common definitions of an open standard, meaning they are freely available and implementable.
Many governments (as well as many other organizations) are realizing the power and benefits of open standards and also ODF. Some governments have introduced policies mandating or encouraging the use of such open standards. By supporting and using open standards, such as by the availability of the eZODF extension, eZ Publish is a very valuable Enterprise Content Management System for such markets.
The OpenOffice.org suite used in this article, which is fully compatible with the eZODF extension, can handle all of your office tasks such as:
- word processing
- spreadsheets
- presentations
- graphics
- databases and more...
Word processor documents in OpenDocument format are most often saved in OpenDocument Text files, with the file extension ".odt".
OpenOffice.org can open and edit not only ODF documents, but also Microsoft Office documents. It is freely available, easy to use, and available in many languages. It can be installed on Windows, Mac, and Linux operating systems.
The screenshots below shows the similarity in user interfaces between OpenOffice.org Writer and Microsoft Word.
MS Office Word 2003
OpenOffice.org Writer 3.0
The eZODF extension
The importing and exporting of content to eZ Publish is accomplished through the eZ Open Document Format (ODF) extension. This extension has been included with eZ Publish by default since eZ Publish 3.8.
The eZODF extension's requirements include eZ Publish 3.8 or later and the zlib PHP extension. By default, the eZODF extension can import and export ODF documents; if OpenOffice.org is installed on the web server, the extension also supports the importing and exporting of Microsoft Word documents. The eZODF extension can preserve many formatting elements, such as tables, lists, images and images captions, headers, and more.
To understand how the eZODF extension integrates into the eZ Publish publishing process, first consider how content objects are stored in eZ Publish. Content objects consist of attributes, the contents of which are displayed and formatted most commonly in XHTML through eZ Publish templates. Due to this separation of content and design, eZ Publish is capable of exporting content to other formats (such as ODF), and of importing external content that has been processed by an extension to be compatible with eZ Publish's storage format.
Before we explore the basic how-to steps, let's explore the reasons why the extension might be useful for you. The benefits of the eZODF extension are many; most of the common benefits listed below:
- You do not have to be connected to the Internet to create and/or edit your content. You can work on your content "offline", then import it to the website yourself at a later time or deliver the content to a site administrator who would import it.
- It provides those who might not have or need an account on a website – such as external or temporary writers, publishers, and translators – the possibility of contributing content.
- Writers do not have to learn a new user interface, as they can work in their preferred word processor. This frees them to focus solely on producing the best content.
- It can facilitate the re-production and re-distribution of content to other channels. For example, you could more quickly create brochures or flyers from site content.
- It helps to maintain visual consistency if you use styling in export templates, and data structure consistency by using predefined layouts for the imported documents.
- The feature is especially beneficial in environments such as magazines and newspapers where there are both print and online channels. Articles can be published either directly on the website or directly in a word processor, and then converted between formats.
Here, we will demonstrate the basics on how to import and export content between eZ Publish and ODF documents. However, there are other features available, such as importing and exporting to PDF and Microsoft Word, as well as the use of custom export templates. Be sure to consult the documentation for the more advanced uses.
The procedures listed below use eZ Publish 4.0.1, the Website Interface extension, and OpenOffice.org 3.0.0.
Importing
OpenOffice.org sections
The eZODF extension uses sections defined in OpenOffice.org Writer documents to map word processor blocks to content attributes in eZ Publish.
Below is a screenshot of the Class edit interface in eZ Publish, showing information about a sample attribute. Note the identifier field, which will be used in the eZODF extension-specific odf.ini configuration file shortly.
Class edit interface: attributes and identifiers
When preparing an OpenOffice.org Writer document to be imported to eZ Publish, you need to create a section corresponding to each content attribute. This is achieved with the following steps in OpenOffice.org Writer:
- Place your cursor in the location of the document where you want the section to begin.
- From the main menu, choose Insert > Section, which will bring up the relevant modal dialog.
- Specify the name of the new section, then click the OK button. It is easiest to use section names that are the same as their corresponding attribute identifier names.
OpenOffice.org Writer: insert section
Repeat the steps above for each section. Note that depending on the section in which your cursor is in, you will then see the name of the section in the status bar at the bottom of the window. Within each section, you can write some explanatory text to detail what the section is to be used for. Once you are done setting up the sections, you can save this document and share it as a template for anybody who will be producing content for your site.
The actual mapping of OpenOffice.org sections to content attributes is done in the eZODF configuration file, odf.ini. There is a configuration block in the configuration file for each content class to which you want to import. In short, each block instructs eZ Publish to create the appropriate new object or version based on the structure of the imported file. Below is an example of a configuration for a default Article class. Note the names of the attributes on the left of each entry in square brackets, and the name of the OpenOffice.org section on the right of each entry.
[article]
Attribute[title]=title
Attribute[intro]=intro
Attribute[body]=body
Attribute[image]=image
For full details, be sure to consult the documentation.
Writing and importing
With OpenOffice.org sections configured, you can start writing content to import. At this point, it is important for writers and publishers to know what types of formatting and datatypes can be imported by the eZODF extension.
Supported datatypes:
- text line
- date
- text block
- date and time
- XML block
- matrix
- image
Supported formatting:
- normal text
- numbered and bulleted lists
- bold and italic
- headers
- text links
- tables
- custom tags
- embedded images
There are three ways to import content using the eZODF extension:
- Directly specify the URLs (in either the front-end of the site and the Administration Interface) for the Import interface of the extension
- If the Website Interface or Website Toolbar is installed, log in to the front-end of the site and browse to the desired location. Then, click the Import or Replace button on the Website Toolbar.
- Log in to the Administration Interface and select the appropriate option from the context-sensitive pop-up menu.
The first method is done by appending "/ezodf/import" to the root of either the front-end or Administration Interface URLs. The default corresponding URLs are thus "http://www.example.com/ezodf/import" or "http://www.example.com/ezwebin_site_admin/ezodf/import". This will load the eZODF Import interface where you can select the file to upload.
Front-end import page
Administration Interface import page
Then, use the eZ Publish Browse interface to find the location under which you wish to import the content.
Select location for imported content
The imported content will then be shown in the same way as if you had entered the content via one of the browser-based interfaces.
Alternatively, you can log in to the front-end of your site (with the Website Interface or Website Toolbar installed) and browse to the node under which you wish to import content. On the Website Toolbar, you will see three buttons on the right, corresponding to the "import", "export", and "replace" operations of the eZODF extension.
eZODF extension: Website Toolbar
Note that the "replace" operation is similar to the "import" operation. However, instead of creating a new object and node beneath the specified location (as with the "import" operation), the "replace" operation will create a new version of the current object. Clicking either the Import or Replace button will bring up a similar Import interface to what is shown above. The difference is that you do not have to use the eZ Publish Browse interface after uploading the file, since you have already selected the location for the imported content.
The third and last method is to log in to the Administration Interface and use the context-sensitive pop-up menu for the desired node from either the left menu or the Sub items menu. Under the "OpenOffice.org" sub-menu, choose either "Import OpenOffice" or "Replace OpenOffice". The subsequent steps are as previously described.
eZODF extension: context-sensitive pop-up menu
Export
To export eZ Publish content as ODF documents, the available methods are similar to how you import content.
The first method is done by appending "/ezodf/export" to the root of either the front-end or Administration Interface URLs. The default corresponding URLs are thus "http://www.example.com/ezodf/export" or "http://www.example.com/ezwebin_site_admin/ezodf/export". This will load the eZODF Export interface where you can select the object to export.
Front-end export page
You will then be prompted to download the exported content as an ODF document.
Alternatively, you can log in to the front-end of your site (with the Website Interface or Website Toolbar installed) and browse to the node that you want to export. On the right side of the Website Toolbar, click the Export button.
eZODF extension: Export button is the second button
The third and last method is to log in to the Administration Interface and use the context-sensitive pop-up menu for the desired node from either the left menu or the Sub items menu. Under the "OpenOffice.org" sub-menu, choose "Export OpenOffice".
Administration Interface, OpenOffice.org export
The export process preserves the same formatting and sections as specified earlier for the import process. Those preserved sections make it possible to re-import the content after editing and saving it in OpenOffice.org Writer.
The styling of the exported document is determined by an ODF template specified in the odf.ini configuration file. This template can be tweaked to add custom styling, headers, footers, and more.