Advanced RTF Template

1. 1
07 Advanced RTF Template Techniques
Table of Contents
Associating XML Data..........................................................................................................................2
Know Your Data..................................................................................................................................2
Looking at Raw XML Data....................................................................................................................3
Looking at the Field Window...............................................................................................................4
Underlying Tags..................................................................................................................................5
Form Field Method Tags .....................................................................................................................5
Form Field Method Tags .....................................................................................................................6
Additional Tag Space...........................................................................................................................7
Premarkup Layout..............................................................................................................................8
SupportedNative Formatting Features ................................................................................................8
Designing the Template Layout...........................................................................................................9
Add Markup.......................................................................................................................................9
Images and Charts............................................................................................................................11
Adding a Chart..................................................................................................................................12
Chart Sample: Bar Chart....................................................................................................................13
Chart Sample: Pie Chart....................................................................................................................14
Chart Sample: Bar Horizontal Chart....................................................................................................15
Chart Sample: Line Chart...................................................................................................................16
Drawing, Shape, and Clip Art Support ................................................................................................17
Other Graphic Features.....................................................................................................................17
Data-Driven Shape Support...............................................................................................................18
Background and Watermark Support.................................................................................................20
Template Features............................................................................................................................20
Conditional Formatting.....................................................................................................................23
Page-Level Calculations.....................................................................................................................28
Data Handling...................................................................................................................................30
Variables, Parameters, and Properties ...............................................................................................31
Advanced Report Layouts..................................................................................................................33

2. 2
Associating XMLData
In the previouslesson,youwere toldsimplyto include certainfieldsor type certain tags, such as
<?USER_NAME?>, but how do you know what to enteror what to drag and drop?
Know Your Data
There is no “intelligent”mappingmechanismwithinOracle BI Publisher.Youhave to know something
about the data you are using,and how that data is appearingin XML to your report.
There are two useful methodsfor exploringthe data to understandit:
• You can look at the raw XML data.
• You can look at the data structure in the FieldwindowinOracle BI PublisherDesktop.
Know Your Data
Your template contentandlayoutmustcorrespondtothe contentandhierarchyof the inputXML file.
Each data fieldinyourtemplate mustmapto an elementinthe XML file.Eachgroupof repeating
elementsinyourtemplatemustcorrespondtoaparent-childrelationshipinthe XMLfile.Tomapthe
data fieldsyoudefine placeholders.Todesignate the repeatingelements,youdefine groups.

3. 3
Looking at RawXML Data
Because you have a basic understandingof XML, this isa snippetof XML data as a sample.(Note:This
is a portion of the file.So,the closingtags are not all present.)
Raw XML Data
Each data fieldinyourreporttemplate mustcorrespondtoan elementinthe XML file.Whenyoumark
up yourtemplate design,youdefineplaceholdersforthe XMLelements.The placeholdermapsthe
template reportfieldtothe XML element.Atruntime,the placeholderisreplacedbythe value of the
elementof the same name inthe XML data file.
Thisis a goodexample of datacomingfroman outside source.Inthiscase,the data was producedby
Oracle ReportsrunningfromwithinanOracle eBusinessSuite 11i database,andqueryingthe userdata
fromthat system.Inorderto reallyunderstandthisdata,youwouldhave tounderstandOracle
eBusinessSuite11i security.But,itisnot uncommonforXML comingfromothersystemsto produce
unnecessaryXMLtags before the firsttagof interest.Inthisdata,the firsttag of interestisthe
<USER_NAME>SYSADMIN</USER_NAME> tag.
Notice the groupdata, <G_RESPS>, beneaththat<USER_NAME> tag.
Thisis the structure of yourdata. But,it can be difficulttoreadall but verysimple XMLdata.And,
because itisdifficult,youcanbe prone to makingerrorswhendoingso.

4. 4
Looking at the Field Window
The Fieldwindow, calledup by choosingInsert > Fieldfromthe menu,is much less error prone, and it
is easierto see tabular structures.

5. 5
Underlying Tags
In the Basic method,it is obviousto see the relationbetweenthe XML data and the tag.
XML data = <USER_NAME>
Placeholder = <?USER_NAME?>
But, how does the Form Fieldmethodcreate tags?
Form Field Method Tags
Right-clickthe field,andchoose Propertiesto openthe TextForm FieldOptionswindow.

6. 6
Form Field Method Tags
Choose the Add HelpText button to see the tag
Note that the placeholder,evenwiththe FormFieldmethod,isstill <?USER_NAME?>,whichis whatit
wouldbe if youusedthe Basic method.

7. 7
Additional Tag Space
There are two placesto put tags: Status Bar (first) and HelpKey (F1) (second).
Additional Tag Space
There isa majornote to make at thispoint.There isa limitationof the Form Fieldmethod.The Status
Bar part of the Additional HelpTextislimitedto138 characters.The HelpKey(F1) part islimitedto255
characters.These twoareas are simplyconcatenatedwithStatusBarappearingfirstfollowedbyHelp
Key.So,intotal,you are limitedto393 characters. If you have placeholdersthatstretchcapabilitiesor
use advancedfunctionsthatgobeyond393 characters, forthat placeholder,youwill have touse the
Basic method.

8. 8
PremarkupLayout
Oracle BI Publisherconvertsall formatting that you apply inthe word-processingprogram to XSL-FO.
But, some featuresof your word processor may not be mappable to XSL-FO.
SupportedNative Formatting Features
• General features
• Alignment
• Tables
• Date fields
• Multicolumnpage support
SupportedNative Formatting Features
General features:
• Large blocksof text
• Page breaks
• Page numbering
Alignment:Supportedfortext,graphics,objects,andtables
• Bidirectionallanguagesare handledautomaticallyusingyourword-processing
application’sleft/rightalignmentcontrols.
Tables:
• Nestedtables
• Cell alignment
• Row andcolumnspanning
• Table autoformatting
• Cell patternsandcolors
• Repeatingtable headers
• Preventrowsfrombreakingacrosspages
• Fixed-widthcolumns
Date fields:Correspondtopublishingdate,notthe requestrundate.
MulticolumnPage Support:enablesyoutouse the multiple columnfunctionfromMicrosoftWordto
publishyouroutput.
For more informationonanyof these supportedfeatures,see the Oracle BIPublisherUser’sGuide.

9. 9
Designing the Template Layout
• Selectthe size,font,and alignmentof text.
• Insert bulletsand numbering.
• Draw borders around paragraphs.
• Include watermarks.
• Include images(jpg, gif,or png).
• Create tables and use table autoformatting features.
• Insert headersand/or footers.
Add Markup
Placeholders:
• <?XML elementtagname?>
XML data value: (example)
• <?USER_NAME?>
Groups:(example)
• <?for-each:USER_NAME?>
• <?end for-each?>
Headers and footers:
• Use native RTF headersand footers.
Add Markup
Note:You can easilymix manual markupwiththatdone inOracle BIPublisherDesktop.Infact,Oracle BI
PublisherDesktopisjustusingthe hiddenFormFieldmethodthatisavailable withinMicrosoftWord
2000 (andlater).
Your template contentandlayoutmustcorrespondto the contentandhierarchyof the inputXML file.
Each data fieldinyourtemplate mustmapto an elementinthe XML file.Eachgroupof repeating
elementsinyourtemplatemustcorrespondtoaparent-childrelationshipinthe XMLfile.
By definingagroup,youare notifyingOracle BIPublisherthat foreach occurrence of an element
(parent),youwantthe includedfields(children) displayed.Atruntime,Oracle BIPublisherwillloop
throughthe occurrencesof the elementanddisplaythe fieldseachtime.
Note that the groupelementmustbe aparentof the repeatingelementsinthe XMLinputfile.
• If you insertthe groupingtagsaroundtextor formattingelements,the textand
formattingelementsbetweenthe grouptagswill be repeated.
• If you insertthe tags arounda table,the table will be repeated.

10. 10
• If you insertthe tags aroundtextina table cell,the textinthe table cell
betweenthe tagswill be repeated.
• If you insertthe tags aroundtwodifferenttable cells,butinthe same table row,
the single rowwill be repeated.
• If you insertthe tags aroundtwodifferenttable rows,the rowsbetweenthe
tags will be repeated(thisdoesnotinclude the row thatcontainsthe “end
group” tag).
Headers and Footers
Oracle BI Publishersupportsthe use of the native RTFheaderandfooterfeature.Tocreate a headeror
footer,use the yourword-processingapplication’sheaderandfooterinsertiontools.Asanalternative,
youcan define aninternal templateinthe bodyof yourtemplate,andthencall thissubtemplatefrom
the headeror footerregion.See HeaderandFooterTemplate Alternativeof the OracleBI Publisher
User’sGuide.
If your template requiresmultiple headersandfooters,create thembyusingOracle BIPublishertagsto
define the bodyareaof yourreport.Whenyou define the bodyarea,the elementsoccurringbefore the
beginningof the bodyareawill compose the header.The elementsoccurringafterthe bodyareawill
compose the footer.Use the followingtagstoenclose the bodyareaof yourreport:
• <?start:body?>
• <?endbody?>
Use the tags eitherdirectlyinthe template,orinformfields.
At the time of thiswriting,MicrosoftWorddoesnot supportformfieldsinthe headerandfooter.You
must,therefore,insertthe placeholdersyntax directlyinto the template (basicRTFmethod),oruse the
headerandfootertemplate alternative.
MicrosoftWord doesnot allowformfieldsinthe headerandfooterregionsof adocument.If you
require manyor complex objectsinthe headerorfooterof your report,these regionscanbecome
difficulttoreador understand.Asanalternative,youcancreate headerand footertemplatesinthe
bodyof yourRTF template documentthatcanthenbe calledfromthe headerorfooterregion.
To create a template withinyourtemplate,simplywrapthe contentsof the internal templatewiththe
followingtags:
• <?template:internaltemplatename?>
• <?endtemplate?>
where internaltemplatename isthe name youassigntothe header/footertemplate.
Thenin the header/footerregion,simplyenterthe followingsyntax tocall thistemplate:
• <?call:internaltemplatename?>
At run time,the contentsof the internal template will renderatthe positionof the call.
Example
Assume youhave the followingXMLdata:
<REPORT>
<COMPANY_NAME>Oracle</COMPANY_NAME>
<REPORT_NAME> AccountsPayables –Invoice Listing</REPORT_NAME>
<REPORT_DATE>1st January2005</REPORT_DATE>
<LEGAL_TEXT>Private and Confidential</LEGAL_TEXT>

11. 11
...
/<REPORT>
You wantthe COMPANY_NAME,REPORT_NAME,and REPORT_DATE to be displayedinatable inthe
headerof the report.In the headerof your template,enterthe following:
• <?call:OraHeader/>
At run time,the OraHeadertemplatewillbe renderedinthe headerof eachpage of the document.
Images and Charts
Oracle BI Publishersupports several methodsof includingimagesor charts in an Oracle BI Publisher
report.
• Direct insertion
• URL reference
• OA_MEDIA directory reference
• Image retrievedfromBLOB data
• LeveragingOracle BusinessIntelligence Beans(UIBeans) to add charts and graphs to
an RTF template.
Images and Charts
For URL reference,dothe following:
1. Inserta dummyimage inyour template.Forlayoutpurposes,itisbestif the dummy
image isthe same size,inpixel heightandwidth,asyouractual image.
2. In the Format Picture dialogbox (right-clickonthe image toopen),selectthe Webtab.
Enter the followingsyntax inthe Alternative Textregion:
url:{‘http://image.location.com/image-name’}
OA_MEDIA methodreferstoonlyOracle eBusinessSuite installations.Otherwise,itisthe same at the
URL reference withthe Alternative Textchangingto:url:{‘${OA_MEDIA}/image-name’}
If your data source is an Oracle BI PublisherDataTemplate,andyourresultsXML containsimage data
that had beenstoredasa BLOB in the database,use the followingsyntax inaformfieldinsertedinyour
template where youwantthe image torenderatrun time:
<fo:instream-foreign-objectcontenttype="image/jpg">
<xsl:value-of select="IMAGE_ELEMENT"/>
</fo:instram-foreign-object>
where image/jpg isthe MIME type of the image (otheroptionsmightbe:image/gif andimage/png)
AndIMAGE_ELEMENT isthe elementname of the BLOBin yourXML data.
Note that youcan specifyheightandwidthattributesforthe image tosetitssize inthe published
report.Oracle BI Publisherwill scale the image tofitthe box size thatyoudefine.Forexample,tosetthe
size of the example above tothree inchesbyfourinches,enterthe following:
<fo:instream-foreign-objectcontenttype="image/jpg"height="3in

12. 12
" width="4in">
<xsl:value-of select="IMAGE_ELEMENT"/>
</fo:instram-foreign-object>
Specifyinpixelsasfollows:
<fo:instream-foreign-objectcontenttype="image/jpg"height="300
px"width="4px">
...
or in centimeters:
<fo:instream-foreign-objectcontenttype="image/jpg"height="3cm
" width="4cm">
...
or as a percentage of the original dimensions:
<fo:instream-foreign-objectcontenttype="image/jpg"height="300%
" width="300%">
...
Adding a Chart
• Insert a dummy image inyour template to define the size and positionof the chart.
• Add a definitionforthe chart to the Alternative Textbox of the dummy image.The
chart definitionrequiresXSLcommands.
• At run time,Oracle BI Publishercallsthe appropriate BI Bean to render the image that
is insertinto the final output.
Addinga Chart
Note:For more information,see pg.2–16 through2–26 inthe Oracle BI PublisherUser’sGuide.
The processgeneratesaplaceholder.The textof thatplaceholdercanbe viewedbyright-clickingthe
image placeholder,choosingFomatPicture,andthenselectingthe Webtab.

13. 13
Chart Sample: Bar Chart
Chart Sample:Bar Chart
There are onlyfoursupportedcharttypes.
• Bar
• Pie
• Bar – Horizontal
• Line

14. 14
Chart Sample: Pie Chart

15. 15
Chart Sample: Bar Horizontal Chart

16. 16
Chart Sample: Line Chart

17. 17
Drawing, Shape, and ClipArt Support
The followingAutoShape categoriesare supported:
• Lines:Straight, arrowed, connectors, curve,free-form,and scribble
• Connectors:Only straight connectors
• Basic Shapes: All shapes supported
• Block Arrows: All arrows supported
• Flowchart: All objectssupported
• Stars and banners: All objectssupported
• Callouts:“Line” calloutsnot supported
• Clipart: To add imagesusing the Microsoft ClipArt libraries
Other Graphic Features
• Freehanddrawing: Supported
• Layering: Supported
• 3-D Effects: Not currentlysupported
• MicrosoftEquation: Supported
• Organization Chart: Supported
• WordArt: Mostlysupported
Note:Some MicrosoftWordArt usesbitmapoperationsthatcurrentlycannotbe convertedtoSVG
(Scalable VectorGraphic).Touse the unsupportedWordArtinyourtemplate,take ascreenshotof the
WordArtand save it as an image (gif,jpeg,orpng). Replace the WordArtwiththe image.

18. 18
Data-Driven Shape Support
In additionto supportingthe static shapes and featuresin your templates,Oracle BI Publisher
supports the manipulationofshapes basedon incoming data or parameters,as well.The following
manipulationsare supported:
• Replicate
• Move
• Change size
• Add text
• Skew
• Rotate
Data-Driven Shape Support
Enter manipulationcommandsforashape inthe Webtab of the shape’spropertiesdialogbox (right-
click,FormatAutoShape > Web> AlternativeText).
Replicatinga Shape
You can replicate ashape basedon incomingXMLdata in the same wayyou replicate dataelementsin a
for-eachloop.Todo this,use a for-each@shape commandinconjunctionwithashape-offset
declaration.Forexample,toreplicate ashape downthe page,use the followingsyntax:
<?for-each@shape:SHAPE_GROUP?>
<?shape-offset-y:(position()-1)*100?>
<?endfor-each?>
where
for-each@shape opensthe for-eachloopforthe shape context
SHAPE_GROUP isthe name of the repeatingelementfromthe XMLfile.Foreachoccurrence of the
SHAPE_GROUP element,anewshape will be created.
shape-offset-y: Isthe command tooffsetthe shape alongthe y-axis.(position()-1)*100) setsthe offset
inpixelsperoccurrence.The XSLpositioncommandreturnsthe recordcounterinthe group (thatis,1,
2, 3, 4, and so on);one issubtractedfromthat numberand the resultismultipliedby100. Therefore,for
the firstoccurrence,the offsetwouldbe 0:(1-1) * 100. The offsetforthe secondoccurrence wouldbe
100 pixels:(2-1) *100. Andfor eachsubsequentoccurrence,the offsetwouldbe another100 pixels
downthe page.
AddingText to a Shape
You can add textto a shape dynamicallyeitherfromthe incomingXMLdata or from a parametervalue.
In the propertiesdialogbox,enterthe followingsyntax:
<?shape-text:SHAPETEXT?>
where SHAPETEXTisthe elementname inthe XML data.At run time,the textwill be insertedintothe
shape.
AddingText Along a Path

19. 19
You can add textalonga line orcurve fromincomingXML data or a parameter.Afterdrawingthe line,in
the propertiesdialogbox enter:
<?shape-text-along-path:SHAPETEXT?>
where SHAPETEXTisthe elementfromthe XML data.At runtime the value of the SHAPETEXTelement
will be insertedaboveandalongthe line.
Movinga Shape
You can move a shape or transpose italongboth the x and y axesbasedon the XML data. For example,
to move a shape 200 pixelsalongthe y-axisand300 alongthe x-axis,enterthe followingcommandsin
the propertiesdialogbox of the shape:
<?shape-offset-x:300?>
<?shape-offset-y:200?>
Rotating a Shape
To rotate a shape abouta specifiedaxisbasedonthe incomingdata,use the followingcommand:
<?shape-rotate:ANGLE;’POSITION’?>
where
ANGLE isthe numberof degreestorotate the shape.If the angle ispositive,the rotationisclockwise;if
negative,the rotationiscounterclockwise.
POSITION isthe pointaboutwhichto carry out the rotation,forexample,“left/top.”Validvaluesare
combinationsof left,right,orcenterwithcenter,top,orbottom.The defaultisleft/top.
Skewinga Shape
You can skewa shape alongitsx or y axisusingthe followingcommands:
<?shape-skew-x:ANGLE;’POSITION’?>
<?shape-skew-y:ANGLE;’POSITION’?>
where
ANGLE isthe numberof degreestoskewthe shape.If the angle ispositive,the skew istothe right.
POSITION isthe pointaboutwhichto carry out the rotation,forexample,“left/top.”Validvaluesare
combinationsof left,right,orcenterwithcenter,top,orbottom.The defaultisleft/top.
For example,toskewashape by30 degreesaboutthe bottomrightcorner,enterthe following:
<?shape-skew-x:number(.)*30;’right/bottom’?>
Changingthe Size of a Shape
You can change the size of a shape usingthe appropriate commandseitheralongasingle axisoralong
bothaxes.To change a shape’ssize alongbothaxes,use:
<?shape-size:RATIO?>
where RATIOisthe numericratioto increase ordecrease the size of the shape.Therefore,avalue of 2
wouldgenerate ashape twice the heightandwidthof the original.A value of 0.5 wouldgenerate a
shape half the size of the original.Tochange a shape’ssize alongthe x ory axis,use:
<?shape-size-x:RATIO?>
<?shape-size-y:RATIO?>
Changingonlythe x or y value hasthe effectof stretchingorshrinkingthe shape alonganaxis.Thiscan
be data driven.

20. 20
Background and WatermarkSupport
Oracle BI Publishersupports the Background feature in MicrosoftWord. Youcan specifya single,
graduated color or an image background for your template to be displayedinthe PDF output. Note
that thisfeature issupported for PDF output only.
To add a background to your template,use the Format > Background menuoption.
In Microsoft Word2002 or later,you can add a textor image watermark via Format > Background >
PrintedWatermark.
Template Features
• Page breaks
• Initial page numbers
• Hyperlinks
• Table of contents
• Bookmarks inPDF output
• Check boxes
• Drop-down lists
Template Features
Page Breaks
To create a page breakafterthe occurrence of a specificelement,use the split-by-page-breakalias.This
will cause the reportoutputto insertahard page breakbetweeneveryinstanceof aspecificelement.
You can alsoinserta form fieldimmediatelyfollowingthe formfieldof the elementyouwantthe page
breakto occur after.In the HelpTextof thisformfield,enterthe syntax:
• <?split-by-page-break:?>
Initial Page Numbers
Some reportsrequire thatthe initial page numberbe setata specifiednumber.Forexample,monthly
reportsmay be requiredtocontinue numberingfrommonthtomonth.Oracle BIPublisherallowsyouto
setthe page numberinthe template tosupportthisrequirement.
Use the followingsyntax in yourtemplate tosetthe initial page number:
• <?initial-page-number:pagenumber?>
where pagenumberisthe XML elementorparameterthatholdsthe numericvalue.
If your XML data containsanelementtocarry the initial page number,forexample:
<REPORT>
<PAGESTART>200<PAGESTART>
....
</REPORT>

21. 21
Enter the followinginyourtemplate:
• <?initial-page-number:PAGESTART?>
Your initial page numberwillbe the value of the PAGESTARTelement,whichinthiscase is200.
Example 2: Setpage numberbypassinga parametervalue.
If you define aparametercalledPAGESTART,youcanpassthe initial valuebycallingthe parameter.
Enter the followinginyourtemplate:
• <?initial-page-number:$PAGESTART?>
Note:You must firstdeclare the parameterinyourtemplate.See “DefiningParametersinYour
Template”inthe Oracle BI PublisherUser’sGuide.
Hyperlinks
You can add fixedordynamichyperlinkstoyourtemplate.
• To insertstatichyperlinks,use yourword-processingapplication’sinsert
hyperlinkfeature.
• If your template includesadataelementthatcontainsahyperlinkorpartof
one,youcan create dynamichyperlinksatruntime.Inthe Type the file or Web
page name fieldof the InsertHyperlinkdialogbox,enterthe followingsyntax:
{URL_LINK}
where URL_LINKis the incomingdataelementname.
• If you have a fixedURL that youwantto pass parametersto,enterthe following
syntax:
http://www.oracle.com?product={PRODUCT_NAME}
where PRODUCT_NAMEis the incomingdataelementname.
• In boththese cases,at run time the dynamicURL will be constructed.
Table of Contents
Oracle BI Publishersupportsthe table of contentsgenerationfeature of the RTFspecification.Follow
your word-processingapplication’sproceduresforinsertinga
table of contents.Oracle BIPublisheralsoprovidesthe abilitytocreate dynamicsectionheadingsin
your documentfromthe XML data. You can thenincorporate these intoatable of contents.
To create dynamicheadings:
1. Enter a placeholderforthe headinginthe bodyof the document,andformatit
as a “Heading,”usingyourword-processingapplication’sstyle feature.You
cannot use formfieldsforthisfunctionality.
· For example,youwantyourreporttodisplayaheadingforeach
companyreported.The XML data elementtagname is
<COMPANY_NAME>. In your template,enter<?COMPANY_NAME?>
where youwantthe headingtoappear.Now format the textas a
Heading.
2. Create a table of contentsusingyourword-processingapplication’stable of
contentsfeature.
3. At run time,the TOCplaceholdersandheadingtextwillbe substituted.
GeneratingBookmarks in PDF Output

22. 22
If you have definedatable of contentsinyourRTF template,youcanuse yourtable of contents
definitiontogenerate linksinthe Bookmarkstabinthe navigationpane of youroutputPDF.The
bookmarkscan be eitherstaticor dynamicallygenerated.
• To create linksfora statictable of contents,enterthe syntax:
<?copy-to-bookmark:?>
directlyabove yourtable of contentsand
<?endcopy-to-bookmark:?>
directlybelowthe table of contents.
• To create linksfora dynamictable of contents,use:
<?convert-to-bookmark:?>
directlyabove the table of contentsand
<?endconvert-to-bookmark:?>
directlybelowthe table of contents.
Check Boxes
You can include acheck box inyour template thatyoucan define todisplayasselected(Checked) or
deselected(NotChecked) basedonavalue fromthe incomingdata.To define acheckbox in your
template:
1. Positionthe cursorinyour template whereyouwantthe checkbox to appear,
and selectthe CheckBox FormField fromthe Formstool bar.
2. Right-clickthe fieldtoopenthe CheckBox Form FieldOptions dialogbox.
3. Specifythe Defaultvalue as eitherCheckedorNotChecked.
4. In the Form FieldHelpTextdialogbox,enterthe criteriaforhow the box should
behave.Thismustbe a Booleanexpression(thatis,one thatreturnsatrue or
false result).Forexample,supposeyourXML data containsanelementcalled
<population>.Youwantthe check box to appearselectedif the value of
<population>isgreaterthan10,000. Enter the followinginthe helptextfield:
<?population>10000?>
5. Note that youdo nothave to construct an “if” statement.The expressionis
treatedas an “if”statement.
Drop-Down Lists
Oracle BI Publisherallowsyoutouse the drop-downformfieldtocreate a cross-reference inyour
template fromyourXML data to some othervalue thatyou define inthe drop-downformfield.For
example,suppose youhave the followingXML:
<countries>
<country>
<name>Chad</name>
<population>7360000</population>
<continentIndex>5</continentIndex>
</country>
<country>
<name>China</name>
<population>1265530000</population>

23. 23
<continentIndex>1</continentIndex>
</country>
<country>
<name>Chile</name>
<population>14677000</population>
<continentIndex>3</continentIndex>
</country>
. . .
</countries>
Notice thateach <country> entryhas a <continentindex>entry,whichisanumericvalue torepresent
the continent.Usingthe drop-downformfield,youcancreate an index inyourtemplate thatwill cross-
reference the <continentindex>value tothe actual continentname.Youcanthendisplaythe name in
your publishedreport.Tocreate the index forthe continentexample:
1. Positionthe cursorinyour template whereyouwantthe value fromthe drop-
downlistto display,andselectthe Drop-DownFormFieldfromthe Formstool
bar.
2. Right-clickthe fieldtodisplaythe Drop-DownFormFieldOptions dialogbox.
3. Addeach value tothe Drop-down itemfield andthe click Add to add itto the
Itemsin drop-down listgroup.The valueswill be indexedstartingfromone for
the first,and soon. For example,the listof continentswill be storedasfollows:
Index Value
1 Asia
2 NorthAmerica
3 SouthAmerica
4 Europe
5 Africa
6 Australia
Nowuse the HelpTextbox to enterthe XML elementname thatwill holdthe index forthe drop-down
fieldvalues.Forthisexample,enter<?continentIndex?>
Conditional Formatting
• if statements
• if statementsinboilerplate text
• if-then-else statements
• choose statements
• Columnformatting
• Row formatting
• Cell highlighting

24. 24
Conditional Formatting
Conditional formattingoccurswhenaformattingelementappearsonlywhenacertainconditionismet.
Oracle BI Publishersupportsthe usage of simple if statements,aswell asmore complex choose
expressions.The conditionalformattingthatyouspecifycanbe XSL or XSL:FO code,or youcan specify
actual RTF objectssuchas a table or data. For example,youcanspecifythatif reportednumbersreacha
certainthreshold,theywill displayshadedinred.Or,youcan use thisfeature tohide table columnsor
rowsdependingonthe incomingXMLdata.
if Statements
Use an if statementtodefine asimple condition;forexample,if adata fieldisaspecificvalue.
• Insertthe followingsyntax todesignatethe beginningof the conditional area.
<?if:condition?>
• Insertthe followingsyntax atthe endof the conditional area:<?endif?>.
For example,tosetupthe PayablesInvoice Registertodisplayinvoicesonlywhenthe Suppliername is
"CompanyA",insertthe syntax <?if:VENDOR_NAME=’COMPANYA’?>before the Supplierfieldonthe
template.Enterthe <?endif?>tag afterthe invoicestable.
Note that youcan insertthe syntax informfields,or directlyintothe template.
if Statementsin Boilerplate Text
Assume youwantto incorporate anif statementintothe followingfree-formtext:
• The program was (not) successful.
You onlywantthe “not” to displayif the value of an XML tag called<SUCCESS> equals“N”.To achieve
thisrequirement,youmustuse the Oracle BIPublishercontextcommandtoplace the if statementinto
the inline sequence ratherthanintothe block(the defaultplacement). Note:Formore informationon
contextcommands,see “UsingContextCommands”inthe OracleBI PublisherUser’sGuide.
For example,if youconstructthe code asfollows:
• The program was <?if:SUCCESS=’N’?>not<?endif?>successful.
The followingundesirableresultwill occur:
The program was
not
successful.
because Oracle BIPublisherappliesthe instructionstothe blockbydefault.Tospecifythatthe if
statementshouldbe insertedintothe inlinesequence,enterthe following:
• The program was <?if@inlines:SUCCESS=’N’?>not<?endif?>successful.
Thisconstruction will resultinone of twodisplays.If SUCCESSdoesnotequal ‘N’,the displaywill be The
program wassuccessful.If SUCCESSequals‘N’,the displaywill be The programwasnotsuccessful.
if-then-else Statements
Oracle BI Publishersupportsthe commonprogrammingconstruct“if-then-else.”Thisisextremelyuseful
whenyouneedtotesta conditionandconditionallyshowaresult.Forexample:
IF X=0 THEN
Y=2
ELSE
Y=3

25. 25
END IF
You can alsonestthese statementsasfollows:
IF X=0 THEN
Y=2
ELSE
IF X=1 THEN
Y=10
ELSE Y=100
END IF
Use the followingsyntax toconstructan if-then-elsestatementinyourRTFtemplate:
• <?xdofx:if element_condition thenresult1else result2endif?>
For example,the followingstatementteststhe AMOUNTelementvalue.If the value isgreaterthan
1000, showthe word"Higher";if it islessthan1000, show the word "Lower";if itis equal to1000, show
"Equal":
<?xdofx:if AMOUNT> 1000 then’Higher’
else
if AMOUNT < 1000 then’Lower’
else
’Equal’
endif?>
choose Statements
Use the choose,when,andotherwiseelementstoexpressmultipleconditional tests.If certain
conditionsare metinthe incomingXML data, thenspecificsectionsof the template willbe rendered.
Thisis a verypowerful featureof the RTFtemplate.InregularXSLprogramming,if a conditionismetin
the choose command,thenfurtherXSLcode isexecuted.Inthe template,however,youcanactuallyuse
visual widgetsinthe conditional flow(inthe followingexample,atable).Use the followingsyntax for
these elements:
• <?choose:?>
• <?when:expression?>
• <?otherwise?>
ColumnFormatting
You can conditionallyshowandhide columnsof datainyourdocumentoutput.The followingexample
demonstrateshowtosetupa table sothat a columnis onlydisplayedbasedonthe value of anelement
attribute.Thisexamplewillshowareportof a price list,representedbythe followingXML:
<itemstype="PUBLIC"><! - can be marked‘PRIVATE’ - >
<item>
<name>PlasmaTV</name>
<quantity>10</quantity>
<price>4000</price>
</item>
<item>
<name>DVDPlayer</name>

26. 26
<quantity>3</quantity>
<price>300</price>
</item>
<item>
<name>VCR</name>
<quantity>20</quantity>
<price>200</price>
</item>
<item>
<name>Receiver</name>
<quantity>22</quantity>
<price>350</price>
</item>
</items>
Notice the type attribute associatedwiththe itemselement.InthisXMLit ismarkedas "PUBLIC"
meaningthe listisa publiclistratherthana "PRIVATE"list.Forthe “public”versionof the list,youdo
not wantto showthe quantitycolumninthe output,butyou wantto developonlyone template for
bothversionsbasedonthe listtype.
Row Formatting
Oracle BI Publisherallowsyoutospecifyformattingconditionsasthe row-levelof atable.Examplesof
row-level formattingare:
• Highlightingarow whenthe datameetsa certainthreshold.
• Alternatingbackgroundcolorsof rowstoease readabilityof reports.
• Showingonlyrowsthatmeeta specificcondition.
ConditionallyDisplayinga Row
To displayonlyrowsthatmeeta certaincondition,insertthe <?if:condition?><?endif?>tagsat the
beginningandendof the row,withinthe for-eachtagsforthe group.This isdemonstratedinthe
followingsample template.
Cell Highlighting
The code to highlightthe debitcolumnasshowninthe table is:
<?if:debit>1000?>
<xsl:attribute
xdofo:ctx="block"name="background-color">red
</xsl:attribute>
<?endif?>
The "if"statementistestingif the debitvalue isgreaterthan1000. If it is,thenthe nextlinesare
invoked.Noticethatthe example embedsnative XSLcode insidethe "if"statement.The "attribute"
elementallowsyoutomodifypropertiesinthe XSL.The xdofo:ctx componentisanOracle BI Publisher
feature thatallowsyoutoadjustXSL attributesat anylevel inthe template.Inthiscase,the background
colorattribute ischangedto red.To change the colorattribute,youcan use eitherthe standardHTML
names(forexample,red,white,green) oryoucanuse the hexadecimal colordefinition(forexample,
#FFFFF).

27. 27

28. 28
Page-Level Calculations
• Page totals
• Brought forward or carried forward totals
• Running totals
Page-Level Calculations
DisplayingPage Totals
Oracle BI Publisherallowsyoutodisplaycalculatedpage totalsinyourreport.Because the page isnot
createduntil publishingtime,the totalingfunctionmustbe executedbythe formattingengine. Note:
Page totalingisperformedinthe PDF-formattinglayer.Therefore thisfeatureisnotavailableforother
outputstypes:HTML, RTF, Excel.
Because the page total fielddoesnotexistinthe XML inputdata,youmust define avariable toholdthe
value.Whenyoudefine the variable,youassociateitwiththe elementfromthe XMLfile thatisto be
totaledforthe page.Once you define total fields,youcanalsoperformadditional functionsonthe data
inthose fields.
To declare the variable thatisto holdyourpage total,insertthe followingsyntax immediatelyfollowing
the placeholderforthe elementthat istobe totaled:
• <?add-page-total:TotalFieldName;’element’?>
where
• TotalFieldName isthe name youassigntoyourtotal (to reference later) and
• ’element’isthe XML elementfieldtobe totaled.
You can add thissyntax to as manyfieldsasyouwantto total.Then whenyouwantto displaythe total
field,enterthe followingsyntax:
• <?show-page-total:TotalFieldName;’number-format’?>
where
• TotalFieldName isthe name youassignedtogive the page total fieldabove and
• number-formatisthe formatyouwishtouse to for the display.
Note that thispage totalingfunctionwillonlyworkif yoursource XML has raw numericvalues.The
numbersmustnotbe preformatted.
Brought Forward/Carried Forward Totals
Many reportsrequire thata page total be maintainedthroughoutthe reportoutputandbe displayedat
the beginningandendof eachpage.These totalsare knownas "broughtforward/carriedforward"
totals. Note:The totalingforthe broughtforwardand carriedforwardfieldsisperformedinthe PDF-
formattinglayer. Therefore thisfeatureisnotavailable forotheroutputstypes:HTML, RTF, Excel.
To displaythe broughtforwardtotal at the top of each page (exceptthe first),use the followingsyntax:
<xdofo:inline-total
displaycondition="exceptfirst"
name="InvAmt">

29. 29
Brought Forward:
<xdofo:show-brought-forward
name="InvAmt"
format="99G999G999D00"/>
</xdofo:inline-total>
The followingtable describesthe elementscomprisingthe broughtforwardsyntax:
Code Element Descriptionand Usage
inline-total Thiselementhastwoproperties:
name - name of the variable youdeclaredforthe field.
display-condition - setsthe displaycondition.Thisisan
optional propertythattakesone of the followingvalues:
first- the contentsappearonlyonthe firstpage
last- the contentsappearonlyon the lastpage
exceptfirst- contentsappearonall pagesexceptfirst
exceptlast- contentsappearonall pagesexceptlast
everytime - (default) contentsappearoneverypage
In thisexample,display-conditionissetto"exceptfirst"to
preventthe value fromappearingonthe firstpage where the
value wouldbe zero.
BroughtForward: Thisstringis optional andwill displayasthe fieldname onthe
report.
show-brought-forward Showsthe value onthe page.It has the followingtwoproperties:
name - the name of the fieldtoshow.Inthiscase,"InvAmt".This
propertyismandatory.
format- the Oracle numberformatto applyto the value at
runtime.This propertyisoptional.Formore informationabout
numberformats,see NumberandDate Formatting.
Insertthe broughtforwardobjectat the top of the template where youwantthe broughtforwardtotal
to display.If youplace itinthe bodyof the template,youcaninsertthe syntax ina formfield.If you
wantthe broughtforwardtotal to displayinthe header,youmustinsertthe full code stringintothe
headerbecause MicrosoftWorddoesnotsupportform fieldsinthe headerorfooterregions.However,
youcan alternativelyuse the Header/FooterTemplate Techniquewhichallowsyoutoenteryourheader
and footercontentwithinthe bodyof the template andthensimplyinclude acall forthiscontentin the
headeror footerregion.Thiscansimplifythe lookof yourtemplateif youhave manyor complex objects
containedinyourheaderor footerregions.See HeaderandFooterTemplate fordetails.
Place the carriedforwardobjectat the bottomof your template whereyouwantthe total to display.
The carried forwardobjectforour example isasfollows:
<xdofo:inline-total
displaycondition="exceptlast"
name="InvAmt">
CarriedForward:
<xdofo:show-carry-forward

30. 30
name="InvAmt"
format="99G999G999D00"/>
</xdofo:inline-total>
Note the followingdifferenceswiththe brought-forwardobject:
• The display-conditionissettoexceptlastsothatthe carriedforwardtotal will
displayoneverypage exceptthe lastpage.
• The displaystringis"CarriedForward".
• The show-carry-forwardelementisusedto show the carriedforwardvalue.It
has the same propertiesasbrought-carried-forward,describedabove.
You are notlimitedtoa single value inyourtemplate,youcancreate multiple broughtforward/carried
forwardobjectsinyourtemplate pointingtovariousnumericelementsinyourdata.
Running Totals
To create the RunningTotal field,define avariable totrackthe total and initialize itto0.
Data Handling
• Sorting
• Regrouping
Data Handling
Sorting
You can sort a group by anyelementwithinthe group.Insertthe followingsyntax withinthe grouptags:
• <?sort:elementname?>
To sort the example bySupplier(VENDOR_NAME),enterthe followingafterthe <?for-
each:G_VENDOR_NAME?>tag:
• <?sort:VENDOR_NAME?>
To sort a group by multiplefields,justinsertthe sortsyntax afterthe primarysortfield.Tosortby
SupplierandthenbyInvoice Number,enterthe following:
• <?sort:VENDOR_NAME?><?sort:INVOICE_NUM?>
Regroupingthe XML Data
The RTF template supportsthe XSL2.0 for-each-groupstandardthatallowsyoutoregroupXML data
intohierarchiesthatare not presentinthe original data.Withthisfeature,yourtemplatedoesnothave
to followthe hierarchyof the source XML file.You
are therefore nolongerlimitedbythe structure of yourdata source.

31. 31
Variables,Parameters,and Properties
Variables,Parameters,and Properties
UsingVariables
Updateable variablesdifferfromstandardXSLvariables<xsl:variable>inthattheyare updateable during
the template applicationtothe XML data. Thisallowsyou to create manynew featuresinyour
templatesthatrequire updateablevariables.The variablesuse a"setandget"approach forassigning,
updating,andretrievingvalues.Use the followingsyntax todeclare/setavariable value:
• <?xdoxslt:set_variable($_XDOCTX,’variablename’,value)?>
Use the followingsyntax toretrieve avariable value:
• <?xdoxslt:get_variable($_XDOCTX,’variablename’)?>
You can use thismethodto performcalculations.Forexample:
• <?xdoxslt:set_variable($_XDOCTX,’x’,xdoxslt:get_variable($_XDOCTX,’x’+1)?>
Thissetsthe value of variable ‘x’toitsoriginal value plus1,muchlike using"x = x + 1". The $_XDOCTX
specifiesthe global documentcontextforthe variables.Inamultithreadedenvironmentthere maybe
manytransformations occurringatthe same time,thereforethe variablemustbe assignedtoasingle
transformation.See the sectiononRunningTotalsforan example of the usage of updateablevariables.
DeningParameters
You can pass run-time parametervaluesintoyourtemplate.Thesecanthenbe referencedthroughout
the template tosupportmanyfunctions.Forexample,youcanfilterdatainthe template,use avalue in
a conditional formattingblock,orpasspropertyvalues(such
as securitysettings) intothe finaldocument.
Note:The Oracle Applicationsconcurrentmanagerdoesnotsupportpassingparametervaluesintothe
template.The parametersmustbe passedprogrammaticallyusingthe APIsasdescribedbelow.
Usinga parameter ina template
• Declare the parameterinthe template.Use the followingsyntax todeclare the
parameter:
<xsl:paramname="PARAMETERNAME"select="DEFAULT"xdofo:ctx="begin"/>
where
PARAMETERNAMEisthe name of the parameter
DEFAULT is the defaultvalue forthe parameter(the selectstatementisoptional)
xdofo:ctx="begin"isarequiredstringtopushthe parameterdeclarationtothe topof the template at
runtime sothat itcan be referredtogloballyinthe template.The syntax mustbe declaredinthe Help
Textfieldof aform field.The formfieldcanbe placedanywhere inthe template.
• Refertothe parameterinthe template byprefixingthe name witha"$"
character. For example,if youdeclare the parametername tobe "InvThresh",
thenreference the value using"$InvThresh".

32. 32
• At run time,passthe parametertothe Oracle BI Publisherengine
programmatically.Priortocallingeitherthe FOProcessorAPI(Core) orthe
TemplateHelperAPI(E-BusinessSuite)create aPropertiesclassandassigna
propertyto itfor the parametervalue asfollows:
Propertiesprop=newProperties();
prop.put("xslt.InvThresh","1000");
For more information,see CallingOracle BIPublisherAPIs.
SettingProperties
Oracle BI Publisherpropertiesthatare available inthe Oracle BIPublisherConfigurationfilecan
alternatively be embeddedintothe RTFtemplate.The propertiessetinthe templateare resolvedatrun
time bythe Oracle BI Publisherengine.Youcaneitherhard-code the valuesinthe template orembed
the valuesinthe incomingXML data.Embeddingthe propertiesin the template avoidsthe use of the
configurationfile.
Note:See “Oracle BI PublisherConfigurationFile”formore informationaboutthe Oracle BIPublisher
Configurationfile andthe available properties.
For example,if youuse anonstandardfontinyour template,ratherthanspecifythe fontlocationinthe
configurationfile,youcanembedthe fontpropertyinside the template.If youneedtosecure the
generatedPDFoutput,youcan use the Oracle BI PublisherPDFsecuritypropertiesandobtainthe
passwordvalue fromthe incomingXMLdata. To add an Oracle BI Publisherpropertytoatemplate,use
the MicrosoftWord Propertiesdialogbox (availablefromthe File menu),andenterthe following
information:
• Name - enterthe Oracle BI Publisherpropertyname prefixedwith"xdo-"
• Type - select"Text"
• Value - enterthe propertyvalue.Toreference anelementfromthe incoming
XML data,enterthe path to the XML elementenclosedbycurlybraces.For
example:{/root/password}
Embeddinga Font Reference
For thisexample,suppose youwanttouse a fontinthe template calledXMLPScript.Thisfontisnot
available asa regularfontonyour server,thereforeyoumusttell Oracle BIPublisherwhere tofindthe
fontat run time.You tell Oracle BIPublisherwhere tofindthe fontbysettingthe fontproperty.Assume
the fontis locatedin/tmp/fonts,thenyouwouldenterthe followinginthe Propertiesdialogbox:
• Name:xdo-font.XMLPScript.normal.normal
• Type: Text
• Value:truetype./tmp/fonts/XMLPScript.ttf
Whenthe template isappliedtothe XML data onthe server,Oracle BIPublisherwill lookforthe fontin
the /tmp/fontsdirectory.Note thatif the template isdeployedinmultiple locations,youmustensure
that the path isvalidforeach location.

33. 33
Advanced Report Layouts
• Batch reports
• Cross-tab support
• Dynamic data columns
• Definingcolumnsto repeat across pages
• Numberand date formatting
• Calendar and time zone support
• Usingexternal fonts
• Advanced designoptions
Advanced DesignOptions
If you have more complex designrequirements,Oracle BIPublishersupportsthe use of XSLand XSL:FO
elements,andhasalsoextendedasetof SQL functions.RTFtemplatesofferextremelypowerful layout
optionsusingOracle BIPublisher’ssyntax.However,because the underlyingtechnologyisbasedon
openW3C standards,such as XSL andXPATH,you are notlimitedbythe functionalitydescribedinthis
course.You can fullyutilize the layoutanddatamanipulationfeaturesavailableinthese technologies.