|o||position: The sequential zero-based position of the element among the set of elements matching the given tag; negative positions are counted backward from the end.|
|o||attribute: The name of an attribute used as a selection criterion; if this option is set, the value option is required.|
|o||value: the value of the selection attribute.|
|o||content: a search string (or a regexp) restricting the search space to the elements with matching content.|
attribute => outline level,
value => 1,
position => -4
Caution: the get_element method of odf_part is not the same as the get_element method of odf_element.
Note that such an instruction should not appear in a real application, knowing that get_paragraph(), introduced in ODF::lpOD::TextElement, does the job in a more user-friendly way.
Returns the full list of elements matching the given tag, whose tags match the given regexp.
The attribute and value options are allowed in order to restrict the search.
The next example returns the list of paragraphs whose style is Standard:
my @std_paragraphs = $context->get_elements(
attribute => style name,
value => Standard
The import_children() method allows the user to directly append elements coming from an external context. As an example, the following instruction appends appends all the children of a given $source element in the context of the calling $destination element:
In this example, both $destination and $source are elements. The source context may belong to the same document as the destination context, or not, so this method may be used for content replication across documents. Knowing that the imported elements are clones of the original ones, the source context is unchanged. The imported elements are appended at the end of the calling context in the same order as in the source context.
An optional filter may be specified as the 2nd argument, in order to import a particular kind of the source context only. So, the instruction below imports only the paragraphs of the source context (remember that text:p is the ODF tag for paragraphs):
The substitute_children() method, that takes the same arguments as import_children(), removes all the children of the calling element (if any), then imports the children of a source element. The following sequence replaces all the content of a given document body by the content of another document body (see ODF::lpOD::Document for details about get_body()):
$doc_destination->get_body->import_children( $doc_source->get_body );
As introduced in ODF::lpOD::Document, the odf_part handlers provide methods that automatically return high level elements that may be the preferred contexts in most cases. The most common one is the root element; its context is the whole document part. The body element, that is sometimes the same as the root one, is a bit more restricted in the document content part (it includes only the content objects, and excludes other objects such as style definitions). Both the root and the body may be got using the part-based get_root and get_body methods.
The following sequence, starting from the creation of a document instance, selects a part, then the root element of the part, than selects the list of table styles defined in the part:
my $doc = odf_document->get("/home/jmg/report.odt"); my $content = $doc->get_part(CONTENT); my $context = $content->get_root; my @table_styles = $context->get_element_list( style:style, attribute => family, value => table );
Note that the sequence above is shown in order to illustrate a principle but that it should not be needed in a real application, knowing that lpOD provides more user-friendly style retrieval tools.
The methods described in this section allows the user to insert elements (previously existing or not) as children of the calling element.
Insert the given odf_element at a given location, that is defined according to a position parameter. This parameter specifies the position of the element to be inserted (provided as the 1st argument) relatively to the calling element. The possible values are:
The WITHIN option splits the text content of the container in two parts and inserts the elements between them, at a given offset. So if position is WITHIN, the offset optional parameter is used. By default, if no offset argument is provided, or if the calling element doesnt contain any text, WITHIN produces the same result as FIRST_CHILD. The offset argument must be an integer; it specifies the position of the inserted child element within the text content of the calling element. A zero offset means that the element must be inserted before the 1st character. A negative offset value means that the insert position must be counted down from the end of the text, knowing that -1 is the position just before the last character. Of course, if the insertion must be done after the end of the text, the simplest way is to select LAST_CHILD instead of WITHIN.
o FIRST_CHILD: the odf_element will be the first child (default). o LAST_CHILD: the odf_element will be the last child. o NEXT_SIBLING: the odf_element will be inserted just after. o PREV_SIBLING: the odf_element will be inserted just before. o WITHIN: the odf_element will be inserted as a child within the text content; if position is WITHIN, then the offset parameter is required. o offset: specifies the position in the text of the context element where the new child element must be inserted (the position is zero-based). o before: the value of this option, if set, must be another child odf_element of the calling one; the new element will be inserted as the previous sibling of this child element. o after: like before, but the new element will be inserted after the value of this option. o PARENT: if this option is set, the calling element is moved and becomes the last child of the element given as PARENT. So the two instructions below are equivalent:
$e2->insert_element($e1, position => PARENT); $e1->insert_element($e2, position => LAST_CHILD);
Note that, with the PARENT option, if the first argument is an element that already belongs to a tree, its not really inserted: the calling element is just inserted inside it.
If before or after is provided, the other options are ignored. Of course, before and after are mutually exclusive.
The following example inserts a previously existing element between the 4th and the 5th characters of the text of the calling element:
$context->insert_element( $alien_element, position => WITHIN, offset => 4 );
The next example inserts a new empty paragraph before the last paragraph of the calling context:
my $last_p = $context->get_paragraph(position => -1); my $new_p = odf_paragraph->create(); $context->insert_element( $new_p, before => $last_p );
The sequence below (that uses features described in ODF::lpOD::TextElement), creates a protected section whose name is Conclusion and inserts it as the container of the last paragraph of the document:
$paragraph = $context->get_paragraph(position => -1); $paragraph->insert_element( odf_section->create("Conclusion", protected => TRUE), position => PARENT );
Like the first version of insert_element, but the argument is an arbitrary, application defined XML tag (i.e. technically a text string instead of a odf_element instance); in such a case a new element is created then inserted according to the same rules and options, with the exception of the PARENT option, that is supported only if the first argument is an existing element and not the tag of a element to be created.
As an example, the next instruction creates and inserts a foo:bar XML element at the end of the content of the calling element:
$context->insert_element(foo:bar, position => LAST_CHILD);
Like insert_element, but without options; appends the element as the last child of the calling element. So these tow lines are equivalent:
$context->insert_element($elt, position => LAST_CHILD); $context->append_element($elt);
The methods introduced in this section are accessors that get or set the own properties of the calling element. However, in some cases they may have indirect consequence on other elements.
Note that odf_element is a subclass of XML::Twig::Elt. So, beyond the methods specifically described below, programmers familiar with XML::Twig are allowed to directly (but cautiously) call any XML::Twig::Elt method from any element, if the methods described below dont meet all their needs.
Appends the calling element to another element provided as argument. The calling element becomes the last child of the given one.
Note that the two following instructions produce the same result:
Erases the text of an element and all its children. Beware that this method is overridden by some specialized element classes.
Returns a copy of the calling element, with all its attributes, its text, and its children elements. Allows the user to copy a high-level structured element (like a section or a table) as well as a single paragraph. The copy is a free element, that may be inserted somewhere in the same document as the prototype, or in another document.
Removes the calling element with all its descendants.
Deletes the attribute whose name is given in argument. Nothing is done if the attribute doesnt exist. The argument may be the exact XML name of the attribute, or an approximative name according to the same logic as get_attribute below.
Same as serialize() introduced later.
Returns the string value of the attribute having this name. The argument may be the exact XML name of the attribute. However, if a name without name space prefix is provided, the prefix is automatically supposed to be the same as the prefix of the context element. In addition, any white space or underscore character in the given name is interpreted as a -. As a consequence, some attributes may be designated without care of the exact XML syntax. As an example, assuming $p is a paragraph, the two instructions below are equivalent, knowing that the name space prefix of a paragraph is text:
$style = $p->get_attribute(text:style-name); $style = $p->get_attribute(style name);
The attribute values are returned in a character set that depends on the global configuration. See ODF::lpOD::Common for details about the character set handling.
Returns the odf_document object that owns the element, or undef if the calling element doesnt belong to a document.
If the element belongs to a document, returns the odf_part where its registered, or returns undef if the element is not in a document.
Returns the type of the odf_document object that owns the element, or undef if the calling element doesnt belong to a document.
Returns the parent of the calling element, if its included in a hierarchy. Returns undef if the calling element is free or if its at the top level of a hierarchy. May be used to check if the element is free or not. This method is an alias for XML::Twig::Elt::parent (see XML::Twig for details).
Returns the top level element of the document part that contains the calling element.
Returns the name of the style used by the calling element (this accessor makes sense for objects that may be displayed according to a layout). Returns undef if no style is used.
Returns the XML tag of the element with its name space prefix.
get_text(recursive => FALSE)
Returns the text contents of the element as a string. By default this method is not recursive (i.e. it just returns the own text of the element, not the text belonging to children and descendant elements). However, if the optional recursive parameter is provided and set to TRUE, then the method returns the concatenated contents of all the descendants of the given element.
Returns the URL if the element owns a hyperlink property, or undef otherwise.
Insert the calling element at a given location, depending on various options. The first argument must be any odf_element, that will be a position reference. The other arguments may be the same as insert_element. See insert_element for details, knowing that the two following instructions are equivalent:
$e1->insert($e2 [, options]); $e2->insert_element($e1 [, options]);
Returns an XML export of the calling element, allowing the lpOD applications to store and/or transmit particular pieces of documents, and not only full documents. The pretty or indent option is allowed, like with the serialize method of odf_part objects, described in ODF::lpOD::Document.
Note that this XML export is not affected by the content encoding/decoding mechanism that works for user content, so its character doesnt depend on the custom text output character set possibly selected through the set_output_charset() method introduced in ODF::lpOD::Common.
set_attribute(attribute => value)
Sets or changes an attribute of the calling element. The attribute is created if it didnt exist. If the provided value is undef, the attribute is deleted (if it didnt exist, nothing is done). The attribute name may be specified according to the same rules as with get_attribute.
About the character set of the input values, the same rules as with any text input apply; see the character set handling section in ODF::lpOD::Common.
Sets several attributes at a time. The attributes to change or create must be passed as a hash ref (like the hash ref returned by get_attributes). The attribute names may be provided in simplified form like with set_attribute.
Intended for debugging purposes, this method puts a XML comment before the calling element. This comment produces a <!--xyz--> tag, where xyz is the given text, in the XML output if the document is later serialized. Beware that such comments are not always preserved if the document is changed by an office application software.
set_child(tag, text, attributes)
Synonym of set_first_child() (see below).
set_first_child(tag, text, attributes)
Makes sure that the calling element contains at least one element with the given XML tag. If there is no compliant child, a new element is created with the given tag and inserted as the first child of the calling element. If one or more compliant child exist, the first one is selected and its text content (if any) is deleted.
The second argument (optional) is a string that becomes the new text content of the created or selected child. The remainder of the argument list, if any, is a hash specifying attribute/value pairs for this element.
The return value is the selected or created element.
set_last_child(tag, text, attributes)
Same as set_first_child() but, in case of creation, the new element is inserted as the last child. If compliant children already exist, the result is the same as set_first_child().
set_parent(tag, text, attributes)
Makes sure that the current element is a child of an element whose tag is specified by the first argument. If the calling element is free or if its immediate parent has not the given tag, a new element with the given tag is inserted as the same place of the calling element, that becomes the first child of the new element.
The return value is the new element.
The other arguments are the same as with set_first_child().
Changes or sets the style name of the calling object. Caution: a lot of ODF elements should not have any style, so dont use this accessor unless you know that the calling object needs a style.
Changes the XML tag of the calling element. Not for usual business; its a low level technical feature.
Sets the text content of the calling element, replacing any previous content. Example:
my $paragraph = $context->get_element(text:p, position => 15); $paragraph->set_text("The new content");
The character set of the provided string must comply to the currently active input character set (default is utf8). See the character set handling section in ODF::lpOD::Common if you get troubles about text encoding.
If set_text is called with an empty string, its effect is the same as clear.
Sets a URL attribute (xlink:href) with the argument.
The ODF::lpOD::Element package provides a associate_tag class method allowing developers to create custom subclasses and associate them to particular elements. The code example below defines CustomParagraph as a subclass of odf_pragraph (introduced in ODF::lpOD::TextElement) and specifies that every text:p XML element must be mapped to this new class instead of ODF::lpOD::Paragraph:
This extensibility mechanism must be used very cautiously if the specified tag is already associated with a lpOD class, knowing that a wrongly overridden method could produce destructive side effects.
Developer/Maintainer: Jean-Marie Gouarne <http://jean.marie.gouarne.online.fr> Contact: firstname.lastname@example.org
Copyright (c) 2010 Ars Aperta, Itaapy, Pierlis, Talend. Copyright (c) 2011 Jean-Marie Gouarne.
This work was sponsored by the Agence Nationale de la Recherche (<http://www.agence-nationale-recherche.fr>).
License: GPL v3, Apache v2.0 (see LICENSE).
|perl v5.20.3||LPOD::ELEMENT (3)||2012-03-28|