RE: Re: [dev] Generating a simple document

                      Hello Svante,

so you allready had a long, interesting but sometimes painfull journey together with the odftoolkit 
:-)
Let me try a conclusion of your answer concerning my question:
For creating documents my approach seems to be valid, the ODFDO APIs are appropriate for implementing my 
"invoice-generator". There is also a change API, but for my task, creating a document, using it may 
not be the better solution.
Adding images to a table-cell is not implemented via High-Leverl API at the moment. But is there an 
alternative approach?
...and of course I would offer my results at least as a draft-tutorial to the tdf-community.

Best regards,
Gregor



-----ursprüngliche Nachricht-----
Von:  svante.schubert@gmail.com (mailto:svante.schubert@gmail.com"; target="_blank" rel="noopener)
Gesendet: 09.06.2020 19:11 Uhr
An:  gregor.raab@freenet.de (mailto:gregor.raab@freenet.de"; target="_blank" rel="noopener)
Kopie:  dev@odftoolkit.org (mailto:dev@odftoolkit.org"; target="_blank" rel="noopener)
Betreff: 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 firstthe 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 (https://github.com/tdf/odftoolkit/tree/1.0.0_SNAPSHOT/odfdom/src/main/java/org/odftoolkit/odfdom/doc"; target="_blank" rel="noopener)  

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/ (https://www.open-xchange.com/portfolio/ox-documents/"; target="_blank" rel="noopener) 
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 (https://tdf.github.io/odftoolkit/docs/odfdom/operations/operations.html"; target="_blank" rel="noopener) 
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/"; 
target="_blank" rel="noopener)(or  Abiword (https://www.abisource.com/"; target="_blank" rel="noopener),  Calligra (https://calligra.org/"; 
target="_blank" rel="noopener), even  MS Word (https://www.office.com/"; target="_blank" rel="noopener)).
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/ (https://odfvalidator.org/"; target="_blank" rel="noopener) 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 (mailto:gregor.raab@freenet.de"; 
target="_blank" rel="noopener)>:
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 (mailto:dev+unsubscribe@odftoolkit.org"; 
target="_blank" rel="noopener)
Problems?  https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ 
(https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/"; target="_blank" 
rel="noopener noreferrer)
Posting guidelines + more:  https://wiki.documentfoundation.org/Netiquette 
(https://wiki.documentfoundation.org/Netiquette"; target="_blank" rel="noopener noreferrer)
List archive:  https://listarchives.odftoolkit.org/dev/ (https://listarchives.odftoolkit.org/dev/"; 
target="_blank" rel="noopener noreferrer)
Privacy Policy:  https://www.documentfoundation.org/privacy (https://www.documentfoundation.org/privacy"; 
target="_blank" rel="noopener noreferrer)



-----ursprüngliche Nachricht Ende-----    



--
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