XML Publisher Templates by Example

Learn how to create reporting layout formats easily and simply using Oracle XML Publisher. by Tim Dexter (tim.dexter@oracle.com) Oracle XML Publisher provides a ne reportin! paradi!m in the mar"et

place. Traditional reportin! tools hold the datasource (#uery)$ layout and translation in a sin!le executable %ile. XML Publisher ta"es the approach o% splittin! the three components apart. This ma"es reportin! much more %lexible and easier to maintain. &ith the layout no independent o% the data this allo s 'T departments to

start consolidatin! their datsources into %e er extraction pro!rams. (o lon!er do they have to have one #uery$ one layout. ) sin!le data extraction can no support multiple layouts allo in! users to apply various layouts to a sin!le datasource and !enerate completely di%%erent report outputs. The 'T department can also %ree itsel% %rom the perrenial problem o% havin! to build and maintain layouts %ormats. The layout templates can be built usin! %amiliar des"top tools such as M*&ord or )dobe )crobat. These can be built by %unctional users process is %aster, Developin! data extraction pro!rams - the 'T department can use various methods %or extractin! data one o% the %astest bein! the XML Publisher data en!ine. )t its most basic$ !ive it *.L and it ill return XML data. ith a little practice. Or!ani+ations can see hu!e savin!s in time and e%%ort in !ettin! reports to their end users. )t every sta!e the

/uildin! Layouts - no lon!er a tedious thread o% email bet een business analyst and developer to !et the layout 0ust ri!ht. The analyst "no s the re#uirements intimately and can build the layout him or hersel% and !et it ri!ht %irst time. Then pass to the developer %or deployment to the server.

Deployin! 1 hether you2re usin! 3/* or Online or you have plu!!ed XML Publisher into your o n application deployment is simple. There are options to deploy datasources and templates to either the %ilesystem or the database.

Background / Overvie
This article ill introduce the 4T5 template %ormats that can be used ith

XML Publisher. 't ill ta"e you %rom a simple listin! report to a complete report layout inlcudin! headers$ %ooters$ ima!es$ master1detail relationships and conditional %ormattin! all %rom the com%ort o% an M*&ord inter%ace.

Preliminary !etup
To aid in the buildin! o% 4T5 templates XML Publisher provides the XML Publisher Template /uilder %or M*&ord. Prior to startin! the examples you should do nload this plu!in and install it. This is available %rom metalin"$ the latest version is 6.6 and can be %ound by do nloadin! patch 7689:;6. )lternatively you can do nload %rom the Oracle *tore site by searchin! %or XML Publisher. <ou associated ill also need to do nload and unpac" the +ip %ile ith this article. ill %ind a ne tool bar

Once you have sucess%ully installed the plu!in you and menu entry in your M*&ord install.

)ll o% the %ollo in! report %ormats are based on 3mployeeListin!.xml,

<?xml version="1.0"?> <ROWSET> <ROW num="1"> <EMPNO>100</EMPNO> <ENAME> o !lo""s</ENAME> < O!>#$ER%</ O!> <SA$>100</SA$> <&NAME>A##O'NT(N)</&NAME> </ROW> <ROW num="*"> <EMPNO>100</EMPNO>

<ENAME> +ne &oe</ENAME> < O!>#$ER%</ O!> <SA$>100</SA$> </ROW> ... </ROWSET>

)s you can see the data is sho in! employee details and the department they in. There is no master1detail relationship in the data$ it is completely =%lat2.

or"

"our #irst Template $ !imple Employee %etail

The simplest output e could !enerate ould be to sho an employee and their ill !et

details. *o open M*&ord and use the Data > Load XML data option on the Template /uilder toolbar and select the XML %ile - 3mployeeListin!.xml. <ou con%irmation that the data has loaded success%ully. (o option$ this use the 'nsert > 5ield ill open a dialo! box sho in! the available %ields %rom the data.

#igure &' (nsert )ield dialog

(otice the list o% available %ields in the dialo!. &e can use this dialo! to enter these %ields into our report. *elect the insertion point in the &ord document and then clic" on a %ield and then use the 'nsert button. ?sin! this method build a layout similar to the one belo add the boiler plate text as you !o.

#igure *' !imple Employee %etail Template

<ou2ll notice that as you use the insert button that Microso%t 5orm 5ields are bein! inserted into the document. This is the ob0ect that XML Publisher uses to store the mappin! to the XML element in the data. This is done so that a user can easily dra! and drop report ob0ects around the document havin! to and you2ll !et the 5ield Property dialo!$ no ithout orry about the =nuts and bolts2 o% the report. Double clic" on a %ield clic" on the @elp button and

you2ll see the method XML Publisher uses to map to the data elements.

#igure +' #orm #ield %ialog

(otice in this case

e see AB3MP(OB>$ this tells the XML Publisher

template parser that the 3MP(O element value should be inserted into the %inal document usin! =AB2 and =B>2 to delimit the element mappin!. (o select Previe > PD5 %rom the toolbar$ the template builder ill prompt ill

you to save template as an 4T5 %ormat. Once this is done the template be applied to the data. <ou2ll !et somethin! li"e,

#igure ,' !imple Employee %etail Output

Creat$ so no

you have the %irst employee and their details but

here are the e2ll add

others %rom the XML data. This template lac"s the commands to loop over the employees and it there%ore only sho s the %irst record. (ext those commands. (3mployeeListin!9.rt%)

-et your employees listing

*o e ant to loop over the employees and !et all o% their data into the use

output. Co bac" to M* &ord close your ori!inal document and create a ne one and load the data a!ain$ alternatively 0ust delete the content. (o the toolbar and select 'nsert > TableD5orm. <ou2ll be presented %ollo in! dialo!$ notice it is made up o% three re!ions. Le%t Pane - this sho s the source XML tree Eenter Pane - this is the tar!et or document pane 4i!ht Pane - this has the Property palette and Previe re!ion ith the

#igure .' (nsert Table/#orm dialog

This dialo! is very po er%ul and allo s you to build either small parts o% a report layout or the complete report structure in one !o. To create the loopin! structure use your mouse and clic" on the =4o 2 node$ hold it do n and dra! it to the center pane and let !o. ) popup ill as" i% you ant to drop a =*in!le tree structure (ode2 or =)ll (odes2$ select =)ll (odes2. <ou2ll no ith the =4o 2 element at the top. *elect this node see the properties palette and previe re!ion %ill. see a ne

ith your mouse and you

#igure /' Properties and Previe

Try chan!in! the =*tyle2 property and then clic"in! on the treeF you can speci%y =Table2$ =5orm2 and =5ree 5orm2. <ou2ll see the previe and use the delete "ey to remove it %rom the tree. (o builder re!ion update based on your choices. *elect =Table2 and then hi!hli!ht the =@num2 value hit OG. The template ill then insert the necessary structures into your template.

#igure 0' (nserted table structure

(otice the data is no

presented in a table$ there are t o ro s created$ one ill

%or the column headers and the second %or the %orm %ields. The builder re!ular %orm %ields are still there but you

put in some de%ault boilerplate based on the XML data element names. The ill also notice t o extra %ields =52 and =32. These contain the loopin! commands, 5 1 AB%or1each,4O&B> 1 4O& is the !roup in the XML and this command is sayin!$ H%or each member o% the 4O& !roup carry out the %ollo in! ie enter the %ields 3MP(O$ 3()M3$ etc 3 1 ABend %or1eachB> 1 this command closes the loop.

(o

previe

this template in the %ormat o% your choice$ you2ll see the

%ollo in!,

*o no

e are seein! all o% the employees details in a table. *o e

e no

have a basic listin! report but lets say

anted to !roup the employees by

their department or 0ob. (3mployeeListin!I.rt%)

1egroup your employees

Our data does not re%lect this !roupin! but the template builder can help us to !roup the data in the template despite not havin! the supportin! structure in the data. This %eature is extremely po er%ul$ a !eneric =%lat2 extract can support many layout %ormats allo in! users to decide ho the data. 3ither create a ne document or delete the existin! content. &e are !oin! to ill use the they ant to see

create a report that sho s the employees by department. &e center pane i% needed.

same dialo! as be%ore$ so open it up$ 'nsert > TableD5orm and clear the

Elic" and hold on the 4O& node and dra! to the center pane and =Drop )ll2$ remove the @num node. @i!hli!ht the 4O& node and then on the Croupin! property drop do n select =D()M32 i.e. the department name. (o on the 4O& node and you2ll see the tree has been updated. clic" bac"

#igure 2' 1egrouping dialog

<ou2ll notice that the document tree has been updated to sho e have created. 'n its current state the employee data e ill be a nested table

the !roupin!

ill have a Table in Table report ie ithin a department table. &e are node and chan!e the *tyle clic" OG and

!oin! to have a simpler %ormat. *elect the 4o clue as to the nature o% ho that node

property to =5ree 5orm2$ notice the icon next to the node is updated to !ive a ill be rendered. (o you should !et template li"e,

#igure 3' 1egrouping template

<ou can see the %amiliar table and its %ields but

e no

have t o extra %ields,

C 1 AB%or1each1!roup,4O&F.DD()M3B>ABsort,D()M3FJascendin!JFdata1 typeKJtextJB> 1 this command is speci%yin! that the 4O& !roup should be then !rouped by D()M3. There is also a sort command to sort by the D()M3 as ell. The sort criteria can be chan!ed usin! the property palette. The template ill no loop over this ne ly created !roup. D()M3 !roup.

3 1 ABend %or1each1!roupB> 1 this closes out the ne

There has been another update$ the ori!inal =52 %ield no

contains$ AB%or1

each,current1!roup()B>$ this is sayin! loop over the current !roup i.e. the

D()M3 !roup somethin! li"e,

e created above. Try previe in! this template and you2ll !et

#igure &4' -rouping by department output

&e have no

created a report that sho s our employees by their

department. &e could easily !roup them by their 0ob titles$ or even !roup by department and then by 0ob title.

Totals and tallies

*o no e have imposed some !roupin! on our data e ant to "no ho e ant to add some

sub totals$ lets say department and ho the XML data but

much the salary cost is in each e are !oin!

many employees are in each. These values are not in e can create them in the template. 5or this

to !o bac" to the insert %ield dialo!. Lets insert the employee count %irst$ move the cursor to 0ust a%ter the D()M3 %ield$ then use the toolbar 'nsert > 5ield. *elect the 3MP(O %ield and then select =count2 %rom the Ealculation drop do n box. 5inally insert. e need to chec" the Croupin! box to let the builder "no e are creatin! a summary %ield on top o% the !rouped data and then clic" on

10

#igure &&' (nsert summary )ield

<ou2ll see a ne

%ield created$ =count3MP(O2$ this %ield contains the code to

calculate the number o% employees$ ABcount(current1!roup()D3()M3)B>. (o create a ne ro in the employee table and move the cursor to the cell ith a

under the *)L %ield. ?se the dialo! a!ain$ this time create a =sum2 on the *)L element$ don2t %or!et the Croupin! chec"box. <ou should end up template li"e this,

#igure &*' !ummary column template

(o

previe

your template and you2ll !et the %ollo in!,

11

#igure &+' !ummary output

<ou2ll notice

e no

have an employee number a%ter the department name

and a total salary amount %or each department. <ou can create complex calculations in the template$ its up to you.

5onditional #ormatting
<ou2ll probably have noticed that the report output has some employees that do not belon! to any department. Let2s assume employees that do not have a department. &e can achieve this #uite simply e are !oin! to have to &e need to add a ne in M*&ord. (o ith an =i%2 statement. The current release o% e ant to hide those

the Template /uilder does not support insertin! conditional statements so rite some code by hand.

%orm%ield$ you may need to enable the =5orm2 toolbar

place the cursor 0ust a%ter the =C2 %ield and insert a %orm

%ield. Open the properties and then the help text and enter$ =ABi%,D()M3LKMMB >2. This command is basically chec"in! i% the D()M3 element has a value. (o place the cursor 0ust be%ore the last =32 %ield and create another %ield$ this time enter =ABend i%B>2$ this closes the i% statement. *o i% the =i%2 statement is evaluated to true then the content bet een the =i%2 and =end i%2 statement i.e the department and employee data in the %irst set o% data then it somethin! li"e this, ill be displayedF i% evaluated to %alse as ill not be sho . <our template should loo"

12

#igure &,' 5onditional template

The output

hen you run this template

ill not contain those employees that ith a

do not belon! to a department. <ou could e#ually exclude employees salary !reater than 6NNN. 'ts up to you and your users.

%ressing 6p
*o e no have the basic structure o% the report e ant$ e no need to

add %ormattin! to ma"e it more readable. 5or this %unctionality.

e2ll use M*&ord

<ou can update colors$ %onts$ styles hi!hli!htin! plain boiler plate and %ields$ XML Publisher dialo!$ no ill respect the %ormattin!. 5or number %ormattin!$ a!ain e use M*&ord %unctionality. Double clic" on the *)L %ield to !et the %ield speci%y the %ield type to be =(umber2 and then pic" a 5ormat %rom the drop list$ you can enter a de%ault number in the =De%ault (umber2 %ield.

13

(o

clic" OG. <ou2ll see the %ield value is no

%ormatted accordin! to the ill also

%ormat you speci%ied. XML Publisher or" %or date %ormattin!.

ill respect this at runtime. This

<ou can update the header and %ooter tooF add boiler plate$ ima!es$ etc. M*&ord ill not allo you to enter %orm %ields in the header or %ooter but you can enter the command strin! e.!. ABD()M3B>. <ou can also add pa!e numbers usin! the native M*&ord method. <ou can very #uic"ly build a report layout similar to,

#igure &.' #ormatted template

This template

ill no

!enerate the %ollo in! output.

#igure &/' #ormatted report output

O% course i% you or your users template and update the layout.

ant to ma"e a chan!e then 0ust reopen the

14

%eployment
Once you are happy the server ith your template its then a #uestion o% deployin! it to

hether that be %or the 3 /usiness *uite$ People*o%t$ OD 3d ards

or XML Publisher 3nterprise.

5onclusion
This document has !iven you brie% introduction to the orld o% XML Publisher

4T5 templates$ it has hope%ully provided you a !limpse o% the po er o% XML Publisher and the %lexibility it provides to you and your users. There are many sample templates delivered ith the Template builder install and the ?ser to create other report ob0ects such as Cuide documentation covers ho

charts$ shapes$ pa!e totals$ conditional %ormattin! ob0ects etc.

15