OpenOffice::OODoc::XPath 2.027

OpenOffice::OODoc::XPath is a Low-level XML navigation in the documents. This module is a low-level class which uses OODoc::File (without inheriting anything from it) along with the classes defined in the XML::Twig module. Its a common basis for the other, more user- friendly, document-oriented modules. It uses XPath expressions in order to retrieve any document element (but it doesnt provide a full implementation of the XPath standard). In addition, while the most part of the provided methods are OpenDocument-aware, this module could be used against any other kind of XML documents, simply because it benefits from all the features of XML::Twig. Such a possibility may prove useful for applications that simultaneously process OpenDocument and non-OpenDocument XML files. The OpenOffice::OODoc::XPath class should not be explicitly used in the applications, because all its features are available in more user-friendly classes such as OODoc::Text, OODoc::Styles, OODoc::Image, OODoc::Document and OODoc::Meta. The present manual page is provided to describe the common methods and properties that are available with all these classes. This chapter can be skipped by programmers who are only interested in upper level methods provided by the OODoc::Text, ::Styles, ::Image and ::Meta modules. Understanding these modules is easier and using them requires less Perl and XML expertise. However, calling OODoc::XPath methods remains a good rescue option as it allows all kinds of operations on all types of XML elements contained in any OpenDocument-compliant file. OODoc::XPath is the common foundation of OODoc::Meta, OODoc::Text, OODoc::Styles and OODoc::Image. It contains the lowest layer of navigation services for XML documents and handles the link with OODoc::File for file access. Its primary role is as an interface with the XML::Twig API. In the present manual chapter, you will see "elements" often mentioned. When it says that a module expects a parameter or returns an element (either singly or as a list), it is referring to an XML element. It is important to distinguish elements from their content (elements being simply references to XML data structures). To read or modify the content of an element such as its text or XML attributes, use the accessors also available within OODoc::XPath. In most cases where XPath methods require a reference to an element as an argument, there are two ways of proceeding: - reference the element directly (obtained previously) - or give an XPath expression and a position, being a string and an integer respectively; for example, the pair (//office:body/text:p, 12) or (//text:p, 12) represents the thirteenth occurrence of the text:p element, i.e. the 13th paragraph (occurrences are numbered starting from 0). The second way requires the knowledge of an appropriate XPath expression (according the OOo/OpenDocument XML format specification). And a given XPath expression is not necessarily the same with an OpenDocument as in an OpenOffice.org document. So you should preferently use high level accessors (provided by derivative classes such as OODoc::Document) and avoid XPath hardcoding. However, you know you can at any time reach any element with XPath. Of course, you will never need to use XPath expressions in order to reach the most common text elements (such as paragraphs), because the OODoc::Text module provides more friendly accessors (for example, you will probably use the getParagraph() method and forget "//text:p"). Some methods accept both forms which means that if the first parameter is recognised as an element reference, the position does not need to be given. Therefore the number of arguments for certain OODoc::XPath methods can vary. For those who really want to access all areas there are also OODoc::XPath methods which allow unrestricted access to every element or XML attribute via an access path in XPath syntax. If you are into this kind of thing, we recommend you obtain good syntax reference manuals for XPath and OpenOffice.org and a supply of aspirin. Methods which may return several lines of text (e.g. getTextList) do so either in the form of an unique character string containing "n" separators or in table form. Unless otherwise stated, the word document in this chapter only refers to XML documents contained within OODoc::XPath objects and not, say, OpenOffice.org files (as an end user would use). Amongst the different methods which return elements, attributes or text, some are called getXxx, others selectXxx or findXxx. Read methods whose names start with "get" generally refer to an unfiltered object or list, whereas others return an object or list filtered according to a parameter value. In this latter case the search parameter is treated as a standard expression and not an exact value. This means that if the search criteria is "xyz", all text containing "xyz" will be considered a match. To restrict the search to text exactly equal to "xyz", use "^xyz$" as the search criteria (following Perl regular expression syntax). Several methods allow you to place copies of or references to elements (from other documents or from other positions in the same document) in any position in the current document. This offers powerful manoeuvrability but only if these placements conform with the destination positions context. For example, you can easily copy a paragraph from one document to another but only if you knowingly modify the paragraphs style attribute if that style is not already defined in the destination document. You can also copy the style but only if you are sure that this style is not already defined by another unknown style in the destination document (and so on). For advanced users familiar with the XML::Twig API, it might be interesting to know that all the objects called "elements" in the following chapters are objects of the OpenOffice::OODoc::Element class, which is an XML::Twig::Elt derivative. So all methods associated with this class are directly applicable to these elements, on top of the functionality described in this manual. However, the knowledge of XML::Twig is not mandatory. Important note: The applications should not explicitly work with this class. We recommend using OODoc::Meta and OODoc::Document (which are both OODoc::XPath derivatives). These two objects provide highest-level methods which are neater and more productive. Explicit use of OODoc::XPath methods (which sometimes require large numbers of parameters) should only be considered as a last resort in unexpected circumstances for access to any element or XML attribute not handled by more friendly methods. However, the present manual chapter could prove helpful because all the common features of OODoc::Meta and OODoc::Document are described here..

Requirements:	No special requirements
Platforms:	Linux
Keyword:	Access,  Document,  Element,  Elements,  Libraries,  Methods,  Oodoc,  Opendocument,  Openoffice,  Openofficeoodocxpath,  Such As,  Text,  Xml,  Xpath
Users rating:	0/10