ODF Toolkit
  1. ODF Toolkit
  2. ODFTOOLKIT-49

Refactoring of DOM style implementation

    Details

    • Type: Bug Bug
    • Status: Reopened
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: simple-odfdom-0.8
    • Fix Version/s: None
    • Component/s: java
    • Labels:
      None
    • Environment:
      Operating System: All
      Platform: All

      Description

      There is a dependency of the DOM layer to the DOC layer that should be questions (although there might be dependency between those layers in the futures).

      The relation of a <style:style having a certain @style:family to a set of child elements <stlye:-properties> and the relation of each of those <style:-properties> to the fixed set of style attributes have to be resolved.

      The reason: The use wants to know what style properties he is able to set.
      He is not interested in @style:family and their children.

      Design draft:
      Perhaps there is a two level enumeration possible? (uncertain yet).

        Issue Links

          Activity

          Hide
          tony wei added a comment -

          In 0.7 we meet a style family issue. When an OdfDrawFrame element was created in presenation, it's family will be set to "OdfStyleFamily.Graphic" by default, but it should be "presentation. Although you can explicitly set to "OdfStyleFamily.presentation", it need developer know which situation this element is. Could we let styleFamily automaticlly be set based on it parent container or some situation.

          Show
          tony wei added a comment - In 0.7 we meet a style family issue. When an OdfDrawFrame element was created in presenation, it's family will be set to "OdfStyleFamily.Graphic" by default, but it should be "presentation. Although you can explicitly set to "OdfStyleFamily.presentation", it need developer know which situation this element is. Could we let styleFamily automaticlly be set based on it parent container or some situation.
          Hide
          Svante Schubert added a comment -

          Yes, the @style:family is a real implementation detail of the ODF XML and every styleable element has one fixed value that will never change, which should be generated into the class. That was the reason, why the config.xml was created in the beginning to store the styleable element to @style:family relationship.
          This problem should be solved (uncertain if a regression test exists).

          The problem I refer to is the relation between the different properties elements and their style properties attributes.

          The user needs to know what kind of style attributes (or properties) can be set and some of the style attributes have the same name:

          Worst case I know:
          A <table:table-cell> is of style family table-cell and can have three property sets in the elements:

          <style:text-properties>
          <style:paragraph-properties>
          <style:table-cell-properties>

          Each one of them can have a different @fo:background-color.

          Show
          Svante Schubert added a comment - Yes, the @style:family is a real implementation detail of the ODF XML and every styleable element has one fixed value that will never change, which should be generated into the class. That was the reason, why the config.xml was created in the beginning to store the styleable element to @style:family relationship. This problem should be solved (uncertain if a regression test exists). The problem I refer to is the relation between the different properties elements and their style properties attributes. The user needs to know what kind of style attributes (or properties) can be set and some of the style attributes have the same name: Worst case I know: A <table:table-cell> is of style family table-cell and can have three property sets in the elements: <style:text-properties> <style:paragraph-properties> <style:table-cell-properties> Each one of them can have a different @fo:background-color.
          Hide
          Svante Schubert added a comment -

          When we talk about style refactoring, we now refer to all problems related to styles. Daisy and I agreed in analyzing and ordering the existing style issues to find the easiest way to solve them.

          The desired future design for styles is easy to be defined:

          • The DOM layer should focus on ODF XML details. Simple design, the sources should be generated by code generation from the latest ODF schema
          • The DOC layer should mask the ODF XML details (e.g. style:family association) from the API user.
            The user should be able to attach single style properties or a collection of styles via a name to stylable features.
            Note: There have been notions to map style properties to a simplified access. For instance to be able to set "bold" instead of fo:font-weight="bold", most likely neglecting the constant integer values.

          The status quo:
          The layer concept is sometimes broken for style related classes.

          Some inital information and suggestions to base our style discussion:

          • The classes beyond org.odftoolkit.odfdom.dom.style
            o are not regenerated. Had been generated once years ago, never again.
            o The XML DOM part should be beyond element.style
            o The usability functionality part should be in the DOC package (e.g. doc.style). (Major parts of class representing style:family).
          • OdfFileDom is accessing style classes (DOC API / XML layer) although itself part of the package layer. We should consider four child classes ..dom.OdfContentDom, OdfStylesDom, OdfMetaDom, OdfSettingsDom, where only two of them have the styles functionality.
          • The correlation between style:family and their sets of style properties should not be a burden for the user of the DOC layer. Still ODF functionality should not get lost by ODF XML capsulation. For instance a table cell might have three different background color:
            1. one as default for the cell
            2. second for the default of all paragraphs within the cell
            3. third as default of all text background.
          • There are two important fixed relationships for every ODF XML element that might receive a style:
            1. Every styleable element has a style:family (special case: see #51)
            2. Every style family has one or more style property sets (see table above)
            In the end the user would like to see on the element, what properties might being added.
          • A requirement from issue 29 (see http://odftoolkit.org/bugzilla/show_bug.cgi?id=29 ) is to cover in the generated DOM as well update functionality for the style pools. For instance, whenever an automatic style is being updated from the DOM API (e.g. the styles name attribute value was changed) the automatic styles pool should be updated as well. Perhaps via the DOM event handling.
          • Special style realted interfaces as the OdfStylePropertySet should be questions if there are no more elegant (e.g. W3C DOM API solutions) to cover the same effect
          • Not mandatory for styles, but helpful for a clean design:
            We should consider providing two different kind of Documents, one related to the DOM layer providing the XML details, the other related to the DOC layer providing usability functions. For instance only the dom layered XML related ODF document would give access to the XML subfiles.
            This would help us to avoid XML details from the user.
          Show
          Svante Schubert added a comment - When we talk about style refactoring, we now refer to all problems related to styles. Daisy and I agreed in analyzing and ordering the existing style issues to find the easiest way to solve them. The desired future design for styles is easy to be defined: The DOM layer should focus on ODF XML details. Simple design, the sources should be generated by code generation from the latest ODF schema The DOC layer should mask the ODF XML details (e.g. style:family association) from the API user. The user should be able to attach single style properties or a collection of styles via a name to stylable features. Note: There have been notions to map style properties to a simplified access. For instance to be able to set "bold" instead of fo:font-weight="bold", most likely neglecting the constant integer values. The status quo: The layer concept is sometimes broken for style related classes. Some inital information and suggestions to base our style discussion: The classes beyond org.odftoolkit.odfdom.dom.style o are not regenerated. Had been generated once years ago, never again. o The XML DOM part should be beyond element.style o The usability functionality part should be in the DOC package (e.g. doc.style). (Major parts of class representing style:family). OdfFileDom is accessing style classes (DOC API / XML layer) although itself part of the package layer. We should consider four child classes ..dom.OdfContentDom, OdfStylesDom, OdfMetaDom, OdfSettingsDom, where only two of them have the styles functionality. The correlation between style:family and their sets of style properties should not be a burden for the user of the DOC layer. Still ODF functionality should not get lost by ODF XML capsulation. For instance a table cell might have three different background color: 1. one as default for the cell 2. second for the default of all paragraphs within the cell 3. third as default of all text background. There are two important fixed relationships for every ODF XML element that might receive a style: 1. Every styleable element has a style:family (special case: see #51) 2. Every style family has one or more style property sets (see table above) In the end the user would like to see on the element, what properties might being added. A requirement from issue 29 (see http://odftoolkit.org/bugzilla/show_bug.cgi?id=29 ) is to cover in the generated DOM as well update functionality for the style pools. For instance, whenever an automatic style is being updated from the DOM API (e.g. the styles name attribute value was changed) the automatic styles pool should be updated as well. Perhaps via the DOM event handling. Special style realted interfaces as the OdfStylePropertySet should be questions if there are no more elegant (e.g. W3C DOM API solutions) to cover the same effect Not mandatory for styles, but helpful for a clean design: We should consider providing two different kind of Documents, one related to the DOM layer providing the XML details, the other related to the DOC layer providing usability functions. For instance only the dom layered XML related ODF document would give access to the XML subfiles. This would help us to avoid XML details from the user.
          Hide
          Svante Schubert added a comment -

          Some notes on style design.

          First we might focus on automatic styles and named styles as primary example for all styles. Most other styles as list styles behave similar and we may adapt most of the design.

          Some question & answers to bring us all on the same level.

          Q: What is a style?
          A style is a collection of various style properties describing the format of an ODF element/component (e.g. color or font seize).

          Q: Where can styles be used?
          A: From XML/DOM perspective on all elements that have @*:style-name attribute, e.g. @text:style-name or @table:style-name.
          In general on all elements that have text or paragraph children.
          From DOC API perspective on most visible components.

          Q: What is the difference between an automatic style and a named style?
          The automatic style comes without name and is similar to the HTML inline style attached directly and unique to the element.
          The automatic style is not reusable, as there is no key/name to access this style.
          A automatic style might only inherit from a named style. The named style usually only from another named style.

          Q: How are automatic & named styles designed in ODF?
          A:
          In ODF each stylable element is aligned to a style:family, which has a fixed set of property sets.
          There is the following relation ship:
          1 "StyleableElement"
          – has –
          1 "style:family"
          – has –
          N "style properties set"
          – has –
          M "single style property"

          The relation between stylable element and style:family has been extracted from the spec and can be found in
          odfdom~developer/src/codegen/resources/dom/config.xml
          To get an idea about the possible amount of styles to be set, take a look at the deprecated OdfStyleFamily.java found in
          odfdom~developer/src/main/java/org/odftoolkit/odfdom/dom/style/

          The most interesting case is the table:table-cell, which similar named @style:family value is related to three sets of style properties.
          One for the cell, one for all paragraphs within the cell and one for the text within the cell.
          Notable that all styles might contain a different fo:background-color style property, which all effect the layout.
          Therefore the DOC layer needs the possibility to add background color in three different ways on a cell.

          Design:
          A automatic style might be handled internally as a named style without name for the stylable element.
          Automatic style names are an ODF implementation detail and must not be part of the DOC API.

          The large amount of single style properties provoke the idea to bundle those methods, instead of repeating them on all stylable elements/components.
          Another argument for bundling is the reusage of style property sets grouped by a style family.
          The contrary design is to add a method for every possible style format on the stylable element/component, e.g.

          cell.setTextBackgroundColor(..)
          cell.setParagraphBackgroundColor(..)
          cell.setCellBackgroundColor(..)

          I drafted various versions of the bundled option and will discuss them with colleagues the next days:

          cell.style.setTextBackgroundColor(..)
          cell.style.setParagraphBackgroundColor(..)
          cell.style.setCellBackgroundColor(..)

          // NULL might be used for automatic style
          cell.getStyle().setTextBackgroundColor(..)
          cell.getStyle().setParagraphBackgroundColor(..)
          cell.getStyle().setCellBackgroundColor(..)

          // THERE IS ALWAYS ONLY ONE TEXT/PARAGRAPH/CELL CONTAINER
          // STYLE NULL EXCEPTION PROBLEM
          cell.style.text.setBackgroundColor(..)
          cell.style.cell.setBackgroundColor(..)
          cell.style.paragraph.setBackgroundColor(..)

          cell.getTextStyles.setBackgroundColor(..)
          cell.getCellStyles.setBackgroundColor(..)
          cell.getParagraphStyles.setBackgroundColor(..)

          cell.getStylesText.setBackgroundColor(..)
          cell.getStylesCell.setBackgroundColor(..)
          cell.getStylesParagraph.setBackgroundColor(..)

          cell.style.setBackgroundColor(..)
          cell.paragraph.style.setBackgroundColor(..)
          cell.text.style.setBackgroundColor(..)

          Aside of the flood of methods that make an API hard to use, is my personal requirement that a user get as much help as
          possible with applicable arguments on the methods. For instance, what can be set for a setBackgroundColor?
          The fo:background-color style attribute should give sufficient information by its constructor, which could be related to the method.
          The source code generation have to be improved to help us here.
          In the end we will pick up our favorite design versions and generate prototypes by the generator to see how the JavaDoc API might look like in real-life.

          Going to focus on source code generation the next days,
          Svante

          Show
          Svante Schubert added a comment - Some notes on style design. First we might focus on automatic styles and named styles as primary example for all styles. Most other styles as list styles behave similar and we may adapt most of the design. Some question & answers to bring us all on the same level. Q: What is a style? A style is a collection of various style properties describing the format of an ODF element/component (e.g. color or font seize). Q: Where can styles be used? A: From XML/DOM perspective on all elements that have @*:style-name attribute, e.g. @text:style-name or @table:style-name. In general on all elements that have text or paragraph children. From DOC API perspective on most visible components. Q: What is the difference between an automatic style and a named style? The automatic style comes without name and is similar to the HTML inline style attached directly and unique to the element. The automatic style is not reusable, as there is no key/name to access this style. A automatic style might only inherit from a named style. The named style usually only from another named style. Q: How are automatic & named styles designed in ODF? A: In ODF each stylable element is aligned to a style:family, which has a fixed set of property sets. There is the following relation ship: 1 "StyleableElement" – has – 1 "style:family" – has – N "style properties set" – has – M "single style property" The relation between stylable element and style:family has been extracted from the spec and can be found in odfdom~developer/src/codegen/resources/dom/config.xml To get an idea about the possible amount of styles to be set, take a look at the deprecated OdfStyleFamily.java found in odfdom~developer/src/main/java/org/odftoolkit/odfdom/dom/style/ The most interesting case is the table:table-cell, which similar named @style:family value is related to three sets of style properties. One for the cell, one for all paragraphs within the cell and one for the text within the cell. Notable that all styles might contain a different fo:background-color style property, which all effect the layout. Therefore the DOC layer needs the possibility to add background color in three different ways on a cell. Design: A automatic style might be handled internally as a named style without name for the stylable element. Automatic style names are an ODF implementation detail and must not be part of the DOC API. The large amount of single style properties provoke the idea to bundle those methods, instead of repeating them on all stylable elements/components. Another argument for bundling is the reusage of style property sets grouped by a style family. The contrary design is to add a method for every possible style format on the stylable element/component, e.g. cell.setTextBackgroundColor(..) cell.setParagraphBackgroundColor(..) cell.setCellBackgroundColor(..) I drafted various versions of the bundled option and will discuss them with colleagues the next days: cell.style.setTextBackgroundColor(..) cell.style.setParagraphBackgroundColor(..) cell.style.setCellBackgroundColor(..) // NULL might be used for automatic style cell.getStyle().setTextBackgroundColor(..) cell.getStyle().setParagraphBackgroundColor(..) cell.getStyle().setCellBackgroundColor(..) // THERE IS ALWAYS ONLY ONE TEXT/PARAGRAPH/CELL CONTAINER // STYLE NULL EXCEPTION PROBLEM cell.style.text.setBackgroundColor(..) cell.style.cell.setBackgroundColor(..) cell.style.paragraph.setBackgroundColor(..) cell.getTextStyles.setBackgroundColor(..) cell.getCellStyles.setBackgroundColor(..) cell.getParagraphStyles.setBackgroundColor(..) cell.getStylesText.setBackgroundColor(..) cell.getStylesCell.setBackgroundColor(..) cell.getStylesParagraph.setBackgroundColor(..) cell.style.setBackgroundColor(..) cell.paragraph.style.setBackgroundColor(..) cell.text.style.setBackgroundColor(..) Aside of the flood of methods that make an API hard to use, is my personal requirement that a user get as much help as possible with applicable arguments on the methods. For instance, what can be set for a setBackgroundColor? The fo:background-color style attribute should give sufficient information by its constructor, which could be related to the method. The source code generation have to be improved to help us here. In the end we will pick up our favorite design versions and generate prototypes by the generator to see how the JavaDoc API might look like in real-life. Going to focus on source code generation the next days, Svante
          Hide
          Svante Schubert added a comment -

          Going to overwork style handling..

          Show
          Svante Schubert added a comment - Going to overwork style handling..
          Hide
          Svante Schubert added a comment -

          Created an attachment (id=483)
          Moving styles access from OdfFileDom to OdfStylesDom & OdfContentDom

          As an intermediate step, I have moved the style access methods from the package layer OdfFileDom to OdfStylesDom and automatic style access to OdfStylesDom & OdfContentDom.

          As styles can never be found in meta.xml or settings.xml, but only in content.xml and styles.xml.
          NOTE: The reason automatic styles can be found in styles.xml is the existence of the header & footer content in the page style being part of the styles.xml file.

          Show
          Svante Schubert added a comment - Created an attachment (id=483) Moving styles access from OdfFileDom to OdfStylesDom & OdfContentDom As an intermediate step, I have moved the style access methods from the package layer OdfFileDom to OdfStylesDom and automatic style access to OdfStylesDom & OdfContentDom. As styles can never be found in meta.xml or settings.xml, but only in content.xml and styles.xml. NOTE: The reason automatic styles can be found in styles.xml is the existence of the header & footer content in the page style being part of the styles.xml file.
          Hide
          Svante Schubert added a comment -

          Hi Devin,

          IMHO we might review and push the first step of this issue already to the master to avoid larger patches in the future.

          If you are on the Chinese New Year Holiday, we might as well wait until your return or try to find another deputy.

          • Svante
          Show
          Svante Schubert added a comment - Hi Devin, IMHO we might review and push the first step of this issue already to the master to avoid larger patches in the future. If you are on the Chinese New Year Holiday, we might as well wait until your return or try to find another deputy. Svante
          Hide
          devin added a comment -

          Hi Svante,
          I like the new design, it's more clearly.
          I have reviewed and pushed the first step patch of this issue. You can continue your work now

          Devin

          Show
          devin added a comment - Hi Svante, I like the new design, it's more clearly. I have reviewed and pushed the first step patch of this issue. You can continue your work now Devin
          Hide
          DaLi Liu added a comment -

          Verified status of this issue
          not sure - I am not sure about this issue,maybe still leave to be opened.

          Show
          DaLi Liu added a comment - Verified status of this issue not sure - I am not sure about this issue,maybe still leave to be opened.

            People

            • Assignee:
              Svante Schubert
              Reporter:
              Svante Schubert
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:

                Development