Re: [dev] Generating a simple document

Hello Gregor,

First of all, sorry for the confusion of the deprecation of the APIs.
It has historical reasons, we are about to fix it. Allow me to tell you the
full story:

The ODF Toolkit was funded by StarOffice, a company from Hamburg being
bought up by Sun Microsystems in 1999. I started at StarOffice as a
software developer exactly at that time.
The Toolkit itself started about 10 years later, I guess about 2007 when
StarOffice started its second attempt on a web office using ODFDOM as its
backend.
IBM joined the forces of the ODF Toolkit, the common idea was to have an
ODF Java library for the server. But IBM wanted to focus on a higher-level
API for their customer needs first, while others - me among them -
preferred to focus on improving first the generation of the DOM source code
from the ODF XML grammar, to save in the end time by the improved generated
source code. So IBM forked ODFDOM and rebranded it as Simple API.
In fact, Simple API is using ODFDOM, but is derived from the ODFDOM
high-level API, the DOC Java package:
https://github.com/tdf/odftoolkit/tree/1.0.0_SNAPSHOT/odfdom/src/main/java/org/odftoolkit/odfdom/doc


Anyway, when Oracle "returned" OpenOffice 2011 to the community, they
donated OpenOffice and the ODF Toolkit to the Apache foundation. Now IBM
joined back the team but unfortunately did not merge their fork (Simple
API, which includes many copy/pasted parts from ODFDOM). Instead, they
added Simple API as a separate library aside in the Toolkit.
Therefore, with the Simple API on board, not realizing how much IBM had
copied, we kept Simple API and marked our second high-level API (the ODFDOM
DOC layer) as deprecated in favour of reunited friends.
But when IBM left OpenOffice, they left the ODF Toolkit as well. Now we
were suddenly the owner of their fork.

I had little time to take care of the Apache incubator project at that time
myself, as I was working for Open-XChange (OX) on my third web office,
using ODFDOM as the backend:
https://www.open-xchange.com/portfolio/ox-documents/
Unfortunately, the OX team forked as well the ODFDOM before I joined them
and it took me quite a while in the past years to manually merge my work
back into our ODFDOM (the 1.0.0_SNAPSHOT branch). When I merged the major
feature of my work at OX - the concept of changes - back into the ODFDOM, I
realized that it was not possible to be applied to the Simple API due to
their massively copied code.
Therefore we dropped the Simple API, realizing that it was too much of a
redundancy.
Unfortunately, we have at the moment no similar advanced high-level API
ready to migrate to.

Still, our idea is to provide a high-level API accessing the document by
its - to users well-known - entities. For instance, table, image,
paragraph, character, etc.
Everything a user is adding/deleting in an Office GUI is a candidate for
such a semantic entity.
What we already have with 1.0.0 is a change API based on these semantic
entities, which allows collaboration by exchanging user changes, like "I
make the 3rd paragraph background colour red" or "I insert a new 2nd
Paragraph".
You may find this Change API documentation online:
https://tdf.github.io/odftoolkit/docs/odfdom/operations/operations.html
The creation of a higher level Semantic DOM API (similar to Simple API),
but more aligned with the Change API above is one of our goals in the next
year.

As I talked so much about history, there is little room for your other
questions. Your approach seems valid to me.
I would - as you did - create an invoice ODT as you desire it look like in
one of the ODF (WYSIWYG) applications like LibreOffice
<https://www.libreoffice.org/>(or Abiword <https://www.abisource.com/>,
Calligra <https://calligra.org/>, even MS Word <https://www.office.com/>).
Load it into ODFDOM to alter it afterwards by automation. You might even
extract & load XML junks into your document like address via its DOM API.
The https://odfvalidator.org/ might become handy, but don't worry about XML
nodes that are not yet standardized, but already in testing. In
LibreOffice, their prefix is "loext" (LibreOffice extension).
Might be a nice tutorial if you are willing to share your experiences with
others.

I am working on evaluating a new way of documentation and a bit on ODF 1.3
support in the next future - and finally doing the releases. Sorry for the
delay, but I really don't like to write documentation...

Best regards,
Svante



Am Mo., 8. Juni 2020 um 16:06 Uhr schrieb Gregor Raab <
gregor.raab@freenet.de>:

> I'm started to explore the odftoolkit some days before and I'm curious,
> whether I could generate a simple invoice using some existing data.
>
> The invoice-document starts with an "address"-paragraph, followed by a
> table with product-items, again followed by a paragraph with additional
> information.
>
> I began with the following steps:
>
> 1) loading an existing template-document:
>
>          OdfTextDocument outputDocument
> =OdfTextDocument.loadDocument(templateFile);
>          OdfFileDom contentDom = outputDocument.getContentDom();
>
> Is this the right beginning? I also found:
>
> OdfDocument anotherOutputDocument = OdfDocument.loadDocument(templateFile);
>
> 2) adding the address:
>
>             outputDocument.newParagraph(address.toString());
>
> 3) adding a table:
>
>                  OdfTable table = OdfTable.newTable(outputDocument,
> positions.size(), 5);
>
> 4) adding the product-items:
>
>
>                  for (Position position : positions) {
>                      OdfTableRow rowForPosition =
> table.getRowByIndex(position.getPos());
>                      // first-cell in row
>                      OdfTableCell cellPosNr =
> rowForPositionIndex.getCellByIndex(0);
>                      cellPosNr.setStringValue(position.getPos());
>                      // Icon (I would like to include a jpg):
>                      String strFile = position.getImageFilePath("icon");
>                      File imageFile = new File(strFile);
>                      if(imageFile.exists()) {
>                         OdfTableCell cellIcon =
> rowForPositionIndex.getCellByIndex(1);
>                         OdfDrawImage image = new OdfDrawImage(contentDom);
>                        image.newImage(new URI(strFile));
>                        cellIcon.getOdfElement().appendChild(image);
>                      }
>                      // some other stuff..
>
> 5) returning the document.
>
> I'm a little bit puzzled, since the doku says, that "OdfTableCell" is
> deprecated, but I read at the mail-archive: "deprecated afterwards in
> favour of the
> Simple API and now likely being enabled again".
>
> In the end, I got an odt-document and was able to open it using
> libreoffice.
>
> Unfortunately I didn't succeed to add the image to the table cell. Can
> you give me an advice, how this should be implemented?
>
> And a more general question: Is this the way, the ofttoolkit should be
> used?
>
>
>
>
> --
> To unsubscribe e-mail to: dev+unsubscribe@odftoolkit.org
> Problems?
> https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
> Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette
> List archive: https://listarchives.odftoolkit.org/dev/
> Privacy Policy: https://www.documentfoundation.org/privacy

-- 
To unsubscribe e-mail to: dev+unsubscribe@odftoolkit.org
Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette
List archive: https://listarchives.odftoolkit.org/dev/
Privacy Policy: https://www.documentfoundation.org/privacy