Skip to content

Latest commit

 

History

History
1765 lines (1185 loc) · 43.5 KB

API.md

File metadata and controls

1765 lines (1185 loc) · 43.5 KB

Classes

Image

This class represents an image in a paragraph.

Meta

This class represents the metadata of a document.

It is used to set descriptive information about the document.

Color

This class represents a Color.

ImageStyle

This class represents the style of an image

ParagraphStyle

This class represents the style of a paragraph

StyleHelper

Utility class for dealing with styles.

TabStop

This class represents a tab stop.

Tab stops are used to align text in a paragraph. To become effective they must be set to the style of the respective paragraph.

Heading

This class represents a heading.

Hyperlink

This class represents a hyperlink in a paragraph.

List

This class represents a list. It can contain multiple list items.

ListItem

This class represents an item in a list.

Paragraph

This class represents a paragraph.

TextDocument

This class represents an empty ODF text document.

Image

This class represents an image in a paragraph.

Since: 0.3.0

new Image(path)

Creates an image

Parameters

  • path string
    Path to the image file that should be embedded

image.setStyle(style)

Sets the new style of this image.

Parameters

  • style IImageStyle
    The new style

Since: 0.5.0

image.getStyle() ⇒ IImageStyle

Returns the style of this image.

Return value
IImageStyle - The style of the image

Since: 0.5.0

image.toXml()

Meta

This class represents the metadata of a document.

It is used to set descriptive information about the document.

Since: 0.6.0

new Meta()

Creates a Meta instance that represents the metadata of a document.

Initializes the creation date with the current time stamp and sets the username of the currently effective user as initial creator.

Example

document.getMeta()
  .setCreator("Homer Simpson")
  .setTitle("Node.js meets ODF")
  .setSubject("ODF document creation")
  .addKeyword("Node.js")
  .addKeyword("Open Document Format")
  .setDescription("ODF text document created with Node.js powered by simple-odf")
  .setLanguage("en-US");

meta.setCreator(creator) ⇒ Meta

The setCreator() method sets the name of the person who last modified the document.

Parameters

  • creator string | undefined
    The name of the person who last modified a document or undefined to unset the creator

Return value
Meta - The Meta object

Example

const meta = new Meta();
meta.setCreator('Lisa Simpson'); // 'Lisa Simpson'
meta.setCreator(undefined);      // undefined

Since: 0.6.0

meta.getCreator() ⇒ string | undefined

The getCreator() method returns the name of the person who last modified the document.

Return value
string | undefined - The name of the person who last modified the document or undefined if the creator is not set

Example

const meta = new Meta();
meta.getCreator();               // undefined
meta.setCreator('Lisa Simpson');
meta.getCreator();               // 'Lisa Simpson'

Since: 0.6.0

meta.getCreationDate() ⇒ number

The getCreationDate() method returns the UTC timestamp specifying the date and time when a document was created.

The creation date is initialized with the UTC timestamp of the moment the Meta instance was created.

Return value
number - The UTC timestamp specifying the date and time when a document was created

Example

const meta = new Meta(); // 2020-04-01 12:00:00
meta.getCreationDate();  // 1585742400000

Since: 0.6.0

meta.setDate(date) ⇒ Meta

The setDate() method sets the date and time when the document was last modified.

Parameters

  • date number | undefined
    The UTC timestamp specifying the date and time when the document was last modified or undefined to unset the date

Return value
Meta - The Meta object

Example

const meta = new Meta();
meta.setDate(Date.now()); // 2020-07-23 13:37:00

Since: 0.6.0

meta.getDate() ⇒ number | undefined

The getDate() method returns the date and time when the document was last modified.

Return value
number | undefined - The UTC timestamp specifying the date and time when the document was last modified or undefined if the date is not set

Example

const meta = new Meta();
meta.getDate();           // undefined
meta.setDate(Date.now()); // 2020-07-23 13:37:00
meta.getDate();           // 1595511420000

Since: 0.6.0

meta.setDescription(description) ⇒ Meta

The setDescription() method sets the description of the document.

Parameters

  • description string | undefined
    The description of the document or undefined to unset the description

Return value
Meta - The Meta object

Example

const meta = new Meta();
meta.setDescription('Memoirs of the yellow man wearing blue trousers');

Since: 0.6.0

meta.getDescription() ⇒ string | undefined

The getDescription() method returns the description of the document.

Return value
string | undefined - The description of the document or undefined if the description is not set

Example

const meta = new Meta();
meta.getDescription(); // undefined
meta.setDescription('Memoirs of the yellow man wearing blue trousers');
meta.getDescription(); // 'Memoirs of the yellow man wearing blue trousers'

Since: 0.6.0

meta.getEditingCycles() ⇒ number

The getEditingCycles() method returns the number of times the document has been edited.

When the Meta instance is being created, the value is set to 1.

Return value
number - The number of times a document has been edited

Example

const meta = new Meta();
meta.getEditingCycles(); // 1

Since: 0.6.0

meta.getGenerator() ⇒ string

The getGenerator() method returns a string that identifies simple-odf as the OpenDocument producer that was used to create the document. The string matches the definition for user-agents as defined in RFC2616.

Return value
string - A string that identifies simple-odf as the OpenDocument producer of this document

Example

const meta = new Meta();
meta.getGenerator(); // simple-odf/0.6.0

Since: 0.6.0

meta.setInitialCreator(initialCreator) ⇒ Meta

The setInitialCreator() method sets the name of the initial creator of the document.

The initial creator is initialized with the username of the currently effective user.

Parameters

  • initialCreator string | undefined
    The name of the initial creator of the document or undefined to unset the initial creator

Return value
Meta - The Meta object

Example

const meta = new Meta();                // 'Homer Simpson'
meta.setInitialCreator('Bart Simpson'); // 'Bart Simpson'
meta.setInitialCreator(undefined);      // undefined

Since: 0.6.0

meta.getInitialCreator() ⇒ string | undefined

The getInitialCreator() method returns the name of the initial creator of the document.

Return value
string | undefined - The name of the initial creator of the document or undefined if the initial creator is not set

Example

const meta = new Meta();
meta.getInitialCreator();               // 'Homer Simpson'
meta.setInitialCreator('Bart Simpson');
meta.getInitialCreator();               // 'Bart Simpson'

Since: 0.6.0

meta.addKeyword(keyword) ⇒ Meta

The addKeyword() method adds a keyword pertaining to a document to the end of the keyword list. If the given string includes comma characters, the string will be split and added as multiple key words.

Parameters

  • keyword string
    The keyword to add to the end of the keyword list

Return value
Meta - The Meta object

Example

const meta = new Meta();                       // []
meta.addKeyword('memoirs');                    // ['memoirs']
meta.addKeyword('Simpson,family,Springfield'); // ['memoirs', 'Simpson', 'family', 'Springfield']

Since: 0.6.0

meta.getKeywords() ⇒ Array.<string>

The getKeywords() method returns a new Array object that contains the keywords of the document.

Return value
Array.<string> - A new Array object that contains the keywords of the document

Example

const meta = new Meta();
meta.getKeywords();                     // []
meta.addKeyword('Simpson,Springfield');
meta.getKeywords();                     // ['Simpson', 'Springfield']

Since: 0.6.0

meta.removeKeyword(keyword) ⇒ Meta

The removeKeyword() method removes the specified keyword from the keyword list.

Parameters

  • keyword string
    The keyword to remove from the keyword list

Return value
Meta - The Meta object

Example

const meta = new Meta();
meta.addKeyword('Simpson,Springfield'); // ['Simpson', 'Springfield']
meta.removeKeyword('Simpson');          // ['Springfield']

Since: 0.6.0

meta.clearKeywords() ⇒ Meta

The clearKeywords() method removes all elements from the keyword list.

Return value
Meta - The Meta object

Example

const meta = new Meta();
meta.addKeyword('Simpson,Springfield'); // ['Simpson', 'Springfield']
meta.clearKeywords();                   // []

Since: 0.6.0

meta.setLanguage(language) ⇒ Meta

The setLanguage() method sets default language of the document. A language is a natural language identifier as defined by RFC5646. If an illegal value is provided, the value will be ignored.

Parameters

  • language string | undefined
    The default language of the document or undefined to unset the default language

Return value
Meta - The Meta object

Example

const meta = new Meta();     // undefined
meta.setLanguage('en-US');   // 'en-US'
meta.setLanguage('illegal'); // 'en-US'

Since: 0.6.0

meta.getLanguage() ⇒ string | undefined

The getLanguage() method returns the default language of the document.

Return value
string | undefined - The default language of the document or undefined if the default language is not set

Example

const meta = new Meta();
meta.getLanguage();        // undefined
meta.setLanguage('en-US');
meta.getLanguage();        // 'en-US'

Since: 0.6.0

meta.setPrintDate(printDate) ⇒ Meta

The setPrintDate() method sets the date and time when the document was last printed.

Parameters

  • printDate number | undefined
    The UTC timestamp specifying the date and time when the document was last printed or undefined to unset the print date

Return value
Meta - The Meta object

Example

const meta = new Meta();
meta.setPrintDate(Date.now()); // 2020-07-23 13:37:00

Since: 0.6.0

meta.getPrintDate() ⇒ number | undefined

The getPrintDate() method returns the date and time when the document was last printed.

Return value
number | undefined - The UTC timestamp specifying the date and time when the document was last printed or undefined if the print date is not set

Example

const meta = new Meta();
meta.getPrintDate();           // undefined
meta.setPrintDate(Date.now()); // 2020-07-23 13:37:00
meta.getPrintDate();           // 1595511420000

Since: 0.6.0

meta.setPrintedBy(printedBy) ⇒ Meta

The setPrintedBy() method sets the name of the last person who printed the document.

Parameters

  • printedBy string | undefined
    The name of the last person who printed the document or undefined to unset the name of the person

Return value
Meta - The Meta object

Example

const meta = new Meta();
meta.setPrintedBy('Marge Simpson'); // 'Marge Simpson'
meta.setPrintedBy(undefined);       // undefined

Since: 0.6.0

meta.getPrintedBy() ⇒ string | undefined

The getPrintedBy() method returns the name of the last person who printed the document.

Return value
string | undefined - The name of the last person who printed the document or undefined if the name of the person is not set

Example

const meta = new Meta();
meta.getPrintedBy();                // undefined
meta.setPrintedBy('Marge Simpson');
meta.getPrintedBy();                // 'Marge Simpson'

Since: 0.6.0

meta.setSubject(subject) ⇒ Meta

The setSubject() method sets the subject of the document.

Parameters

  • subject string | undefined
    The subject of the document or undefined to unset the subject

Return value
Meta - The Meta object

Example

const meta = new Meta();
meta.setSubject('Simpsons'); // 'Simpsons'
meta.setSubject(undefined);  // undefined

Since: 0.6.0

meta.getSubject() ⇒ string | undefined

The getSubject() method returns the subject of the document.

Return value
string | undefined - The subject of the document or undefined if the subject is not set

Example

const meta = new Meta();
meta.getSubject();           // undefined
meta.setSubject('Simpsons');
meta.getSubject();           // 'Simpsons'

Since: 0.6.0

meta.setTitle(title) ⇒ Meta

The setTitle() method sets the title of the document.

Parameters

  • title string | undefined
    The title of the document or undefined to unset the title

Return value
Meta - The Meta object

Example

const meta = new Meta();
meta.setTitle('Memoirs of Homer Simpson'); // 'Memoirs of Homer Simpson'
meta.setTitle(undefined);                  // undefined

Since: 0.6.0

meta.getTitle() ⇒ string | undefined

The getTitle() method returns the title of the document.

Return value
string | undefined - The title of the document or undefined if the title is not set

Example

const meta = new Meta();
meta.getTitle();                           // undefined
meta.setTitle('Memoirs of Homer Simpson');
meta.getTitle();                           // 'Memoirs of Homer Simpson'

Since: 0.6.0

meta.toXml(document, root)

Transforms the text style into Open Document Format.

Parameters

  • document Document
    The XML document
  • root Element
    The root node in the DOM

Since: 0.6.0

Color

This class represents a Color.

Since: 0.4.0

new Color(red, green, blue)

Creates a new color with the specified channel values.

Parameters

  • red number
    The red channel of the color
  • green number
    The green channel of the color
  • blue number
    The blue channel of the color

color.toHex() ⇒ string

The toHex() method returns a string representing the color as hex string.

Return value
string - A hex string representing the color

Since: 0.4.0

Color.fromHex(value) ⇒ Color | undefined

The Color.fromHex() method parses a string argument and returns a color. The string is expected to be in #rrggbb or rrggbb format.

Parameters

  • value string
    The value you want to parse

Return value
Color | undefined - A color parsed from the given value. If the value cannot be converted to a color, undefined is returned.

Since: 0.4.0

Color.fromRgb(red, green, blue) ⇒ Color | undefined

The Color.fromRgb() method returns a color with the channel arguments.

Parameters

  • red number
    The red channel of the color with a range of 0...255
  • green number
    The green channel of the color with a range of 0...255
  • blue number
    The blue channel of the color with a range of 0...255

Return value
Color | undefined - A color parsed from the given value. If any channel is outside the allowable range, undefined is returned.

Since: 0.4.0

ImageStyle

This class represents the style of an image

Since: 0.5.0

new ImageStyle()

Constructor.

imageStyle.setAnchorType()

imageStyle.getAnchorType()

imageStyle.setHeight(height)

Sets the target height of the image.

Parameters

  • height number
    The target height of the image in millimeter

Since: 0.5.0

imageStyle.getHeight() ⇒ number | undefined

Returns the target height of the image or undefined if no height was set.

Return value
number | undefined - The target height of the image in millimeter or undefined if no height was set

Since: 0.5.0

imageStyle.setWidth(width)

Sets the target width of the image.

Parameters

  • width number
    The target width of the image in millimeter

Since: 0.5.0

imageStyle.getWidth() ⇒ number | undefined

Returns the target width of the image or undefined if no width was set.

Return value
number | undefined - The target width of the image in millimeter or undefined if no width was set

Since: 0.5.0

imageStyle.setSize(width, height)

Sets the target size of the image.

Parameters

  • width number
    The target width of the image in millimeter
  • height number
    The target height of the image in millimeter

Since: 0.5.0

imageStyle.toXml()

ParagraphStyle

This class represents the style of a paragraph

Since: 0.4.0

new ParagraphStyle()

Constructor.

paragraphStyle.setColor()

paragraphStyle.getColor()

paragraphStyle.setFontName()

paragraphStyle.getFontName()

paragraphStyle.setFontSize()

paragraphStyle.getFontSize()

paragraphStyle.setTextTransformation()

paragraphStyle.getTextTransformation()

paragraphStyle.setTypeface()

paragraphStyle.getTypeface()

paragraphStyle.setHorizontalAlignment()

paragraphStyle.getHorizontalAlignment()

paragraphStyle.setPageBreakBefore()

paragraphStyle.setKeepTogether()

paragraphStyle.getTabStops()

paragraphStyle.clearTabStops()

paragraphStyle.toXml()

StyleHelper

Utility class for dealing with styles.

Since: 0.4.0

StyleHelper.getAutomaticStylesElement(document) ⇒ Element

Returns the automatic-styles element of the document. If there is no such element yet, it will be created.

Parameters

  • document Document
    The XML document

Return value
Element - The documents automatic-styles element

Since: 0.4.0

TabStop

This class represents a tab stop.

Tab stops are used to align text in a paragraph. To become effective they must be set to the style of the respective paragraph.

Since: 0.3.0

new TabStop([position], [type])

Creates a tab stop to be set to the style of a paragraph.

Parameters

  • [position] number
    The position of the tab stop in centimeters relative to the left margin. If a negative value is given, the position will be set to 0.
  • [type] TabStopType
    The type of the tab stop. Defaults to TabStopType.Left.

Example

// creates a right aligned tab stop with a distance of 4 cm from the left margin
const tabStop4 = new TabStop(4, TabStopType.Right);
paragraph.getStyle().addTabStop(tabStop4);

tabStop.setPosition(position)

Sets the position of this tab stop.

Parameters

  • position number
    The position of the tab stop in centimeters relative to the left margin. If a negative value is given, the position will be set to 0.

Since: 0.3.0

tabStop.getPosition() ⇒ number

Returns the position of this tab stop.

Return value
number - The position of this tab stop in centimeters

Since: 0.3.0

tabStop.setType(type)

Sets the type of this tab stop.

Parameters

  • type TabStopType
    The type of the tab stop

Since: 0.3.0

tabStop.getType() ⇒ TabStopType

Returns the type of this tab stop.

Return value
TabStopType - The type of this tab stop

Since: 0.3.0

tabStop.toXml(document, parent)

Transforms the tab stop into Open Document Format.

Parameters

  • document Document
    The XML document
  • parent Element
    The parent node in the DOM (style:tab-stops)

Since: 0.3.0

Heading

This class represents a heading.

Since: 0.1.0

new Heading([text], [level])

Creates a heading

Parameters

  • [text] string
    The text content of the heading
  • [level] number
    The heading level; defaults to 1 if omitted

heading.setLevel(level)

Sets the level of this heading.

Parameters

  • level number
    The heading level

Since: 0.1.0

heading.getLevel() ⇒ number

Returns the level of this heading.

Return value
number - The heading level

Since: 0.1.0

heading.createElement()

Hyperlink

This class represents a hyperlink in a paragraph.

Since: 0.3.0

new Hyperlink(text, uri)

Creates a hyperlink

Parameters

  • text string
    The text content of the hyperlink
  • uri string
    The target URI of the hyperlink

hyperlink.setURI(uri)

Sets the target URI for this hyperlink.

Parameters

  • uri string
    The new target URI

Since: 0.3.0

hyperlink.getURI() ⇒ string

Returns the target URI of this hyperlink.

Return value
string - The target URI

Since: 0.3.0

hyperlink.toXml()

List

This class represents a list. It can contain multiple list items.

Since: 0.2.0

new List()

Creates a list

list.addItem([item]) ⇒ ListItem

Adds a new list item with the specified text or adds the specified item to the list.

Parameters

  • [item] string | ListItem
    The text content of the new item or the item to add

Return value
ListItem - The newly added list item

Since: 0.2.0

list.insertItem(position, item) ⇒ ListItem

Inserts a new list item with the specified text or inserts the specified item at the specified position. The item is inserted before the item at the specified position.

Parameters

  • position number
    The index at which to insert the list item (starting from 0).
  • item string | ListItem
    The text content of the new item or the item to insert

Return value
ListItem - The newly added list item

Since: 0.2.0

list.getItem(position) ⇒ ListItem | undefined

Returns the item at the specified position in this list. If an invalid position is given, undefined is returned.

Parameters

  • position number
    The index of the requested the list item (starting from 0).

Return value
ListItem | undefined - The list item at the specified position or undefined if there is no list item at the specified position

Since: 0.2.0

list.getItems() ⇒ Array.<ListItem>

Returns all list items.

Return value
Array.<ListItem> - A copy of the list of list items

Since: 0.2.0

list.removeItemAt(position) ⇒ ListItem | undefined

Removes the list item from the specified position.

Parameters

  • position number
    The index of the list item to remove (starting from 0).

Return value
ListItem | undefined - The removed list item or undefined if there is no list item at the specified position

Since: 0.2.0

list.clear()

Removes all items from this list.

Since: 0.2.0

list.size() ⇒ number

Returns the number of items in this list.

Return value
number - The number of items in this list

Since: 0.2.0

list.toXml()

ListItem

This class represents an item in a list.

Since: 0.2.0

new ListItem([text])

Creates a list item

Parameters

  • [text] string
    The text content of the list item

listItem.toXml()

Paragraph

This class represents a paragraph.

Since: 0.1.0

new Paragraph([text])

Creates a paragraph

Parameters

  • [text] string
    The text content of the paragraph

paragraph.addText(text)

Appends the specified text to the end of this paragraph.

Parameters

  • text string
    The additional text content

Since: 0.1.0

paragraph.getText() ⇒ string

Returns the text content of this paragraph. Note: This will only return the text; other elements and markup will be omitted.

Return value
string - The text content of this paragraph

Since: 0.1.0

paragraph.setText(text)

Sets the text content of this paragraph. Note: This will replace any existing content of the paragraph.

Parameters

  • text string
    The new text content

Since: 0.1.0

paragraph.addHyperlink(text, uri) ⇒ Hyperlink

Appends the specified text as hyperlink to the end of this paragraph.

Parameters

  • text string
    The text content of the hyperlink
  • uri string
    The target URI of the hyperlink

Return value
Hyperlink - The newly added hyperlink

Since: 0.3.0

paragraph.addImage(path) ⇒ Image

Appends the image of the denoted path to the end of this paragraph. The current paragraph will be set as anchor for the image.

Parameters

  • path string
    The path to the image file

Return value
Image - The newly added image

Since: 0.3.0

paragraph.setStyle(style)

Sets the new style of this paragraph. To reset the style, undefined must be given.

Parameters

  • style IParagraphStyle | undefined
    The new style or undefined to reset the style

Since: 0.3.0

paragraph.getStyle() ⇒ IParagraphStyle | undefined

Returns the style of this paragraph.

Return value
IParagraphStyle | undefined - The style of the paragraph or undefined if no style was set

Since: 0.3.0

paragraph.createElement(document) ⇒ Element

Creates the paragraph element.

Parameters

  • document Document
    The XML document

Return value
Element - The DOM element representing this paragraph

Since: 0.1.0

paragraph.toXml()

TextDocument

This class represents an empty ODF text document.

Since: 0.1.0

textDocument.getMeta() ⇒ Meta

The getMeta() method returns the metadata of the document.

Return value
Meta - An object holding the metadata of the document

See: Meta
Example

document.getMeta().setCreator('Lisa Simpson');

Since: 0.6.0

textDocument.declareFont(name, fontFamily, fontPitch)

Declares a font to be used in the document.

Note: There is no check whether the font exists. In order to be displayed properly, the font must be present on the target system.

Parameters

  • name string
    The name of the font; this name must be set to a ParagraphStyle
  • fontFamily string
    The name of the font family
  • fontPitch FontPitch
    The ptich of the fonr

Since: 0.4.0

textDocument.addHeading([text], [level]) ⇒ Heading

Adds a heading at the end of the document. If a text is given, this will be set as text content of the heading.

Parameters

  • [text] string
    The text content of the heading
  • [level] number = 1
    The heading level; defaults to 1 if omitted

Return value
Heading - The newly added heading

Since: 0.1.0

textDocument.addList() ⇒ List

Adds an empty list at the end of the document.

Return value
List - The newly added list

Since: 0.2.0

textDocument.addParagraph([text]) ⇒ Paragraph

Adds a paragraph at the end of the document. If a text is given, this will be set as text content of the paragraph.

Parameters

  • [text] string
    The text content of the paragraph

Return value
Paragraph - The newly added paragraph

Since: 0.1.0

textDocument.saveFlat(filePath) ⇒ Promise.<void>

Saves the document in flat open document xml format.

Parameters

  • filePath string
    The file path to write to

Since: 0.1.0

textDocument.toString() ⇒ string

Deprecated

Returns the string representation of this document in flat open document xml format.

Return value
string - The string representation of this document

Since: 0.1.0

textDocument.toXml()