content/odftoolkit/odfdom/ConvenienceLayerDesignIdeas.mdtext - incubator-odftoolkit-site - Git at Google

 Title: 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
  1. Identify which tasks are repeated most frequently and thus should be very easy to do
  1. Identify those tasks which are more advanced and might require more steps
  1. 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.
   1. Combine two documents into one document.
   1. Print out the metadata fields for a document.
   1. Replace one image with another image in a file
   1. Reorder slides in a presentation
   1. Take 5 slides from 5 different presentations and combine them into one new presentation
   1. Find all text with the style "private" and replace that text with "XXXXXXXX"
   1. Add a logo image in the document header
   1. Given a 2 dimensional data array or a cell range address, create a bar chart in a spreadsheet
   1. Highlight all the occurrences of a given text with blue bold properties
   1. Create a 5rows X 2columns table in a text document, the first row is head row.
   1. Create a presentation document from a given template document
   1. Insert a rectangle shape with the shape text “hello world"
   1. Create TOC at the beginning of the text document
   1. Create a new sheet in a spreadsheet, insert a text at the given cell address, format the text as bold/italic
   1. Create a data pilot given row/column/data fields in the sheet in a spreadsheet
   1. Insert a formula at the given cell address in a spreadsheet
   1. Define simple page setup for a text document, orientation is portrait, left/right margin is 2cm, top/bottom is 2.5cm
   1. Insert page number in the footer
   1. Set row height and column width for a sheet in a spreadsheet
   1. Set bullet number for a text list
   1. Create a customized paragraph style, apply this style to all paragraphs in a text document
   1. Select a custom shape, create a style from the custom shape properties, apply this style to another custom shape.
   1. Create a custom shape in presentation slide, set animation effect “entrance->fly in“ to the custom shape.
   1. 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
  1. At that point insert content
  1. 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.)
  1. Modify the selection, e.g., replace the content, modify the the style, delete the selection, etc.
  1. 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
  1. 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 parametrized selection mechanism that has some predefined predicates, like for all content, all content of a given style, etc., but also allow user-defined predicates
  - Mutable and immutable iterators
  - Copy semantics on content, so it can be moved from document to document and preserve styles (if desired) including possibly merging styles where they are identical
  - And of course, all the wrappers to read/write ODF content once we have the fragment that the user wants.
  - And I'm sure there are several other items to consider

 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.
  1. Then review that list and identify common patterns of use, those recurring interactions that should be coded once and reused.
  1. 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.
  1. Then we implement the API's, write unit tests, etc.
	Title: 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
	1. Identify which tasks are repeated most frequently and thus should be very easy to do
	1. Identify those tasks which are more advanced and might require more steps
	1. 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.
	1. Combine two documents into one document.
	1. Print out the metadata fields for a document.
	1. Replace one image with another image in a file
	1. Reorder slides in a presentation
	1. Take 5 slides from 5 different presentations and combine them into one new presentation
	1. Find all text with the style "private" and replace that text with "XXXXXXXX"
	1. Add a logo image in the document header
	1. Given a 2 dimensional data array or a cell range address, create a bar chart in a spreadsheet
	1. Highlight all the occurrences of a given text with blue bold properties
	1. Create a 5rows X 2columns table in a text document, the first row is head row.
	1. Create a presentation document from a given template document
	1. Insert a rectangle shape with the shape text “hello world"
	1. Create TOC at the beginning of the text document
	1. Create a new sheet in a spreadsheet, insert a text at the given cell address, format the text as bold/italic
	1. Create a data pilot given row/column/data fields in the sheet in a spreadsheet
	1. Insert a formula at the given cell address in a spreadsheet
	1. Define simple page setup for a text document, orientation is portrait, left/right margin is 2cm, top/bottom is 2.5cm
	1. Insert page number in the footer
	1. Set row height and column width for a sheet in a spreadsheet
	1. Set bullet number for a text list
	1. Create a customized paragraph style, apply this style to all paragraphs in a text document
	1. Select a custom shape, create a style from the custom shape properties, apply this style to another custom shape.
	1. Create a custom shape in presentation slide, set animation effect “entrance->fly in“ to the custom shape.
	1. 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
	1. At that point insert content
	1. 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.)
	1. Modify the selection, e.g., replace the content, modify the the style, delete the selection, etc.
	1. 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
	1. 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 parametrized selection mechanism that has some predefined predicates, like for all content, all content of a given style, etc., but also allow user-defined predicates
	- Mutable and immutable iterators
	- Copy semantics on content, so it can be moved from document to document and preserve styles (if desired) including possibly merging styles where they are identical
	- And of course, all the wrappers to read/write ODF content once we have the fragment that the user wants.
	- And I'm sure there are several other items to consider

	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.
	1. Then review that list and identify common patterns of use, those recurring interactions that should be coded once and reused.
	1. 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.
	1. Then we implement the API's, write unit tests, etc.