incubator-odf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From devin...@apache.org
Subject svn commit: r1166074 - /incubator/odf/site/trunk/content/odftoolkit/odfdom/Layers.mdtext
Date Wed, 07 Sep 2011 09:12:29 GMT
Author: devinhan
Date: Wed Sep  7 09:12:29 2011
New Revision: 1166074

URL: http://svn.apache.org/viewvc?rev=1166074&view=rev
Log:
CMS commit to odftoolkit by devinhan

Modified:
    incubator/odf/site/trunk/content/odftoolkit/odfdom/Layers.mdtext

Modified: incubator/odf/site/trunk/content/odftoolkit/odfdom/Layers.mdtext
URL: http://svn.apache.org/viewvc/incubator/odf/site/trunk/content/odftoolkit/odfdom/Layers.mdtext?rev=1166074&r1=1166073&r2=1166074&view=diff
==============================================================================
--- incubator/odf/site/trunk/content/odftoolkit/odfdom/Layers.mdtext (original)
+++ incubator/odf/site/trunk/content/odftoolkit/odfdom/Layers.mdtext Wed Sep  7 09:12:29 2011
@@ -1,128 +1,126 @@
-__TOC__
-
-=The ODFDOM Layers=
+The ODFDOM Layers
+-----------------
 
 The ODFDOM project's objective is to provide an easy API for reading, writing and manipulating
documents of the OpenDocument format (ODF). 
 To archive this, the ODFDOM API follows a layered approach to access documents, as layered
design is the robust foundation for a well-designed modular structure.
 
-<center> [[image: ODFDOM-New-Layered-Model.png]]</center>
+<center>![alt text][1]</center>
 
-==The ODF Package Layer==
-The ODF Package Layer provides access to all resources stored within the ODF package, such
as XML streams, images or embedded objects. 
-===The ODF Package API===
-The ODF Package API covers all features from the [http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part3.html
third part of the ODF 1.2 specification] defining the ODF Package features. The ODF 1.2 package
features are build on top technologies as [http://www.pkware.com/documents/APPNOTE/APPNOTE_6.2.0.txt
ZIP package handling], [http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/ W3C encryption],
[http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/ W3C signature] and [http://www.w3.org/TR/2004/REC-rdf-concepts-20040210/
W3C metadata].
+The ODF Package Layer
+---------------------
+The ODF Package Layer provides access to all resources stored within the ODF package, such
as XML streams, images or embedded objects.   
+ 
+**The ODF Package API**  
+The ODF Package API covers all features from [the third part of the ODF 1.2 specification][2]
defining the ODF Package features. The ODF 1.2 package features are build on top technologies
as [ZIP package handling][3], [W3C encryption][4], [W3C signature][5] and [W3C metadata][6].
 
 At this layer a document is in general represented by a bundle of named resources zipped
to a package.
 For instance, an ODF text document like 'myVacation.odt' might contain the following files:
 
-[[image: ODF_Package.jpg]]
+![alt text][7]
+
+***Note:*** All file streams aside of the '/Pictures' directory and its content are specified
by the ODF standard. 
+Furthermore, the file streams are similar for all types of ODF documents.  
 
-'''Note:''' 
-All file streams aside of the '/Pictures' directory and its content are specified by the
ODF standard. 
-Furthermore, the file streams are similar for all types of ODF documents.
-
-The main requirements for this layer in regard of ZIP are: 
-* Zip/unzip the file streams of the package
-* Enlist all file streams in the /META-INF/manifest.xml (similar to an inventory)
-* Begin the package with an unzipped 'mimetype' file stream (allowing others to easily identify
the package)
+The main requirements for this layer in regard of ZIP are:   
+
+  - Zip/unzip the file streams of the package
+  - Enlist all file streams in the /META-INF/manifest.xml (similar to an
+    inventory)
+  - Begin the package with an unzipped 'mimetype' file stream (allowing
+    others to easily identify the package)
 
 All sources of the Package layer are organized in ODFDOM beyond <code>org.odftoolkit.odfdom.pkg.*</code>
 
 The following example illustrates how to add a graphic to the package level
 (although not shown by an ODF application (like OpenOffice.org), as not used by the shown
content):
 
-<pre>
-
-import org.odftoolkit.odfdom.pkg.OdfPackage;
-[...]
-
-// loads the ODF document package from the path
-OdfPackage pkg = OdfPackage.loadPackage("/home/myDocuments/myVacation.odt");
-
-// loads the image from the URL and inserts the image in the package, 
-// adapting the manifest
-pkg.insert(new URI("./myHoliday.png"), "Pictures/myHoliday.png", "image/png");
-pkg.save("/home/myDocuments/myVacation.odt");
- 
-</pre>
-
-<br/>
-
-==The ODF XML Layer==
-The ODF XML Layer provides all the features of an office format, such as tables, images,
numbering etc. All features are defined in [http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part1.html
the first part of the ODF 1.2 specification] describing the ODF XML schema. This layer consists
of two APIs representing two different views on the features.
-
-===The ODF DOM API===
-The ODF DOM API gives access to the XML, the elemental parts of the ODF schema features.
With this API it is easy to manipulate all specified XML nodes extending the platform and
language independent DOM API [http://www.w3.org/DOM/ DOM API standardized by the W3C] - best-known
by its implementation through the browsers. It extends the DOM API using a typed DOM. For
every ODF XML element and ODF XML attribute defined by the ODF grammar (the RelaxNG schema)
a unique class exists, providing methods for their allowed children. The purpose is to provide
the user a corset to easily write valid ODF without consulting the spec constantly. This API
is very consistent as instead of laboriously writing all these classes, the sources were generated
directly from the ODF schema. This generation guarantees complete coverage of the ODF specification
on one side and an easy and accurate upgrade to future ODF specifications on the other. 
+    import org.odftoolkit.odfdom.pkg.OdfPackage;
+    [...]
+    
+    // loads the ODF document package from the path
+    OdfPackage pkg = OdfPackage.loadPackage("/home/myDocuments/myVacation.odt");
+    
+    // loads the image from the URL and inserts the image in the package, 
+    // adapting the manifest
+    pkg.insert(new URI("./myHoliday.png"), "Pictures/myHoliday.png", "image/png");
+    pkg.save("/home/myDocuments/myVacation.odt");
+
+
+The ODF XML Layer
+-----------------
+
+The ODF XML Layer provides all the features of an office format, such as tables, images,
numbering etc. All features are defined in [the first part of the ODF 1.2 specification][8]
describing the ODF XML schema. This layer consists of two APIs representing two different
views on the features.   
+
+**The ODF DOM API**  
+   
+The ODF DOM API gives access to the XML, the elemental parts of the ODF schema features.
With this API it is easy to manipulate all specified XML nodes extending the platform and
language independent DOM API [DOM API standardized by the W3C][9] - best-known by its implementation
through the browsers. It extends the DOM API using a typed DOM. For every ODF XML element
and ODF XML attribute defined by the ODF grammar (the RelaxNG schema) a unique class exists,
providing methods for their allowed children. The purpose is to provide the user a corset
to easily write valid ODF without consulting the spec constantly. This API is very consistent
as instead of laboriously writing all these classes, the sources were generated directly from
the ODF schema. This generation guarantees complete coverage of the ODF specification on one
side and an easy and accurate upgrade to future ODF specifications on the other. 
 
-At this level, all XML file streams of the document are accessible via the [http://www.w3.org/DOM/
W3C DOM API], but only the ODF standardized XML file streams of the document (e.g. content.xml,
meta.xml) have their own classes representing their ODF XML elements. Foreign XML within a
specified ODF XML file will remain in the document model in general and won't be neglected
unless desired ( which still might be a future option).
+At this level, all XML file streams of the document are accessible via the [W3C DOM API][10],
but only the ODF standardized XML file streams of the document (e.g. content.xml, meta.xml)
have their own classes representing their ODF XML elements. Foreign XML within a specified
ODF XML file will remain in the document model in general and won't be neglected unless desired
( which still might be a future option).
 
 Example of the ODF XML representing a table in ODF:
 
-[[image: FruitTable_code.jpg]]
+![alt text][11]
 
-'''Note:''' In the OpenDocument standard the ODF elements are reused among all document types.
The above XML of a table is for instance equally usable in Text and Spreadsheet documents.
+***Note:*** In the OpenDocument standard the ODF elements are reused among all document types.
The above XML of a table is for instance equally usable in Text and Spreadsheet documents.
 
 
 This XML would be mapped to a W3C derived ODF DOM class structure:
 
-[[image: Table_fruits_diagramm.jpg | 670x346px]]
+![alt text][12]
 
 All sources of the typed DOM API are organized beyond <code>org.odftoolkit.odfdom.dom.*</code>
 
-The sources for the ODF elements are all generated from the ODF grammar (RelaxNG schema)
using the following naming conventions in the Java reference implementation:
-* The class name is equal to the element local name using the Namespace as prefix and 'Element'
as suffix (e.g. the 'draw:frame' element has the <code>DrawFrameElement</code>
class). 
-* Elements are stored beyond a sub-package equal to their Namespace used by the OOo. Therefore
the frame element 'draw:frame' would be generated in Java as class <code>org.odftoolkit.odfdom.dom.draw.DrawFrameElement</code>.
+The sources for the ODF elements are all generated from the ODF grammar (RelaxNG schema)
using the following naming conventions in the Java reference implementation:   
 
-'''Note:''' The element local names 'h' and 'p' have been renamed to the classes 'Heading'
and 'Paragraph' for usability reasons.
+- The class name is equal to the element local name using the Namespace as prefix and 'Element'
as suffix (e.g. the 'draw:frame' element has the <code>DrawFrameElement</code>
class).  
+- Elements are stored beyond a sub-package equal to their Namespace used by the OOo. Therefore
the frame element 'draw:frame' would be generated in Java as class <code>org.odftoolkit.odfdom.dom.draw.DrawFrameElement</code>.
+
+***Note:*** The element local names 'h' and 'p' have been renamed to the classes 'Heading'
and 'Paragraph' for usability reasons.
 
 The following example illustrates how to add a graphic to the ODF document, that it is viewable:
-<pre>
- 
-import java.net.URI;
-import org.odftoolkit.odfdom.OdfElement;
-import org.odftoolkit.odfdom.doc.OdfDocument;
-import org.odftoolkit.odfdom.doc.OdfTextDocument;
-import org.odftoolkit.odfdom.doc.draw.OdfDrawImage;
-import org.odftoolkit.odfdom.dom.element.draw.DrawFrameElement;
-import org.odftoolkit.odfdom.dom.element.office.OfficeTextElement;
-import org.odftoolkit.odfdom.dom.element.text.TextPElement;
-
-[...]
-
-// Load file
-OdfTextDocument odt = (OdfTextDocument) OdfDocument.loadDocument("ImageIn.odt");
-            
-// get root of all content of a text document
-OfficeTextElement officeText = odt.getContentRoot();
-            
-// get first paragraph
-TextPElement firstParagraph = 
-  OdfElement.findFirstChildNode(TextPElement.class, officeText);
-            
-// XPath alternative to get the first paragraph
-/*
-  XPath xpath = XPathFactory.newInstance().newXPath();
-  xpath.setNamespaceContext(new OdfNamespace());
-  OdfFileDom dom = odt.getContentDom();
-  firstParagraph = (TextPElement) xpath.evaluate("//text:p[1]", dom, XPathConstants.NODE);
-*/
-
-// insert a frame
-DrawFrameElement frame = firstParagraph.newDrawFrameElement();
-            
-// insert an image: This is a class from the Document API
-OdfDrawImage image = (OdfDrawImage) frame.newDrawImageElement();
-image.newImage(new URI("./MySampleImage.png"));
-            
-// Save file
-odt.save("ImageOut.odt");
-</pre>
-<br/>
-Even in this example we had to refer to a class from the Document API. Otherwise our implementation
had gotten quite long and complex. 
 
-<br/>
+    import java.net.URI;
+    import org.odftoolkit.odfdom.OdfElement;
+    import org.odftoolkit.odfdom.doc.OdfDocument;
+    import org.odftoolkit.odfdom.doc.OdfTextDocument;
+    import org.odftoolkit.odfdom.doc.draw.OdfDrawImage;
+    import org.odftoolkit.odfdom.dom.element.draw.DrawFrameElement;
+    import org.odftoolkit.odfdom.dom.element.office.OfficeTextElement;
+    import org.odftoolkit.odfdom.dom.element.text.TextPElement;
+    
+    [...]
+    
+    // Load file
+    OdfTextDocument odt = (OdfTextDocument) OdfDocument.loadDocument("ImageIn.odt");
+                
+    // get root of all content of a text document
+    OfficeTextElement officeText = odt.getContentRoot();
+                
+    // get first paragraph
+    TextPElement firstParagraph = 
+      OdfElement.findFirstChildNode(TextPElement.class, officeText);
+                
+    // XPath alternative to get the first paragraph
+    /*
+      XPath xpath = XPathFactory.newInstance().newXPath();
+      xpath.setNamespaceContext(new OdfNamespace());
+      OdfFileDom dom = odt.getContentDom();
+      firstParagraph = (TextPElement) xpath.evaluate("//text:p[1]", dom, XPathConstants.NODE);
+    */
+    
+    // insert a frame
+    DrawFrameElement frame = firstParagraph.newDrawFrameElement();
+                
+    // insert an image: This is a class from the Document API
+    OdfDrawImage image = (OdfDrawImage) frame.newDrawImageElement();
+    image.newImage(new URI("./MySampleImage.png"));
+                
+    // Save file
+    odt.save("ImageOut.odt");
 
-===The ODF Document API===
+Even in this example we had to refer to a class from the Document API. Otherwise our implementation
had gotten quite long and complex. 
+
+**The ODF Document API**
 
 The ODF Document API provides a different much more high level view on the ODF schema features.
This API is concerned about usability, hiding all ODF XML implementation details from the
user, covering frequent user scenarios. For example, changing the content of a certain spreadsheet
cell (e.g. Add 'Hello World' to a spreadsheet cell positioned at 'B2'). While in the ODF DOM
API in general each class represents an ODF XML node, here a class covers multiple underlying
ODF XML elements (& their attributes). Think of puzzle piece consisting of multiple smaller
pieces. Therefore the typed DOM tree is being mapped to feature tree.
 
@@ -131,7 +129,7 @@ The name of a document class is in gener
 
 For example, the document class for a 'draw:frame' element would be represented in the ODFDOM
Java reference implemenation as <code>org.odftoolkit.odfdom.doc.draw.OdfDrawFrame</code>
class. Some classes of the Document API differ from this naming convention, e.g. OdfTextParagraph
is the subclass of TextPElement. However by browsing the packages you will easily find the
classes your looking for.
 
-'''Note:''' The Document API will change. The current inheritance between DOM and DOC elements
does not fit any longer in the multiple elements to a single document feature (1:n) pattern.
The first Document Object is the table <code>rg.odftoolkit.odfdom.doc.table.OdfTable</code>,
others will follow soon.
+***Note:*** The Document API will change. The current inheritance between DOM and DOC elements
does not fit any longer in the multiple elements to a single document feature (1:n) pattern.
The first Document Object is the table <code>rg.odftoolkit.odfdom.doc.table.OdfTable</code>,
others will follow soon.
 
 Again let's look at the previous code example for the DOM API: Remember all DOM element classes
are abstract and we're really getting objects from the Document API: Even if <code>frame.newDrawFrameElement()</code>
is defined to return the DOM class DrawFrameElement, it really returns the DOC subclass OdfDrawFrame.
So it's always save to use explicit casting <code>OdfDrawFrame frame = (OdfDrawFrame)
firstParagraph.newDrawFrameElement();</code>.
 
@@ -139,26 +137,38 @@ However reworking the previous example w
 
 Here's an example for working with DOC classes, completely avoiding handling the DOM manually:
 
-<pre>
-[...]
-// Load Image
-OdfTextDocument odt = (OdfTextDocument) OdfDocument.loadDocument("ImageIn.odt");
-
-// Play around with text
-odt.addText("When there is no paragraph, the text will be embedded in a new paragraph");
-odt.newParagraph("Create new paragraph");
-odt.addText("\nThis is a new line");
-
-// Insert Image and make last paragraph its anchor
-odt.newImage(new URI("./MySampleImage.png"));
-
-// Insert new spreadsheet as sub document into the package within directory  "myOdsDirectoryPath/"
-odt.insertDocument(OdfSpreadsheetDocument.newSpreadsheetDocument(), "myOdsDirectoryPath");
-
-// Save file
-odt.save("ImageOut.odt");
-</pre>
-
-<br/>
-
-<p style="margin: 15px 0px; text-align:center">Go on reading about [[Development|how
to set up a building environment and where to get the source code]].</p>
+    [...]
+    // Load Image
+    OdfTextDocument odt = (OdfTextDocument) OdfDocument.loadDocument("ImageIn.odt");
+    
+    // Play around with text
+    odt.addText("When there is no paragraph, the text will be embedded in a new paragraph");
+    odt.newParagraph("Create new paragraph");
+    odt.addText("\nThis is a new line");
+    
+    // Insert Image and make last paragraph its anchor
+    odt.newImage(new URI("./MySampleImage.png"));
+    
+    // Insert new spreadsheet as sub document into the package within directory  "myOdsDirectoryPath/"
+    odt.insertDocument(OdfSpreadsheetDocument.newSpreadsheetDocument(), "myOdsDirectoryPath");
+    
+    // Save file
+    odt.save("ImageOut.odt");
+
+
+Go on reading about [how to set up a building environment and where to get the source code][13].
+
+
+  [1]: ODFDOM-New-Layered-Model.png
+  [2]: http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part3.html
+  [3]: http://www.pkware.com/documents/APPNOTE/APPNOTE_6.2.0.txt
+  [4]: http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/
+  [5]: http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/
+  [6]: http://www.w3.org/TR/2004/REC-rdf-concepts-20040210/
+  [7]: ODF_Package.jpg
+  [8]: http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part1.html
+  [9]: http://www.w3.org/DOM/
+  [10]: http://www.w3.org/DOM/
+  [11]: FruitTable_code.jpg
+  [12]: Table_fruits_diagramm.jpg
+  [13]: Development.html
\ No newline at end of file



Mime
View raw message