Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
OODoc::Document(3)    User Contributed Perl Documentation   OODoc::Document(3)

       OpenOffice::OODoc::Document - Top level component for content and
       layout processing

	       # get an	ODF file handler
	       my $oofile = odfContainer("myfile.odt");
	       # connect a content-focused document interface
	       my $content = odfDocument
			       container => $oofile,
			       part => 'content'
	       # connect a style-focused document interface
	       my $styles = odfDocument
			       container => $oofile,
			       part => 'styles'
	       # process any content and style element
			       text => "An additional paragraph",
			       style =>	"BlueStyle"
			       parent => 'Text body',
			       family => 'paragraph',
			       properties =>
				       area	       => 'text',
				       'fo:color'      => rgb2oo('blue')
	       # commit	the changes using the file handler

       This module defines the top level Document class, which is a connector
       allowing	any kind of content and	presentation processing. It inherits
       from OODoc::XPath, OODoc::Text, OODoc::Styles and OODoc::Image.

       The most	usual instruction to get access	to any member of a document,
       with the	exception if the metadata (meta.xml) should be something like:

	       my $doc = odfDocument([options]);

       This constructor, if successful,	returns	an object that can be used
       (according to its "member" option) to process styles, images and	text.

       This module is designed simply to create	objects	which include all the
       functionality of	OODoc::Text, OODoc::Image, OODoc::Styles and
       OODoc::XPath (which should not be called	directly by applications).

       For example

	       my $styles = odfDocument(file =>	"source.odt", part => "styles");

       is generally better than

	       my styles = odfStyles(file => "source.odt");

       While OODoc::Document inherits all the methods and properties of	these
       classes,	its detailed documentation in essentially provided in the
       following manual	pages:

	       OpenOffice::OODoc::Text	       -> text content
	       OpenOffice::OODoc::Styles       -> style	& layout
	       OpenOffice::OODoc::Image	       -> graphic objects
	       OpenOffice::OODoc::XPath	       -> common features & low-level API

       For example, the	appendParagraph() and createStyle() methods used in
       the synopsis above are respectively described in
       OpenOffice::OODoc::Text and OpenOffice::OODoc::Styles.

       The present manual page only describes those methods (there are very
       few) which combine layout and content processing.

       Constructor : OpenOffice::OODoc::Document-_new(_parameters_)

	       Short Form: odfDocument(<parameters>) or	odfConnector(<parameters>)

	       See OpenOffice::OODoc::XPath->new (or odfXPath)

	       Returns an OpenDocument connector, available for	subsequent
	       access to any element of	a well-formed document.

	       Knowing that the	Document class is a derivative of the Text, Styles,
	       Image, and XPath	classes, ooDocument() implicitly executes the
	       corresponding constructors. So all the options of these constuctors
	       are available.

	       If no "part" parameter is given,	the member selected by default is
	       "content" (see OODoc::XPath). The most generally	used parts are
	       "content" and "styles".

       createImageStyle(name [,	options])

	       Creates a graphics style	which is immediately usable. With no
	       options,	this method applies to the new style a "reasonable" set	of
	       characteristics which match fairly closely the default image
	       presentation style in before any manual changes made
	       by the user. An application can set its own options in the same way
	       as createStyle in OODoc::Styles.

	       The aim of this method is to minimise the amount	of work	involved in
	       setting up the style, especially	when the default values	are close
	       enough, and bearing in mind that	an image must always be	associated
	       with a style to be displayed in a document.

	       The code	below shows a simple method of inserting an image into a
	       document, in this case linked to	a given	paragraph (see
	       createImageElement in OODoc::Image):

		   my $anchor  = $doc->getParagraph(4);
		   my $style   = $doc->createImageStyle("Photo");
		   my $image   = $doc->createImageElement
		       "Eiffel Tower",
		       style	       => "Photo",
		       attachment      => $anchor,
		       size	       => "4cm,	12cm",
		       import	       => "eiffel_tower.jpg"

	       The 'properties'	option is available for	customizations,	according
	       to the OpenDocument naming rules. For example, the following
	       instruction creates a style for centered	images:

		       'Centered Image',
		       properties =>
			       'style:horizontal-pos' => 'center'

       createTextStyle(name [, options])

	       Creates a text style which is immediately usable	and whose default
	       characteristics are the "Standard" style	in the document, even if no
	       options are given.

	       If the "Standard" style does not	exist, a "reasonable" style is
	       still created (this can happen in a document created from code and
	       not by an interactive office software).

	       An application can still	pass all the options it	wants in the same
	       way as createStyle in OODoc::Styles.


	       Removes the page	break from the given paragraph (before or after).

	       This method actually removes the	page break attribute from the
	       corresponding paragraph style. It does not remove paragraph styles
	       which may have been created to carry page breaks, so its	effects	are
	       not technically the reverse of setPageBreak(). Generally	speaking,
	       however,	this should not	be a problem. See setPageBreak() about the
	       logic of	handling page breaks.

       setPageBreak(paragraph [, options])

	       Places a	page break at the position of the given	paragraph. By
	       default,	the page break is placed before	the paragraph and no
	       changes are made	to the page style.

	       You can place the page break after the paragraph	using the option

		   position => 'after'

	       To use this method properly every time, you must	remember that a
	       page break is not a text	element, but a style applied before or
	       after the paragraph concerned. Putting a	page break in front of or
	       behind a	paragraph actually means adding	a "page	break before" or
	       "page break after" attribute to the paragraph's style. As always, a
	       page break cannot appear	in the text in keeping with the	principle
	       of separation of	content	and presentation. This however adds a
	       slight complication, in that all	paragraphs which use the same style
	       will have the page break. Otherwise, if the paragraph has a named
	       style (i.e. defined in styles.xml) and we are working in	the body of
	       the document (i.e. in content.xml), then	this method will not work
	       as it cannot access both	XML members at the same	time. There is
	       however a solution (the one used	by which consists
	       simply of creating a special style for the paragraph which takes	the
	       old paragraph style as a	parent and has only a page break attribute
	       (the old	paragraph style	is not modified). To do	this, all you need
	       is the option:

		   style => style_name

	       This option forces the creation of an automatic style with the given
	       name (make sure none other exists with the same name) and which will
	       only be used to carry the page break. Later on, you can of course
	       apply other characteristics to the style	using the updateStyle
	       method in OODoc::Styles,	but this is not	recommended. It	is better
	       not to use page break styles for	other purposes.	The nature of the
	       existing	paragraph style	dictates whether or not	you create a page
	       break style. If the paragraph style is a	named style (i.e. defined
	       in styles.xml and visible to the	user), you must	create a page break
	       style, but if it	already	has an automatic style you must	not. The
	       quite rare but most complicated scenario	is where the paragraph has
	       an automatic style shared by several paragraphs.	In this	case you
	       must then make copies of	the styles using the methods in

	       A page break can	allow you to change a page's style. You	can do this
	       with the	option:

		   page	=> page	style

	       in which	you give the following page's style (i.e. the logical name
	       of a master page. See OODoc::Styles). Remember that if the "page"
	       option is given,	the page break is forced before	the paragraph (the
	       "position" option does not work in this case).

       style(object [, style])

	       Returns the style name of a text	or graphics object. If the first
	       argument	is a "master page" (see	OODoc::Styles),	it even	returns	the
	       associated "page	layout".

	       Replaces	the object's style if a	style name is given as the second

       Developer/Maintainer: Jean-Marie	Gouarne


       Copyright 2004-2008 by Genicorp,	S.A. <>

       Initial English version of the reference	manual by Graeme A. Hunter

       License:	GNU Lesser General Public License v2.1

perl v5.32.1			  2008-09-16		    OODoc::Document(3)


Want to link to this manual page? Use this URL:

home | help