Drofus XFDesigner UserGuide
Drofus XFDesigner UserGuide
T AB L E O F C O NT ET
1.
INTRODUCTION ......................................................................................................5
2.
GETTING STARTED................................................................................................6
XF DESIGNER USAGE............................................................................................7
3.1. GET XML FROM DROFUS AND ASSIGN DATA SOURCE .....................................7
3.2. BASICS USAGE.......................................................................................................8
3.3. UNDERSTANDING XPATH EXPRESSIONS ...........................................................9
3.4. COMMON WAYS TO CREATE A REPORT .............................................................9
3.5. CREATING A REPEATING SECTION ...................................................................10
3.6. CREATING A REPEATING TABLE ........................................................................10
3.7. CREATING A FIELD ..............................................................................................11
3.8. STYLE FORMATTING(FONT, WEIGHT ETC) .......................................................11
3.9. DATA FORMATTING A FIELD (DATE, NUMBERS) ..............................................12
3.10. USING BUILDING BLOCKS...................................................................................12
3.11. UNLOADING BUILDING BLOCKS .........................................................................13
3.12. PAGE LAYOUT AND PAGE SET ...........................................................................13
3.13. ITEM INFORMATION IN HEADER/FOOTER .........................................................17
3.14. IMAGES FROM XML AND STATIC IMAGES .........................................................18
3.15. DECIMAL SYMBOL ...............................................................................................19
4.
6.
Page 3
IL LU ST R AT IO N S
Image 1: Exporting XML from dRofus ................................................................................7
Image 2: XF Designer User Interface .................................................................................8
Image 3: Edit Xpath expression window...........................................................................10
Image 4: Dynamic GUI XML ............................................................................................42
Page 4
1. INT RO D UCT IO N
dRofus contains a rich set of predefined reports ready to use. This is the most common
and simple way to get data from dRofus to a PDF. In some situations however you need
greater control over the data or the layout in the reports, or you simply want to create a
new type of report that does not exist. For these cases this document aids you in using
the Ecrion XF Designer tool to create reports from dRofus. You could use another tool if
you prefer, as long as you could use XML1 as a data source, but we have chosen to use
XF Designer because it is in our opinion a high quality tool that is powerful and simple to
use and has great support of the XML standards that dRofus is using. It also gives you the
ability to export the final report layout for importing back into dRofus so everybody, without
XF Designer, could generate a report in dRofus using the new layout.
XF Designer is based on the XML standard and it would be a great benefit to have some
knowledge of XML technologies such as XPATH.
Page 5
2. G ET T ING ST A RT ED
2.1.
INSTALLING XF DESIGNER
2.2.
You can download a sample package, containing example reports and data sets and this
document, from http://www.drofus.com. The sample package contains:
Reports: Example reports that can be used as a starting point for creating similar
reports or simply to learn how to use XF Designer. Documentation for each report
template is explained in chapter 5.1. In the sub folder pdf you can see a preview of
the samples.
Building Blocks: Building blocks are reusable template parts that can be used in
multiple report templates. The building blocks are explained in chapter 0.
Stylesheets: Stylesheets are documents that can define common styles (fonts, sizes,
colors etc.) that enable you to quickly change styles in multiple reports in one place.
The sample style sheet is explained in chapter 5.4
Video tutorials: Screen casts with examples of how to create reports and using the
samples.
XSL: Common special xsl files to include in reports to simplify some tasks.
XML: Sample data sets for the sample reports and using with XF Designer
Page 6
3. X F D E SI G N ER U S AG E
3.1.
GET XML FROM DROFUS AND ASSIGN DATA
SOURCE
When starting to create a report in XF Designer, the first thing you have to do is assign a
data source. The data source is an XML file with data from dRofus. You can either use
one of the sample XML files in the sample pack or generate one from dRofus. If you are
making a report for a specific project it will be beneficial to generate it from dRofus since
the data in the XML file may be specific to this project. Find the report under Reports and
exports in dRofus that is similar or contain the data you want to use in the new report.
Make the data selection and options you want. Go to More options Format and set it to
XML:
Note that some of the options will limit what data to get (e.g. what room) and some will
also define what XML to export for each room. E.g. the images will not be part of the XML
unless the "With pictures" option is checked. Also note that not all the xml attributes will be
included unless there exists data about it for the current item. E.g. if you have an extra
room core field in your project that attribute will only be included for the rooms that
actually have any value for it. Therefore it is recommended that you limit your xml to only
a part of the database when you are designing the report and that this has all the data that
you want to have in the report. We recommend that at least two items such as rooms
should be included in your data to get a correct preview.
Save the file and in XF Designer choose Home Assign Data Source and browse to the
XML file under Data Source. The XML data will be shown in the Data Source pane (3)
(default to the right) as in the image below. Now you can begin creating the report by
dragging and dropping the data from the Data Source (3) to the document/page (1).
Creating reports in dRofus with XF Designer
Page 7
Important to Google Chrome users: Because of a bug in chrome version 15 and below, you need to either
remove the drofus.xml file from the downloads folder between each time you run this report, or you can go to
options ( ) Under the Bonnet Downloads and make sure that "Ask where to save each file before
downloading" is checked. You dont need this in version 16 (currently beta).
3.2.
BASICS USAGE
Page 8
One of the first things you probably want to do is set up the page layout (see chapter 3.13)
and create a header and footer. This is done in the Page Layout ribbon. You can also use
a building block to create the same header/footer in multiple reports, see chapter 0.
3.3.
A fundamental thing when building a report based on XML data is to understand some
basics about XPath. XPath is a syntax used to describe parts of an XML document and
you can think of it as a path to the data you want. You can refer to a set of nodes such as
all the rooms in the document, a specific attribute like the room name attribute in the room
and many other variants.
XF Designer will help you create most of these expressions for you, but it is
recommended to get some understanding of this. In some of the more advanced
reports/tasks you might also need to edit some expressions manually.
When you refer to multiple nodes you refer to a node
set. In the example image to the right the expression
/drofus-xml/room-container/room
There are also functions that you can use to make tests or other operations, e.g. sum,
count etc: The expression
count(/drofus-xml/room-container/room)
3.4.
There are three main methods used in building a report; repeating table, repeating section
and dynamic page set.
A repeating table creates a table with one row for each item in a node set. You can
create a repeating table of all the room nodes and get one row per room.
Page 9
A repeating section creates an area for each item in a node set. It is used when
you want to show more data than one row per item. You can create a repeating
section for all the rooms and e.g. show a table with some of the room attributes.
Dynamic page set creates one or more pages for each item in a node set. It inserts
a page break after each item.
3.5.
Almost every report will need at least one section unless you use a repeating table as
explained in the next section. A repeating section is a paragraph that will be repeated for a
chosen item in the XML file, e.g. if you want to do something for each room in the XML.
Sections can also be nested inside each other. To create a section do one of the
following:
Position the cursor where you want to insert the section and select Insert->Repeating
Section. In the following window you can define an Xpath expression to what you
want to repeat on (see previous chapter about XPath). The easiest way is just to
navigate to the data, double click on the node (in this example room) and the
expression is created for you. Then click OK.
You can also locate the item you want to repeat on and drag it from the Data Source
window (pane 3 in Image 2) onto the document where you want it. When you drop it,
choose Repeating Section.
When this is done, the text Customize this for.. will appear. Remove this and start
placing text or fields (see 3.7).
3.6.
A common use of table is to have one table row for each item in the xml file, e.g. you want
one row per room. To create this do one of the following:
Creating reports in dRofus with XF Designer
Page 10
Drag the item you want to have one row for each item of from the navigation bar (3)
onto the document (1). Then select Repeating table. You can substitute the default
column fields with your chosen column fields.
Create a table from Insert->Table with one row and header (if you want this) and the
desired number of columns. Then position the cursor in the row (the second one if
you have a header), right click and select Convert to repeating row. Then select the
item to repeat for, e.g. /drofus-xml/room-container/room to repeat for each room.
3.7.
CREATING A FIELD
Inserting a field is the common way to get data from the XML source into the document.
To insert a field you can either just drag and drop the data element you would like to show
from the data source window or position the cursor where you want to place the field and
select Insert->Field. Again, you will be asked for an XPath expression. It is important to
note the Context that is printed at the top of the window, as the XPath expression you
create will be relative to this.
In this example you are in context of a room, e.g. you have created a section or repeating
table for each room. You can then navigate to the attribute you want by e.g. expanding
core and double click on the room_func_no attribute to get the room number. This will
construct the following expression:
core/@room_func_no
3.8.
You can format your text in the report in three different ways:
Page 11
Use the properties pane window. That way you can also set this to parts of the report
that is not "visible" in the preview. E.g. set a font or color to a block for a large part of
the report.
Use styles from a style sheet. Home Styles. This is similar to styles in Word and
lets you create common styles and easily change them later. You can also share
styles between multiple reports. If no styles are present you can choose Home
Styles Change Styles to create a new style sheet or assign an existing one.
3.9.
If you have an xml field that you would like to apply a specific formatting to (e.g. last
changed date) you can specify this under the group Home Formatting. Make sure you
first select the field you would like to format. You can then:
1) Choose from a list of predefined formatting or
2) Set a custom format
Under custom format you can create your own pattern or choose between a wide range of
predefined patterns. Example:
dd MMM yyyy hh:mm a
This will print the date with the month with only three characters followed by the time
without seconds, with AM/PM (10 Nov 2011 03:16 PM).
3.10.
Building blocks are reusable components that you can insert into you reports. The sample
package comes with some building blocks that you can use in the reports that you create.
Not only are building blocks an easy way to create new reports fast, but if you extract
common parts of your reports into a building block you can update the building block and
in that way update all the reports that is using the building block.
To add a building block place the cursor where you want to insert it and choose Insert
Building block. Then locate the building block in the building block directory of the sample
package. You can also use the pull down menu under the same menu after you have
added the building block directory under Insert Building block Manage building
blocks.
Page 12
A building block is made for a specific data context (in the xml), e.g. the room core must
be in the section that has the room node as context. The building blocks included in the
samples are described in chapter 0.
3.11.
If you have inserted a building block into your report and want to edit it, but do not want to
save the changes to the building block file, you can right click on it and select Unload
Building Block. This inserts the content of the building block into the report. This way your
changes will not affect the building block file.
3.12.
Most of the building blocks require you to be in a specific context. This is important to
understand if you would like to use a building block. This is because the X-paths are
normally relative with regards to the context of where you are (see 3.7).
E.g. if you have a building block that is intended to be used in the room context and would
like to use this in a new report you must first make sure you are in the room context by
e.g. inserting a repeating section for each room (below room-container) and then insert
the building block in this repeating section.
3.13.
In your report you can have multiple different layouts and parts of your document. The
page layout specifies page size, margins and content of headers and footers. Each part
of the report, called a Page Set, uses one or more page layouts. It is in the page set that
you define the content of the report. For example you can have a cover page with one
layout and no header/footer and one page set with the RDS for each room that has
another page layout. You can even have different layouts for different header/footer for
odd and even pages. For example:
Page 13
In order to view the pagination setup, make sure to check the pagination check box in
View Show/hide Pagination.
Page layout
To add a page layout, right click on the "Layouts" and select "Add page layout". To
rename a page layout, right click on the layout and select "Rename".
A document layout has the following regions:
Header
Page 14
Page 15
You can also add one page layout for odd pages and one for even pages if you for
example would like to only show page number in one of them.
To create a new page set go to Page Layout Pages Add page set. From the "Add
page set" dialog click "Add" to specify what page layout to use for the new page set.
You can organize the order of the page sets by right clicking on the page set in the
Pagination view and select "move up/down".
Dynamic page set
A dynamic page set is a page set that create (at least) one page per item from the XML.
An example would be an RDS report where each page has information from the room.
The best way to do this is to add a dynamic page set.
From Page Layout Pages, click the lower part of the "Add page set" and choose "Add
dynamic page set":
Click Add to add the layout you would like to use for the RDS report.
Click the small arrow to the right of the "Repeat" to navigate to the room node from XML
that each page should get data from:
Page 16
From the sort option you can define what order the rooms should come in. Click the small
arrow to the right of the "Sort" and click add to add a parameter from the XML and set
sorting options. The following example is ordered by name and then by programmed area:
3.14.
In order to show information about the item (e.g. room or FF&E) in the header or footer
you should use a "Dynamic page set" as described in 3.13. Then you can just insert fields
(3.7) as normal into the header and footer.
Page 17
3.15.
Select the xml element based on your context to get the path:
Page 18
you must make sure that "Preserve Aspect Ratio" under Image Tools Format is not
checked. You can now preview to validate that max size is correct, but as you can see the
image will not preserve the correct ratio. Open properties and then copy the values from
Image Content width/height to Width/height in Positioning and change from non-uniform
to uniform scaling:
External images
You can also include images that are not stored in dRofus. Just select the image you
would like to include. It is important that you then check the "Embed File" option else the
images will not be included when generating the report on the server:
3.16.
DECIMAL SYMBOL
You must use the English decimal symbol (.) when assigning decimal numbers in a report.
The reason is that the dRofus report server internally uses the English locale.
Page 19
4. IM PO RT ING R E PO R T S T O DRO FU S
4.1.
Templates made in XF Designer can be exporter to an XSL template file and the imported
into dRofus so that the user can run it from within dRofus like any other report.
Important: Before you export from XF Designer make sure you enable a plugin in order
for the CSS (style) information to be included properly. Go to File Options Plugins and
select Ecrion.CSS.Serializer as the Current CSS Serializer plugin.
To export your report to an XSL template file uploading go to Home Export to XSL.
4.2.
When you have exported the template file you can import it back into dRofus. Go to the
Reports and Exports and choose the built in PDF report that contains the data and options
that the new report is based upon. If you used one of the samples that follow this
document, the report to use stated under XML from report section in chapter 5.1. In the
options screen for the report, make the choices that you want to be non-configurable for
the user when he runs the report. E.g. if your report is room list and you want the XML to
contain area sums that will make your report work, check the With area sums checkbox.
This will always be checked and read-only for the users that later run your report. Press
New/Save at the bottom of the screen (if you do not see this button you do not have write
permissions to the module this report is intended for)
Make adjustments to the title and description as you want. Tick away the Shared
checkbox if you only want this report to be visible to you. If the report is shared it could
Page 20
optionally be placed in a folder (you have to make the folder in the report overview in
advance).
Then choose the Custom template option and then select your XSL file for upload. You
could also optionally upload your original design file (XF Designer file) so that you or
anyone else can download this to make new adjustments to the report. Click OK when
you are finished. The new report is now visible in the report tree and is ready to run.
Page 21
5. EX AM P L E R E PO RT S
5.1.
REPORTS
FF&E list
Filename:
FF&E list.xfd
Level
Beginner
XML from report: Other export->FF&E Catalog XML export
- Include FF&E items
- Include FF&E cost
- With sub FF&E
XML sample file: xml/ffe_with_cost.xml
Key concepts
Table repeat, sum
This report prints out FF&E items in a table. If the item has sub items, this is printed below
the parent. The report uses a repeating table row (see 3.6) for each /drofusxml/article-container/article. Inside the name column there is a repeating section
for sub-article-list/sub-article that will list the sub FF&E items.
At the bottom we use the sum function to sum the cost for all items. The XPATH
expression for this is:
sum(/drofus-xml/article-container/article/cost/price/net/excludingvat/)
This report demonstrates how to print the hierarchical FF&E catalog structure with FF&E
items. The report traverses the <level> structure that represents the FF&E catalog
structure. To do this we have a repeating section over the <level> nodes. It is important to
note that <level> nodes are nested in each other to represent the hierarchical structure.
For this reason, simply drag and drop the first level on to the document and create a
repeating section over the expression that is created (/drofus-xml/level). The expression
will not work because it will only iterate over the <level> nodes at the top level, not the sub
levels. To get this done we use an expression that will select all <level> nodes in the
document regardless of where it is placed in the XML structure. This expression can be:
//level
Page 22
To get an indent for subgroups we use a dynamic value for the Alignment & Indentation > Start Indent property set to: concat(@depth*5,mm). This uses the depth attribute for
the level which is 0 for the group (top level), 1 for subgroups etc. this is multiplied with 5
and the result is concatenated with mm that gives the length unit in millimeter. You can
use inc to get inches. This gives an indentation of 0 for groups, 5 for subgroups, 10 for
sub sub group and so on.
Below each group is a table with FF&E items (articles). The table is inside a conditional
section where the condition is count(article) > 0 that will return false if there is no items in
the group. This will prevent the table header to appear when there is no need for it. You
can insert a conditional section from Insert->Conditional Section.
The table has a table header and a repeatable row as explained in 3.6. Use the XPATH
expression article.
In the xml source the level node has child nodes called <article> that represents an FF&E
item. This node has only one attribute, @ref, that contains an id to an article item under
the /drofus-xml/article-container node. To get to the FF&E item data we need to do a look
up under the correct <article> node that has this same id. To do this efficiently we create a
index that we can use. See 5.3 to learn more about indexes. To do this, paste the
following code into the Review->Global XSLT window.
<xsl:key match="article" name="article-index" use="@id"/>
You could then of course copy/paste this field into the other column. Look under articlecontainer/article for available fields.
The sum for each group is printed after each FF&E listing and the sum for groups with sub
groups is also listed after each of the subgroups. To get this done we have two conditional
sections. The first one will print the sum after each listing and should be done only if there
are no sub groups so the condition for this is:
not(level)
To get the sum for all the groups that have subgroups, we need to do this at the end of the
last subgroup. To do this we use the following condition:
not(following-sibling::level) and parent::level
This one ensures that it is the last level and that it has a parent level.
Page 23
Room list
Filename:
Level
XML from report:
XML sample file:
Key concepts
Room list.xfd
Medium
Room -> Room list -> With area sums
xml/rooms.xml
Repeating table, key/index
This is a simple list of all rooms. It has a repeating table (see 3.6) for room that was
created by just dragging the <room> XML node from the data source pane (3) from
drofus-xml/room-container into the document.
The hard part of this report is the third column that shows the top function name
(department) in which this room is placed. The header field for this column uses the top
<level> attribute description which contains the description of this function level. This uses
the following expression
/drofus-xml/level[1]/@description
This simply goes to the first level node in the document and gets the @description
attribute.
To get the column content we have to look in the <level> hierarchy which represents the
functional structure. In this we will find all the same rooms as in the <room-container> but
only the rooms that has a @ref attribute that refers to the room-container/room/@id
attribute. To be able to reference this room we need an index. To create this, paste the
following code in to the Review->Global XSLT window.
<xsl:key match="room" name="room-ref-key" use="@ref"/>
This will index all <room> nodes based on the ref attribute. We can then use this to look
up the same room as we are currently processing by doing
key('room-ref-key', @id)
Because we also want the top level above this room the complete expression for the field
is:
key('room-ref-key',@id)/ancestor::level[last()]/@name
This looks up the room in the level tree, gets all the level nodes above it, picks the last
one and the gets the name attribute, phui...
Page 24
This report is almost identical to the FF&E list grouped report described above. Since the
<level> nodes in this case represents the room functional hierarchy just as it represented
the FF&E catalog structure the <level> traversing will be identical, we just refer to rooms
and use the room-container instead of the article and article-container nodes. The sums
are also constructed the same way.
Room list by group
Filename:
Level
XML from report:
XML sample file:
Key concepts
The Room list by group example is also identical to the FF&E list grouped report in that
now the <level> nodes represent the group type/group structure. It has some simplification
of the fields in the header and the sum for each top level is removed since it is not
interesting to see the sum for programmed area for a group type in total.
RDS simple sample, building blocks
Filename:
Level
XML from report:
XML sample file:
Key concepts
This report is built up almost only by using building blocks. We have defined a custom
header so that we can show both the room function number and the geographical (if it has
any value) in the header. It also uses a dynamic page set for each room ordered by room
function number. See 3.13 for how to create dynamic page sets and change the order of
the rooms. See 3.10 on how to insert building blocks. The room core building block needs
an index over all the room ref nodes so the following xpath expression has been added in
the Review->Global XSLT window:
<xsl:key match="room" name="room-ref-index" use="@ref"/>
Page 25
This is the same report as the RDS simple sample, building blocks report except that it
also contains the FF&E in room building block.
RDS simple sample
Filename:
Level
XML from report:
XML sample file:
Key concepts
This report is basically the same as the RDS simple sample report. However, instead of
using building blocks we have unloaded the building blocks so the content of the building
blocks have been copied into the report. This makes it very easy to adjust everything in
the report.
RDS cafeteria sample, 2-column with images
Filename:
Level
XML from report:
XML sample file:
Key concepts
This report is created by first creating a page layout of A3, defining two column layouts in
the body region and setting the orientation to landscape.
Then, using building blocks, add room core information and RDS data. By default the RDS
data would flow directly below the room core. In order to make the RDS data always start
in column 2 you have to select the block-repeat element for the RDS in the navigation bar
and in the properties set Keeps & Breaks Break Before to column.
See chapter 3.15 on how to insert images from xml. I used the position of the image to
define what image was the detail image and what was the key plan image. In the source
path for the image I therefore modified it to:
pictures/picture[@position='1']/@image_data. To get image 2 (key plan) we just
change position='2'. By default the images would overflow if they are too big, so we need
to control this by setting a max size and placement as described in the images chapter.
The key plan: After adding the image. Right click on it and select "Absolute positioning". I
can then drag it to the bottom left corner of the report.
Page 26
The room core building block needs an index over all the room ref nodes so the following
xpath expression has been added in the Review->Global XSLT window:
<xsl:key match="room" name="room-ref-index" use="@ref"/>
This is a report of RDS for a room template. It has a table with core information about the
room template and uses the dynamic gui building block for the specification. We have
defined a custom header so that we can room template values in the header. It also uses
a dynamic page set for each room template ordered by room function number. See 3.13
for how to create dynamic page sets and change the order of the rooms. See 3.10 on how
to insert building blocks.
RDS - room template simple sample with FF&E list
Filename:
Level
XML from report:
XML sample file:
Key concepts
This is the same report as the RDS room template simple sample report except that it
also contains the FF&E in room building block.
Page layout sample
Filename:
Level
XML from report:
XML sample file:
Key concepts
This sample illustrates some of the possibilities with different page layout and page sets
(see chapter 3.13).
It includes a cover page with some data in the template and some data from the XML,
then a blank page. These first pages do not have any header and footer. The rest of the
report is one page per room and they both have a header, but different footer if it is an odd
or even page number.
Page 27
FF&E in room
Filename:
Level
XML from report:
XML sample file:
Key concepts
FF&E in room.xfd
Medium
Room Equipment list per room
xml/ffe_in_room.xml
Building Blocks, Dynamic page set
As the RDS simple sample report this report uses a dynamic page set for each room
ordered by room function number. It also uses the standard header and footer building
blocks and the room core building block. In addition it has the FF&E in room building
block. The FF&E in room building block needs an index of all the articles and the room
core building block needs an index of all the ref rooms in order to function properly so the
following xpath expression has been added in the Review->Global XSLT window:
<xsl:key match="article" name="article-index" use="@id"/>
<xsl:key match="room" name="room-ref-index" use="@ref"/>
FF&E specification
Filename:
Level
XML from report:
XML sample file:
Key concepts
FF&E specifications.xfd
Medium
FF&E FF&E specifications ( With pictures)
xml/ffe_specification.xml
Building Blocks, Dynamic page set, Keys, Images
This report uses a dynamic page set for each article (FF&E item) ordered by FF&E
number (see 3.13). It uses the standard footer building block, but created a custom
header (copied the building block) and added the FF&E number. It uses the FF&E
specification building block to show the specification.
The FF&E "Core" information is shown in a table. The price is formatted using the
formatting tool (see 3.9). The placement information is the only advanced entry here.
Since we dont know what depth in level the FF&E item resides and the level structure is a
separate structure in the XML (see 6.2) we use an inline repeat to iterate for each level
above, starting at the bottom using the following XPATH:
key('article-ref-index',@id)/ancestor::level
The first part key('article-ref-index',@id) uses an index to find the level for the article
(FF&E). The second part ancestor::level means get all the ancestors of type level (all the
parents) from the level. And we then print the number and name for each of them. In order
for this to work we also need a key defined in Review Global XSLT:
<xsl:key match="article" name="article-ref-index" use="@ref"/>
Page 28
This report shows the usage of building blocks to show dynamic GUI and to pass options
to this.
It also shows how the XSL report template value when defining dynamic GUI in the client
has when using the dynamic GUI building block.
Spesific placement of dynamic GUI flags/groups
Filename:
Level
XML from report:
XML sample file:
Key concepts
This report uses the dynamic GUI building blocks to show specific flags (tabs) and groups
in your report.
Use style sheets to modify the looks of dynamic GUI reports
Filename:
5.2.
BUILDING BLOCKS
Building blocks can help you create new reports fast, but they can also let you modify
common parts in multiple reports in only one design file the building block file.
The building block must normally be in the context of a specific element in the XML. E.g.
the room core building block will only work as expected if the context where it is used
matches room. If the context is wrong the xpath expressions in the building block will not
retrieve any values.
Page 29
Room Core
Filename:
room-core-bb.xfc
Level
Medium
XML context: room
Shows selected information from the room. It is built to look like the default from existing
reports in dRofus.
Header
Filename:
header-bb.xfc
Level
Beginner
XML context: (none)
This building block is a simple header with project logo, and constructor and project name
in left corner and name of the report in the right corner with a solid border at the bottom of
the header.
Footer
Filename:
footer-bb.xfc
Level
Beginner
XML context: (none)
This building block is a simple footer with information about who generated the report and
when (from the xml) and page number. It has a solid border at the top of the footer.
RDS specification (Dynamic GUI)
Filename:
rds-bb.xfc
Level
Beginner
XML context: Room
This is a simple wrapper using the dynamic GUI building block to enable it to be used in
context of room.
FF&E specification (Dynamic GUI)
Filename:
ffe-specification-bb.xfc
Level
Beginner
XML context: Article (FF&E)
This is a simple wrapper using the dynamic GUI building block to enable it to be used in
the context of article (FF&E).
Page 30
In the document where you have html data and would like to call this you must manually
edit the text view of the report and type this when you are in the context of an element
(field) with html data:
<xsl:apply-templates select="html-data"/>
Page 31
dynamic-gui-bb.xfc
Terminology: Here I will use the same name of the different parts of the dynamic GUI
that we use in the xml. See section 6.5 for description of the different parts.
Options: This building block can take several options (described below) in order to modify
the layout further. To give an option to the building block you must double click on the
building block and click the "more >>" button to add parameters. Add a parameter with the
name options and in value you specify the option(s). If you would like to give more than
one option, just add them all in the value separated by comma.
Placement of groups within a flag
Flags (or tabs) are the top level of grouping we have in dynamic data (normally presented
Page 32
as tabs in the dRofus client). Within each flag we have one or more groups. We currently
support three different forms of layout:
flag: Default layout. It will then print all the groups one at the time using the whole
available width. It will order by column number first and then row number. Meaning it
will print everything from column one, then all the groups in the second column etc.
two-column-flag: This will print the groups in two columns. First it will place everything
set to be in column one and two in client And then, if there are groups that are not in
column one or two it will split the rest over the two columns.
thee-column-flag. This behaves exactly like two columns, except one more column.
description-group (and document-group). This will print the element label (if the
element has one) in a separate row and then print the element in the whole available
width.
group. This is the default, and most common group. This will print the data the most
similar to the way it is presented in the client. It will make one column for the element
label and then one column for the fields (data) where all the data for the element will
follow. So if you have an element with a text field and then a numeric field the
numeric data will be printed right after the text is finished.
flow-group. This will just create one row for each element and let the fields (data)
follow right after the element label (no defined with for element label). Use this if you
have very limited space and it is not important to make the data align.
dyn-field-table. Like group it creates a column for the label, but then it will create a
new table for each element with as many columns as the element has fields. So if you
have two elements with three fields each it will be aligned. This is nice to use if you
e.g. has many elements with multiple check boxes each and they all have a label. If
you use group they will not align, but if you use this they will. Numeric values can be
right aligned if specified in option.
two-column and three-column. This will split the elements into two or three columns
within the group. It will use the same order as they have in the client, but in column
one print the first halve (or third) and then continue to the next column. Each group
are using the group style. The only exception is if the option to show check boxes first
is set - then the style flow-group is used instead. Note that if the group already is
within a flag that is two or three column the available space for each column is very
limited.
Page 33
Page 34
Show checkboxes in front of element label: If the first field of an element in dRofus is a
checkbox, and this field does not have its own label one could say that the checkbox is for
the element and not the field it selves. But in the client and the default layout in the reports
is to show it after the element label.
You can overwrite this feature in the report by passing the option show-checkbox-beforeelement-label=true. If the first field of an element is checkbox and the checkbox does not
have its own label (or it has a label, but the option Show label= "Do not show label") then
the checkbox is printed before the element label and excluded from the fields to print after.
A special note about using this style in combination with the two- or three-column-group
xsl style: Normally when using two- or three-column group style we would split the
elements into two or three parts and print each of them in a column using the group
layout-style. But if show checkboxes in front option is set and we have a two- or threecolumn group we would print them using the flow-group style instead. This is because a
normal pattern for using this is to have a lot of checkboxes in a group and optionally some
text fields after the checkboxes. If we use the group style in a two or three column there is
very limited space left for the content column (with fields). And we also do not need to
align the checkboxes any more (they are in front) so any additional fields would just flow
after the element label.
Control if group label should be printed: Default behavior is that before we print any of
the elements in the group we print the group label if the group has any label. You can
control the style (font/borders/colors etc.) in the style sheet, but using an option you can
also control when it should be shown (or not).
You can pass the option show-group-label=mode, where mode is one of:
always: Will always make room for the group label even if the group does not have a
label.
nonempty: Will print the label if the group has any label (even if it is not shown in the
client). This is the default behaviour.
inclient: Will print the label only if the group has a label and it is also shown in the
client (e.g. "Show border" is true for the group).
never: Will never print the group label.
Using more than one option: More than one option can be given to the same parameter
option, just comma seperated.
Example: To give the element label column width of 25%, show checkboxes before
elements, never show group label, indent disabled elements by 5mm and custom columns
for the flow table - use the following option:
show-checkbox-before-element-label=true,element-is-disabled-by-labelindent=5mm,element-label-column-percentagewidth=25,show-grouplabel=never,dyn-field-table-column-width-1=1,dyn-field-table-columnwidth-2=2,dyn-field-table-column-width-3=12
Page 35
dynamic-gui-flags-from-id.xfc
Medium
Any node that has flags, e.g. RDS, equipment-specification etc
flag-numbers = comma separated list of flag-ids to include
options = see dynamic gui building block for description
This is a building bloc that lets you use the dynamic GUI building blocks, but instead of
printing all the content, you can pass the flag(s) you would like to print. E.g. if you would
like to have a custom table layout with some flags in column 1, then some images in
column two and then the rest of the flags after this.
See the dynamic GUI building block for description (layout and options) and sample report
Custom placement of tabs and groups from dynamic GUI.xfd for usage.
Dynamic GUI for one or more specific group(s)
Filename:
Level
XML context:
Parameter(s)
dynamic-gui-groups-from-id.xfc
Medium
Any node that has groups, e.g. flag in RDS, equipment-specification etc
flag-number = flag-id to get groups from
group-numbers = comma separated list of group ids
options = see dynamic gui building block for description
This is a building bloc that lets you use the dynamic GUI building blocks, but instead of
printing all the content, you can pass the group(s) you would like to print.
See the dynamic GUI building block for description (layout and options) and sample report
Custom placement of tabs and groups from dynamic GUI.xfd for usage.
FF&E in room
Filename:
ffe-in-room.xfc
Level
Medium
XML context: room
This building block shows an FF&E list for room. It could be used in a separate report or in
combination with for instance RDS.
It contains a repeating table over room/occurrence-list/occurrence to list all occurrences in
room. To get to the FF&E item information we use a key/index since the occurrence is
only a reference to articles in drofus-xml/article-container. We use this in the global xslt:
<xsl:key match="article" name="article-index" use="@id"/>
Page 36
It includes sub FF&E it they exists. They are italic and the number is indented and this is
done by doing some conditional formatting on the table-row and the block around the
FF&E number.
5.3.
CREATING INDEXES
Take a look at the following xml. It contains one function level with one room node and a
room-container with one room node:
<drofus-xml>
<room-container>
<room id=123>
<core name=foobar/>
</room>
</room-container>
<level>
<room ref=123/>
</level>
</drofus-xml>
I want to create a report which traverses the level structure and shows information about
the rooms underneath them. The traversing is done by creating a repeating section with
/drofus-xml/level as xpath expression. However, the room node underneath the level node
is only a reference node (ref node), meaning it links or refers to a corresponding roomcontainer/room node. Ref nodes are used in order to avoid duplicating information several
places in the xml file. The link between the two room nodes is that the value of the @ref
attribute equals the value of the @id attribute.
When traversing the level node and we find the room ref node, we need a way to retrieve
the corresponding room node since it contains all the room data. The way to do this is by
creating an index. This is done by manually inserting the following xpath expression into
Review->Global XSLT window.
<xsl:match key=room-index match=room use=@id/>
It creates an index called room-index containing all the room nodes in the xml file that
contains a @id attribute. It is possible to create several indexes in the same document.
They just need a unique name.
In our report I want to insert a repeating table showing the room name for all the rooms
underneath the levels. Then I insert a field with the following xpath expression:
Page 37
key(room-index, @ref)/core/@name
I am in the context of a room ref node which has a @ref attribute. Using the @ref value I
retrieve the room node with a matching @id value from the index called room-index. The
xpath expression key(room-index, @ref) returns the room node and it contains a core
node with a @name attribute.
Important: The xsl in a building block might require one or more indexes to be defined.
This can either be done in the Review->Global XSLT Window for the building block or in
the main report using the building block.
5.4.
STYLESHEETS
In XF Designer you can assign a Cascading Style Sheet (CSS) in order to extract the style
from the layout. This is an easy way to define a common style (e.g. font size, weight etc.)
for common elements in your reports. Then you only need to update your style to change
how your report looks like.
In the samples all the reports uses the style sheet dRofus.css. In addition there is also a
style sheet dRofus2.css that you can try to assign to any of the sample to see the
difference. They both have the following styles:
Style name:
block.report-common
.core-header-cell
.core-body-cell
.core-label
.core-value
.dyn-flag-header-cell
.dyn-flag-body-cell
block.dyn-group-header
block.dyn-element-label
block.dyn-elementvalues
Description/use
Special style that is applied to the root block in the
document. Here you can define the common font and
style etc. for all the elements that do not explicitly get
another style later.
Defines the background color etc. for the header row in
the item core tables.
Defines the border around the item core in building block.
Labels in room core building block. Sets font style to italic
Values in room core building block. Sets font weight to
bold, right aligns the text and sets some padding at the
end.
Used for the table cell holding dynamic GUI flag label
information. Sets background to gray and centers the
text.
Defines the border around the content of the flag (the
groups).
The group label in dynamic GUI. Font weight bold and a
border/line below the label.
Label of elements in dynamic GUI
Values (fields) for dynamic GUI. Sets font style to italic.
Page 38
5.5.
VIDEO TUTORIALS
1) Room list
This video demonstrates how to use one of the samples included in this package and
customize it to contain the data we would like. It demonstrates:
Change the content of the report both in header and room list
2) FF&E Specification
This video demonstrates how to create a custom report from scratch. In this case a FF&E
specification report. It demonstrates:
5.6.
The XF Designer and the drofus reportserver use different software to generate the
reports. Unfortunately it sometimes causes reports exported from XF Designer to look
different than it does in XF Designer. This is only a problem when assigning margins
and/or paddings to blocks and table cells.
top-margin for blocks - Margins dont appear in XF Designer but will appear in
reports generated on the drofus reportserver.
margin and padding for table cells its best to avoid assigning margins and
padding to table cells since they seem to be supported quite differently.
Page 39
6. DRO F U S X M L DO C UM ENT A T IO N
6.1.
GENERAL
drofus-xml/property-set: This is general properties for the project and the reports. The
most important properties here are:
o drofus-xml/property-set/@constructor: Project constructor
o drofus-xml/property-set/@project_name: Project name
o
o
drofus-xml/project-pictures: This node contains logo/image for the project. There are
3 types of images: image-small is the small logo intended for report, image-large is
the pictures showed on the login screen of the client, image-large-print could be used
as a front-page large picture for print. To create an image in the report see 3.15.
6.2.
LEVEL
The /drofus-xml/level nodes are general grouping of rooms and articles and will have
different meaning for different reports. If you run a normal room list, the levels is the
functional structure but if you run list per group the level will be the group types and
groups. If you run an FF&E catalog report, the level is the catalog structure. The level
nodes can also be nested in each other so /drofus-xml/level/level is a sub function or sub
group. Under each level you will find room/article that represent rooms and FF&E items.
These contains only a @ref attribute that reference the same item in the /drofus-xml/roomcontainer or /drofus-xml/article-container, see below.
In addition, the level node may contain a /drofus-xml/level/cost or /drofus-xml/level/areasum that contains FF&E cost or room area sums depending on the report type.
6.3.
ROOM
Page 40
In addition, the room may contain room/property nodes that represent additional
properties (extra room core attributes). These are also in the core as attributes but are
represented as node in addition to enable project independent access (as you can iterate
through all property nodes, but if you are making a project dependant report it is easier to
pick a core attribute directly)
Below the room you will also find:
room/rds: The room data sheet. See 6.5 for more details on how this is organized.
6.4.
Page 41
article/core/@reference: Reference
article/ equipment-specification: Contains the specification for the FF&E item, se 6.5
for more info)
article/occurrence-list: Contains the occurrences of this article in room. See
room/occurrence-list for more information.
o article/occurrence-list/room/@ref: A reference to the room in the /drofusxml/room-container.
6.5.
The dynamic GUI is exported as a tree with one or more flags that has groups that has
elements that has fields. It has the same structure as when you edit it in the dynamic GUI
editor.
The image below explains how it is exported:
Page 42
Please note that the XML is not ordered in the same order as you see it in the client, but
the position attribute has this information and you should use this to order the data in your
reports.
Each element has a @label that defines the label of the element. For fields it also has an
attribute @show-label. If this is 1 the label is shown before the value in the GUI, if it is 2
the label is shown after the field.
Field has the attribute @data-type which tells if the field is a logic (checkbox), numeric,
option (combobox/radiobox), date, html (formatted text) or text. Each field also has a
@value which contains the language specific and human readable value.
If field has @data-type = logic the @value will contain a language dependent Yes/No
value. It also has a attribute @db-value which is independent of value and will be either
true or false.
If field has @data-type = html (formatted text) the @value will contain the text value as
"normal" unformatted text. In addition it will have a child element html-data that contains
the html data.
See the sample building block dynamic-gui-bb.xfc for example usage.
Addressing specific fields and values
In the samples and building blocks included the dynamic GUI values is processed in the
order they are structured in the XML file. This layout will adapt if data changes but is
limiting if you want to control exactly where specific flags, groups or fields are printed. If
you want to get a specific field value from the dynamic GUI data dragging and dropping
from the XML data tree will generate the following XPATH
flag/group/element/field/@value
This is unfortunately no good because it will match all field values and not the specific one
you are after. To achieve this, you have to add some conditions for which flag, group,
element and field you want. Each element in the structure has a number that is used as
identification (e.g. flag-no, group-no etc.) so we use this to address the field we want e.g.:
flag[@flag-no='10']/group[@group-no='10']/element[@group-elementno='11']/field[@field-no='10']/@value
This will get field in flag with no 10, group 10, element 11 and field 10.
Be aware that when doing this the report will not work if you move the field to for instance
a different group or you run the report on a different project where the UI is not the same.
Page 43