General

Components

Community

Development

TDF

Supported ODF Text Operations (or Changes)

Operations (or Changes) are used to transfer the user changes between editors. Operations are a prerequirement for collaborative working on a document.

Reason: No developer would ever send a zipped repository for exchanging work with other developers. Still we are doing this by zipping documents and sending those. To be able to dispatch only changes among collaborators new functionality had been added: Any OpenDocumend Text can now be transformed into an equivalent sequence of user changes (ODT/JSON). This list of user changes is like a batch of text operations, similar to a stream of actions the user would perform to create the document from top to the bottom. Foremost, new user changes can be merged into the existing document via JSON.

Test Demo You may test creating changes as JSON output transformation by commandline:

java -jar <ODFDOM_JAR> <ODT_INPUT>

You need version =>0.10.0 for this feature, version information is provided by:

java -jar <ODFDOM_JAR>

Table of contents
Supported ODF Text Operations (or Changes)
delete
move
addParagraph
splitParagraph
mergeParagraph
addText
addTab
addLineBreak
addField
updateField
addTable
addRows
addCells
addColumn
deleteColumns
addListStyle
addHeaderFooter
deleteHeaderFooterContent
addNote
documentLayout
addFontDecl
format
addStyle
changeStyle
deleteStyle
addDrawing

Most operations target specific text components (characters, paragraphs, tables, table cells, drawing objects, etc.) or ranges of text components. The following general rules apply for these operations:

  1. Single text components are addressed by a start property containing a Position array.
  2. Ranges of text components are addressed by a start and an end property, both containing a Position array. The range is inclusive, the text component addressed by end is part of the range. The end position must be equal to start or must follow start.

Note: In productive usage operation names and attributes should be shortened to limit bandwidth usage.

delete

Deletes a component or a range of related components.

Property Data Type Default Value Description
name String required “delete”
start TextPosition required The position of the first component that will be deleted.
end TextPosition value of start The position of the last component that will be deleted (closed range). if omitted, this operation addresses a single component.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note: Currently, only single components can be deleted, except for text ranges in a paragraph. A text range can include characters, fields, and drawing objects, but must be contained in a single paragraph.

The operation deletes only the addressed components. It will never delete any parent components, even if they are left empty (for example: after deleting the last row in a table, the empty table will remain in the document).

move

Moves a component or a range of related components to a new location.

Property Data Type Default Value Description
name String required “move”
start TextPosition required The position of the first component that will be moved.
end TextPosition value of start The position of the last component that will be moved (closed range). If omitted, this operation addresses a single component.
to TextPosition required The target position to move the selected components to.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note: Currently, only single drawing components can be moved. The property end will not be evaluated at all.

addParagraph

Inserts a new empty paragraph node into the document.

Property Data Type Default Value Description
name String required “addParagraph”
start ParagraphPosition required The position of the new paragraph. The paragraph will be inserted before a component that is currently located at this position.
attrs ParagraphAttributeSet {} Initial attribute set for the paragraph.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

splitParagraph

Splits the contents of an existing paragraph into two paragraphs.

Property Data Type Default Value Description
name String required “splitParagraph”
start CharacterPosition required The position of the first character (or other child component in the paragraph) that will be moved to the beginning of the new paragraph.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

mergeParagraph

Merges two consecutive paragraphs to a single paragraph.

Property Data Type Default Value Description
name String required “mergeParagraph”
start ParagraphPosition required The position of the paragraph, that will be merged with the following paragraph.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

The formatting attributes of the second paragraph will be lost, unless the leading paragraph is empty.

addText

Inserts new text into a paragraph.

Property Data Type Default Value Description
name String required “addText”
start CharacterPosition required The position where the new text will be inserted. The text will be inserted before the character that is currently located at this position.
text String required Text to be inserted into the specified paragraph at the specified position.
attrs CharacterAttributeSet {} Attribute set with additional character attributes (see note below).
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

addTab

Inserts a tabulator into a paragraph.

Property Data Type Default Value Description
name String required “addTab”
start CharacterPosition required The position where the new tabulator will be inserted. The tabulator will be inserted before the character that is currently located at this position.
attrs CharacterAttributeSet {} Attribute set with additional character attributes (see note below).
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

addLineBreak

Inserts a line break into a paragraph.

Property Data Type Default Value Description
name String required “addLineBreak”
start CharacterPosition required The position where the new line break will be inserted. The line break will be inserted before the character that is currently located at this position.
type Enum textWrapping One of “page”, “column” or “textWrapping”.
attrs CharacterAttributeSet {} Attribute set with additional character attributes (see note below).
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

addField

Inserts simple text field into a paragraph.

Property Data Type Default Value Description
name String required “addField”
start CharacterPosition required The position where the new field will be inserted. The field will be inserted before the character that is currently located at this position.
type String required TODO The field type as string.
representation String required The latest text representation of this field.
attrs CharacterAttributeSet {} Attribute set with additional character attributes (see note below).
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

updateField

Updates an already existing simple field.

Property Data Type Default Value Description
name String required “updateField”
start CharacterPosition required The position where the new field will be inserted. The field will be inserted before the character that is currently located at this position.
type String optional The field instruction.
representation String optional The attribute represents the field representation.
attrs CharacterAttributeSet {} Attribute set with additional character attributes (see note below).
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

addTable

Inserts a new table node into the document.

Property Data Type Default Value Description
name String required 'addTable'
start TablePosition required The position of the new table. The table will be inserted before a component that is currently located at this position.
attrs TableAttributeSet {} Initial attribute set for the table.
sizeExceeded Object none If set to an object, the table is too big to be displayed or edited. The object must contain the attributes rows and columns containing the original row count and column count of the table. To be used for importing documents only, NOT while editing documents.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

addRows

Inserts one or more new rows into a table.

Property Data Type Default Value Description Notes
name String required “addRows”
start TableRowPosition required The position of the new table row. The row will be inserted before a row that is currently located at this position.
count Integer 1 The number of rows that will be inserted.
insertDefaultCells Boolean false If true, empty cells will be inserted into the new row. The number of inserted cells will be equal to the number of columns in the table, as specified by the tableGrid attribute of the table. (1)
referenceRow Integer none If specified, the zero-based index of the existing row whose cells and their attributes will be cloned (but without the cell contents). (1)
attrs TableRowAttributeSet {} Initial attribute set for the table row.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

(1) The properties insertDefaultCells and referenceRow are mutually exclusive.

addCells

Inserts one or more new cells into a table row.

Property Data Type Default Value Description Notes
name String required “addCells”
start TableCellPosition required The position of the new cell. The cell will be inserted before a cell that is currently located at this position.
count Integer 1 The number of cells that will be inserted. (1)
attrs TableCellAttributeSet {} Initial attribute set for the cell.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

(1) The resulting number of cells in the row must not exceed the number of columns in the table, as specified by the tableGrid attribute of the table.

addColumn

Inserts cells for a new column into a table.

Property Data Type Default Value Description
name String required “addColumn”
start TablePosition required The position of the table the new column will be inserted into.
gridPosition Integer required Zero-based column index, according to the tableGrid attribute of the table.
tableGrid Integer[] required The complete array of relative widths for the entire table, containing the new entry for the new column. Will be set to the tableGrid attribute of the table.
insertMode Enum “before” "before”/"behind" The new cells will be inserted before/behind the existing cells.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

deleteColumns

Deletes the cells of a single column or multiple columns from a table.

Property Data Type Default Value Description
name String required “deleteColumns”
start TablePosition required The position of the table whose columns will be removed.
startGrid Integer required Zero-based index of the first column to be removed, according to the tableGrid attribute of the table.
endGrid Integer value of startGrid Zero-based index of the last column to be removed (closed range). If omitted, only one column will be removed.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

addListStyle

Inserts the definition of a list style into the document. An existing list style with the given name will be replaced.

Property Data Type Default Value Description
name String required “insertList”
listStyleId String required The unique identifier of this list style.
baseStyleId String The unique identifier of the abstract base list style for this list style.
listDefinition Object required Definitions for each numbering level, mapped by the property names listLevel0 to listLevel8. See next table for details.

List definitions per numbering level:

Property Data Type Default Value Description
textAlign Enum “left” One of “left”, “right”, “center”, or “justified”.
numberFormat Enum “none” One of “none”, “bullet”, “decimal”, “lowerRoman”, “upperRoman”, “lowerLetter”, or “upperLetter”.
levelStart Integer Start index of the level.
indentLeft Integer 0 Left indent of the numbered paragraph.
indentFirstLine Integer 0 First line indent, negative values represent hanging indents.
fontName String Font name, typically used for bullet symbols.
levelText String Formatting text of the label. Bullet symbol for bullet lists, level formats (custom string with one of the placeholders from ”%1” to ”%9”) for numbered lists.
textStyle String Identifier of the text style that the current numbering level shall be applied to.
paraStyle String Identifier of the paragraph style that the current numbering level shall be applied to.
levelPicBulletUri String ”” URI of the bullet picture.
tabStopPosition Integer Tabulator position, in 1/100 of millimeters.
color Color Color.AUTO Font color of the list label.

addHeaderFooter

Inserts Header or Footer in the document.

Property Data Type Default Value Description
name String required “addHeaderFooter”
id String required Unique name, which is used as a target for operations belonging to this element
type String required Should start with “header_” or “footer_” to identify is it header or footer

Note:

Currently, three types of header/footer are supported:

  1. “header_default” (“footer_default”) - default type, used if no other type is defined or available
  2. “header_first” (“footer_first”) - if defined, used only on first page in document. Has bigger priority then “_default”, and overwrites it.
  3. “header_even” (“footer_even”) - if defined, used on even pages, and overwrites “_default” type, as it has higher priority. With this type defined, on odd pages, “_default” type is used.

deleteHeaderFooterContent

Removes header or footer with passed id from the document.

Property Data Type Default Value Description
name String required “deletetHeaderFooter”
id String required Unique identifier, which is used to determine element to be deleted

addNote

Inserts a new comment into a paragraph.

Property Data Type Default Value Description
name String required “addNote”
start CharacterPosition required The position where the new comment will be inserted. The commentRang will be inserted before the character that is currently located at this position.
id String required Unique name, which is used as a target for operations belonging to this element
author String ”” The author of this comment.
uid String ”” The unique id of the author of this comment (used for picture and meta information of the author).
date String The creation date of this comment.
attrs CharacterAttributeSet {operations-formatting-attribute-sets.html#characterAttributeSet} Attribute set with additional character attributes

documentLayout

Sets default attributes for the document and for various formatting attribute types.

Property Type Default Value Description
name String required “setDocumentAttributes”
attrs DocumentAttributeSet required Application dependent attribute set with default attribute values for different attribute types.

addFontDecl

Inserts an extended description for a specific font which an be used for font substitution algorithms.

Property Type Default Value Description
name String required “addFontDecl”
fontName String required The font name.
attrs Object required The font description. Supports the following properties:

attrs (from above) support the following properties:

Property Type Default Value Description
altNames Array [] A list of alternative names for the font.
family String ”” The font family.
pitch Enum “variable” The font pitch. Either “fixed” or “variable”.
panose1 Array none The font typeface classification number. See http://en.wikipedia.org/wiki/PANOSE.

format

Sets or removes explicit formatting attributes at an arbitrary component in the text document.

Property Data Type Default Value Description
name String required “format”
start TextPosition required The position of the first component that will be formatted with the specified attributes.
end TextPosition value of start The position of the last component that will be formatted (closed range). If omitted, this operation addresses a single component.
attrs AttributeSet required The attribute set containing all attributes to be changed. Attributes with a value of null will be removed from the component. Attributes not contained in the set remain unmodified.
target String ”” specifies the target position, needs only to be used if document parts such as header or footer are addressed

Note:

addStyle

Inserts a new style with its formatting attributes into the document.

Property Type Default Value Description
name String required “addStyle”
type Enum required The main attribute type of the style sheet. The supported types are dependent on the application.
styleId String required The identifier of the new style sheet (must be unique inside the corresponding attribute type).
styleName String value of styleId The readable name of this style sheet. Must not be set for auto styles. An empty string is an allowed value.
attrs AttributeSet {} The attribute set with all attributes defined by the style sheet. Must support the attributes of the main attribute type of this operation, may support attributes of other types.
parent String none (no parent) The identifier of the parent style sheet that derives formatting attributes to this style sheet. Must be omitted, if the style sheet does not have a parent. Auto styles must refer to their parent style sheet.
uiPriority Integer 0 The priority of the style sheet used to order style sheet in the user interface. The lower the value the higher the priority.
default Boolean false Whether this style sheet is the default style sheet of the family. Only one style sheet per family can be the default style sheet.
hidden Boolean false Whether the style sheet is hidden in the user interface. Not used for auto-styles which are always hidden implicitly (see property auto).
custom Boolean false Whether the style sheet has been created at runtime while editing the document. Will be false for built-in style sheets. Not used for auto styles.

changeStyle

Changes the formatting attributes, and other properties of an existing style. Must not be used for auto styles.

Property Type Default Value Description
name String required “changeStyle”
type Enum required The main attribute type of the style sheet. The supported types are dependent on the application.
styleId String required The identifier of the style sheet to be changed. MUST NOT be an auto style (a style sheet with the property auto set to true, see operation addStyle).
other Other properties supported by the operation addStyle that will be changed in the style sheet. The properties default and auto cannot be changed.

deleteStyle

Removes a style from the document. Does not modify any attribute sets of elements that refer to the style sheet.

Property Type Default Value Description
name String required “deleteStyle”
type Enum required The main attribute type of the style sheet. The supported types are dependent on the application.
styleId String required The identifier of the style sheet to be removed. MUST NOT be an auto style (a style sheet with the property auto set to true, see operation addStyle).

addDrawing

Inserts a new drawing object into the document. This section describes the generic properties of the addDrawing operation.

Property Type Default Value Description
name String required “addDrawing”
start DrawingPosition required The position of the drawing object.
type Enum required The type of the drawing contents: see DrawingContentType below
attrs DrawingAttributeSet {} Initial attribute set for the drawing object.

DrawingContentType:

Impressum (Legal Info) | Privacy Policy (Datenschutzerklärung) | Statutes (non-binding English translation) - Satzung (binding German version) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Apache License, v2.0. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License v2.0. “LibreOffice” and “The Document Foundation” are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy. LibreOffice was based on OpenOffice.org.