incubator-odf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Svante Schubert <svante.schub...@gmail.com>
Subject Re: Introducing a new PropertiesBase class in Simple API
Date Wed, 23 Nov 2011 12:54:36 GMT
You addressed an important point, Oliver.
The style handling seems currently the weakest spot of the Simple API.

>From your proposal only our opinion on how to archive Simplicity for the
the high level API (now Simple API, earlier the ODFDOM DOC API) differ.
Instead of archiving simplicity by neglecting functionality, I would
rather prefer to improve the abstraction of ODF XML implementation details.
Allow me to draft what I have in mind:


      ODF Style Requirement

In the more or less distant future the users of the Simple API should be
able to traverse their ODF document based on a component tree.
Components are common known user modules. For instance: table, section,
paragraph or text, which are yet unspecified by the ODF TC.
They are like larger puzzle pieces of underlying XML. Hiding the ODF XML
details from the user.

In this component view, styles are only a certain type of meta data
(layout information) attached to the component.
In ODF the styles can be attached to a component by two ways:

 1. The user might use predefined style set (e.g. "Heading 1" or
 2. The user might single style properties to a component

NOTE: The Simple API should only allow styles appropriate to a component.

No more complexity should be necessary for a user (perhaps there still
might be the feature to allow inheritance among styles of the same family).
That might be possible if the ODF style complexity is handled by APIs
beyond the Simple API, like the ODFDOM API.


      ODF Style Complexity

If for example the user would like to change the background color of a
cell following ODF details have to be considered:

  * The ID of a style is not the string @style:name. The style:name is
    only unique in conjunction with its @style:family
  * In addition the style name of automatic styles is an implementation
    detail and might change during a load/save round-trip of the document.
    In other words: the user accesses the (automatic) style properties
    directly at the component.
  * Every component that is able to have styles has a @style:family
    attribute. Each style family has up to three style properties
    elements, which have their own style properties attributes.
    The most interesting case is a cell, which has three background
    colors. One in each of their style properties sets for cell,
    paragraph and text. One is the cell background, the next the default
    background for all paragraph and the last the default background
    color for all text. The API might reflect this by allowing to set
    default values for paragraph and text content (see as well the notes
    on style design at issue 49
    <https://issues.apache.org/jira/browse/ODFTOOLKIT-49>).


      Design against Gordian Knot

The key question to solve the riddle is, where to handle the automatic
styles?
As noted above automatic style sets are an implementation detail for the
user, therefore although each style property should be accessible, the
collection have to remain invisible in the Simple API.
Automatic styles are neither part of the ODF Package API, as they are
specified in part 1 of the specification
<http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part1.html>.
Therefore they have to be implemented in the mainly from ODF RelaxNG
schema generated ODFDOM API.
Are they able to be generated? I guess they can, see issue 182
<https://issues.apache.org/jira/browse/ODFTOOLKIT-182>.
Unfortunately there is still that issue 187
<https://issues.apache.org/jira/browse/ODFTOOLKIT-187> blocking the
above approach.

Two main concepts are missing in the Simple API:

 1. The existence and ability to traverse components, which are mappable
    to ODFDOM classes if desired
 2. The ability to add style properties to components. Directly
    (automatic style set) or via a named set (named style set)

Conclusion:
Your approach should in the end show up as little helper classes
(boilerplate) as possible in the Simple API, but instead move those
helpers to the generated underlaying ODFDOM API.

Best regards,
Svante



Am 15.11.2011 21:03, schrieb Oliver Rau:
> Hi Everybody,
>
> while writing a couple of enhancements for to the Simple API, some of
> them were in the area around the various properties types, e.g.
> GraphicProperties, ParagraphProperties etc..
>
> Now as Simple should be what it is called, simple, it is unlikely that
> we will ever reach the point were every property can be accessed. The
> usual way to go then is to OdfDom, however the problem is that there
> is a lot of magic involved in order to get to the actual properties
> element (getting styles, getting automatic styles, etc) and being able
> to set attributes on it.
>
> What I'm thinking about would be to introduce an base class that each
> Properties implementation would either inherit from. This base class
> would provide bridges to the OdfDom world, e.g. something similar like
> a method called getPropertiesElement. This would return the low level
> OdfDom Properties Element, e.g. StyleGraphicPropertiesElement in case
> of the GraphicProperties.
>
> The user of the API would now be able to set any property he wants.
>
> An additional method (or alternative variant to the above) could be a
> method that allows getting / setting properties by name, e.g.
> getProperty(name) and setProperty(name, value).
>
> What do you guys think?
>
>
> Regards
>
>
> Oliver



Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message