incubator-odf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From devin...@apache.org
Subject svn commit: r1170991 - /incubator/odf/site/trunk/content/odftoolkit/odfdom/Convenience Layer Design Ideas.mdtext
Date Thu, 15 Sep 2011 07:54:36 GMT
Author: devinhan
Date: Thu Sep 15 07:54:36 2011
New Revision: 1170991

URL: http://svn.apache.org/viewvc?rev=1170991&view=rev
Log:
create page: Some Design Thoughts on ODFDOM Convenience Layer

Added:
    incubator/odf/site/trunk/content/odftoolkit/odfdom/Convenience Layer Design Ideas.mdtext

Added: incubator/odf/site/trunk/content/odftoolkit/odfdom/Convenience Layer Design Ideas.mdtext
URL: http://svn.apache.org/viewvc/incubator/odf/site/trunk/content/odftoolkit/odfdom/Convenience%20Layer%20Design%20Ideas.mdtext?rev=1170991&view=auto
==============================================================================
--- incubator/odf/site/trunk/content/odftoolkit/odfdom/Convenience Layer Design Ideas.mdtext
(added)
+++ incubator/odf/site/trunk/content/odftoolkit/odfdom/Convenience Layer Design Ideas.mdtext
Thu Sep 15 07:54:36 2011
@@ -0,0 +1,83 @@
+= 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:
+
+# Consider the tasks that the user will perform
+# Identify which tasks are repeated most frequently and thus should be very easy to do
+# Identify those tasks which are more advanced and might require more steps
+# 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?
+
+# 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.
+# Combine two documents into one document.
+# Print out the metadata fields for a document.
+# Replace one image with another image in a file
+# Reorder slides in a presentation
+# Take 5 slides from 5 different presentations and combine them into one new presentation
+# Find all text with the style "private" and replace that text with "XXXXXXXX"
+# Add a logo image in the document header
+# Given a 2 dimensional data array or a cell range address, create a bar chart in a spreadsheet
+# Highlight all the occurrences of a given text with blue bold properties
+# Create a 5rows X 2columns table in a text document, the first row is head row.
+# Create a presentation document from a given template document
+# Insert a rectangle shape with the shape text ¡°hello world¡±
+# Create TOC at the beginning of the text document
+# Create a new sheet in a spreadsheet, insert a text at the given cell address, format the
text as bold/italic
+# Create a data pilot given row/column/data fields in the sheet in a spreadsheet
+# Insert a formula at the given cell address in a spreadsheet
+# Define simple page setup for a text document, orientation is portrait, left/right margin
is 2cm, top/bottom is 2.5cm
+# Insert page number in the footer
+# Set row height and column width for a sheet in a spreadsheet
+# Set bullet number for a text list
+# Create a customized paragraph style, apply this style to all paragraphs in a text document
+# Select a custom shape, create a style from the custom shape properties, apply this style
to another custom shape.
+# Create a custom shape in presentation slide, set animation effect ¡°entrance->fly
in¡± to the custom shape.
+# 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:
+
+# Given an ODF document instance, navigate to a point in the document
+# At that point insert content
+# Save the document
+
+Another is:
+
+# Given an ODF document instance, define a selection (by start and end point, by start point
and "distance", by similarity, etc.)
+# Modify the selection, e.g., replace the content, modify the the style, delete the selection,
etc.
+# Save the document
+
+And another is:
+
+# Given an ODF document instance, iterate over content of a given type, e..g, all footnotes,
all images, all paragraphs of a given style
+# 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:
+
+# Spend a few days completing the list of user tasks that we agree should be easy to do with
the ODFDOM convenience layer API.
+# Then review that list and identify common patterns of use, those recurring interactions
that should be coded once and reused.
+# 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.
+# Then we implement the API's, write unit tests, etc.
+



Mime
View raw message