Some Design Thoughts on ODFDOM Convenience Layer

The API is our User Interface

Since the users of ODFDOM are programmers who use our library, this means that our API is our "User Interface". Although it is not a GUI, it is a UI, and we should design it like a UI, meaning we:

  1. Consider the tasks that the user will perform
  2. Identify which tasks are repeated most frequently and thus should be very easy to do
  3. Identify those tasks which are more advanced and might require more steps
  4. Design an interface that makes the most-common tasks very easy, while still being powerful enough for more advanced uses.

Some Typical User Tasks

Operations such as these should be possible to do with only 10 lines code, and with no knowledge of XML or XPath or ODF. We should add to this list and discuss

Do we agree that these are all common tasks that should be simple to program with ODFDOM?

  1. Open an ODF document, search for a text string "foo" and replace it with "bar" every where it occurs in the user text of the document.
  2. Combine two documents into one document.
  3. Print out the metadata fields for a document.
  4. Replace one image with another image in a file
  5. Reorder slides in a presentation
  6. Take 5 slides from 5 different presentations and combine them into one new presentation
  7. Find all text with the style "private" and replace that text with "XXXXXXXX"
  8. Add a logo image in the document header
  9. Given a 2 dimensional data array or a cell range address, create a bar chart in a spreadsheet
  10. Highlight all the occurrences of a given text with blue bold properties
  11. Create a 5rows X 2columns table in a text document, the first row is head row.
  12. Create a presentation document from a given template document
  13. Insert a rectangle shape with the shape text “hello world"
  14. Create TOC at the beginning of the text document
  15. Create a new sheet in a spreadsheet, insert a text at the given cell address, format the text as bold/italic
  16. Create a data pilot given row/column/data fields in the sheet in a spreadsheet
  17. Insert a formula at the given cell address in a spreadsheet
  18. Define simple page setup for a text document, orientation is portrait, left/right margin is 2cm, top/bottom is 2.5cm
  19. Insert page number in the footer
  20. Set row height and column width for a sheet in a spreadsheet
  21. Set bullet number for a text list
  22. Create a customized paragraph style, apply this style to all paragraphs in a text document
  23. Select a custom shape, create a style from the custom shape properties, apply this style to another custom shape.
  24. Create a custom shape in presentation slide, set animation effect “entrance->fly in“ to the custom shape.
  25. Split a large document to many small documents, each chapter beginning with “heading 1“ style will be saved as a small document.

Programming = Data structures + Algorithms

We probably all saw a statement like that in our first Computer Science class. These are both essential parts of programming. But many libraries have the fault that they only have strength in the data modeling. They often have very little support for common algorithms. For example, what did the C Programming Language give us? Aside from qsort() and bsearch(), there was very little. C++ on the other hand, contained the powerful Standard Template Library (STL).

ODFDOM 0.7 is mainly convenience wrappers of ODF markup, raising the level of abstraction of this data. But we should also consider supporting algorithms, along the STL model. This would be quite powerful and is necessary to make the above task examples very simple for our users.

For example, a typical pattern of use is:

  1. Given an ODF document instance, navigate to a point in the document
  2. At that point insert content
  3. Save the document

Another is:

  1. Given an ODF document instance, define a selection (by start and end point, by start point and "distance", by similarity, etc.)
  2. Modify the selection, e.g., replace the content, modify the the style, delete the selection, etc.
  3. Save the document

And another is:

  1. Given an ODF document instance, iterate over content of a given type, e..g, all footnotes, all images, all paragraphs of a given style
  2. As you iterate over the content, treat each returned fragment as a selection that can be operated on.

As we think of this more, we see some commonality, including the need to define:

A Possible Direction Forward

I'd like us to consider doing the following:

  1. Spend a few days completing the list of user tasks that we agree should be easy to do with the ODFDOM convenience layer API.
  2. Then review that list and identify common patterns of use, those recurring interactions that should be coded once and reused.
  3. Then, before writing any real code, let's write pseudo code for some (or even all) of our original tasks. Let's validate the API design at a high level by confirming that this API radically simplifies the coding required for the most common use cases.
  4. Then we implement the API's, write unit tests, etc.

Powered by the Apache CMS.

Apache "ODF Toolkit" is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

Copyright © 2011 The Apache Software Foundation Licensed under the Apache License, Version 2.0. Contact Us
Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
Other names appearing on the site may be trademarks of their respective owners.