Transcript
1.1.
CREATING REPORTS FROM DROFUS WITH XF DESIGNER Version 1.2
T AB L E O F C O NT ET 1.
INTRODUCTION ......................................................................................................5
2.
GETTING STARTED................................................................................................6
2.1. INSTALLING XF DESIGNER ...................................................................................6 2.2. USING THE SAMPLE PACKAGE ............................................................................6 3.
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.
IMPORTING REPORTS TO DROFUS ...................................................................20
4.1. EXPORTING TEMPLATE FROM XF DESIGNER ..................................................20 4.2. IMPORT REPORT TEMPLATE TO DROFUS ........................................................20 5.
EXAMPLE REPORTS ............................................................................................22
5.1. REPORTS ..............................................................................................................22 5.2. BUILDING BLOCKS ...............................................................................................29 5.3. CREATING INDEXES ............................................................................................37 5.4. STYLESHEETS .....................................................................................................38 5.5. VIDEO TUTORIALS ...............................................................................................39 5.6. MARGIN AND PADDING PITFALLS ......................................................................39
6.
DROFUS XML DOCUMENTATION........................................................................40
6.1. GENERAL ..............................................................................................................40 6.2. LEVEL ....................................................................................................................40 6.3. ROOM ....................................................................................................................40 6.4. FF&E ITEM / ARTICLE...........................................................................................41 6.5. DYNAMIC GUI (RDS, FF&E SPECIFICATION)......................................................42
Creating reports in dRofus with XF Designer
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
Creating reports in dRofus with XF Designer
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.
1
eXtensible Markup Language
Creating reports in dRofus with XF Designer
Page 5
2. G ET T ING ST A RT ED 2.1.
INSTALLING XF DESIGNER
The tool and license can be found at http://www.ecrion.com/products/xfdesigner/overview.aspx.
2.2.
USING THE SAMPLE PACKAGE
You can download a sample package, containing example reports and data sets and this document, from http://www.drofus.com. The sample package contains:
dRofus XFDesigner UserGuide.pdf: This document.
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
Images: Images used in the samples.
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
Creating reports in dRofus 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:
Image 1: Exporting XML from dRofus
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 don’t need this in version 16 (currently beta).
Image 2: XF Designer User Interface
3.2.
BASICS USAGE
The XF Designer consists of the following important elements: 1. The document: This shows the design of the document and can be edited directly similar to a word processing tool 2. Navigation bar: Shows the currently selected element/section in the document and lets you navigate to an element in an easier way than using the 1 if the element has a small or no visible space. 3. Data source: You can browse and drag and drop data from the data source on to the document. Here you can also see the page layout and page sets. To see the page sets check the "Pagination" option in View→Show/Hide. 4. Properties pane: Detailed properties for the selected element in 1 or 2 5. Ribbon menu
Creating reports in dRofus with XF Designer
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.
UNDERSTANDING XPATH EXPRESSIONS
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
refers to all the room nodes under the room-container node, in this case two rooms. You use this kind of XPath expression when you want to do something for each room in the XML. If you want to get a specific attribute value, such as the value of the project name attribute, you can use /drofus-xml/property-set/@project_name
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)
returns the number of rooms in this document, 2.
3.4.
COMMON W AYS TO CREATE A R EPORT
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.
Creating reports in dRofus with XF Designer
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.
CREATING A REPEATING SECTION
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.
Image 3: Edit Xpath expression window
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.
CREATING A REPEATING TABLE
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.
STYLE FORMATTING(FONT, WEIGHT ETC)
You can format your text in the report in three different ways:
Use the Home → Font menu options
Creating reports in dRofus with XF Designer
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.
DATA FORMATTING A FIELD ( DATE, NUMBERS)
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.
USING BUILDING BLOCKS
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.
Creating reports in dRofus with XF Designer
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.
UNLOADING BUILDING BLOCKS
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.
CONTEXT OF BUILDING BLOCKS
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.
PAGE LAYOUT AND PAGE SET
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:
Creating reports in dRofus with XF Designer
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:
Left. Region rotated 90 degrees
Body. This is where the content of the report flows… Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam imperdiet rhoncus est id gravida. Nullam sem arcu, mattis sed elementum vel, posuere venenatis justo. Phasellus libero arcu, congue ut hendrerit vitae, lacinia sed mi. Nunc sed ultricies velit. Curabitur nec tincidunt nibh. Vestibulum gravida porttitor leo, ac lobortis urna tincidunt sed. Morbi posuere pulvinar tortor……
Right. Region rotated 270 degrees
Header
Footer, with "precedence" checked You can edit the page layout by either double clicking on it in the pagination window or selecting an option from the menu: Page Layout →Layouts In the page layout properties window, you can define both the page size in general (in the Page properties) and the size of the different regions. Important: The body region (where the main content of the report is added) does not have a size (the page has it), but it has margins and padding. The margin is the total margin from the page size to the body content. So if you for example would like to have a header that is 3 cm high (Extent) you need to set both the extent of the header and make sure that the body has a top margin of at least 3 cm. Otherwise, the content of the body and header would overlap. If you check the precedence option for the header or footer it will fill the total width (precedence over the left and right regions):
Creating reports in dRofus with XF Designer
Page 14
Two column page layout You can let the body region of a layout flow in two columns. This can be used to both show more information in a single page or to e.g. setup a report with different elements in two columns. You can set the number of columns from the menu Page Layout → Columns or in properties for the Page Layout select the Regions tab and Body region "Column count". Edit footer / header Each page layout has a header and a footer you can edit and add content to. You can edit the content of the header and footer by either double clicking in the header/footer area of the page with the page layout you would like to edit or you can choose which page layout to edit from the bottom part of the menu option: Page layout → Layouts → Edit page layout. Page set A page set is where you define the content of your report and where you normally add the xml. Usually you apply one page layout to all the pages in a page set, but you can also add two different layouts and let one layout be for the first page and another for the rest.
Creating reports in dRofus with XF Designer
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:
Creating reports in dRofus with XF Designer
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.
ITEM INFORMATION IN HEADER/FOOTER
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.
Creating reports in dRofus with XF Designer
Page 17
3.15.
IMAGES FROM XML AND STATIC IMAGES
Images from dRofus (in XML) If you would like to use images from dRofus in your report, you cannot drag and drop them in, but need to go to: Insert → Graphics →Image. Select the "…" button on the right of the "File Url":
Select the xml element based on your context to get the path:
And press OK. Defining max width and height of images from XML To control the size of the image we can resize the image in design view, but this will not be good enough, since the size of the room core is not actual size from the building block and we need to set a max width/height. The way to do this is to get the size you would like to use by changing the size in designer mode. In order to free form both width and height
Creating reports in dRofus with XF Designer
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.
Creating reports in dRofus with XF Designer
Page 19
4. IM PO RT ING R E PO R T S T O DRO FU S 4.1.
EXPORTING TEMPLATE F ROM XF DESIGNER
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.
IMPORT REPORT TEMPLATE TO DROFUS
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
Creating reports in dRofus with XF Designer
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.
Creating reports in dRofus with XF Designer
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/)
FF&E list grouped Filename: Level XML from report: XML sample file: Key concepts
FF&E list grouped.xfd Advanced FF&E -> FF&E lists -> FF&E list grouped by FF&E level xml/ffe_with_cost.xml Dynamic indentation, condition, table repeat, key/index
This report demonstrates how to print the hierarchical FF&E catalog structure with FF&E items. The report traverses the
structure that represents the FF&E catalog structure. To do this we have a repeating section over the nodes. It is important to note that 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 nodes at the top level, not the sub levels. To get this done we use an expression that will select all nodes in the document regardless of where it is placed in the XML structure. This expression can be: //level
Creating reports in dRofus with XF Designer
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 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 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.
This will index all nodes based on the id attribute. To create a table column, e.g. the FF&E no column, choose Insert->Field and enter the following XPATH expression key('article-index', @ref)/core/@article_func_no
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.
Creating reports in dRofus with XF Designer
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 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 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 hierarchy which represents the functional structure. In this we will find all the same rooms as in the 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.
This will index all 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...
Creating reports in dRofus with XF Designer
Page 24
Room list by function Filename: Level XML from report: XML sample file: Key concepts
Room list by function.xfd Advanced Room -> Room list -> With area sums xml/rooms.xml Dynamic indentation, condition, table repeat, key/index
This report is almost identical to the FF&E list grouped report described above. Since the nodes in this case represents the room functional hierarchy just as it represented the FF&E catalog structure the 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
Room list by group.xfd Advanced Room -> Room list -> With area sums xml/room per group.xml Dynamic indentation, condition, table repeat, key/index
The Room list by group example is also identical to the FF&E list grouped report in that now the 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
RDS - simple sample, building blocks.xfd Beginner Rooms -> Room Data Sheet xml/rds-datatypes-sample.xml Room info in header, building blocks, dynamic page set
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:
Creating reports in dRofus with XF Designer
Page 25
RDS – simple sample, building blocks with FF&E list Filename: Level XML from report: XML sample file: Key concepts
RDS - simple sample, building blocks with FF&E list.xfd Beginner Rooms -> Room Data Sheet xml/rds-datatypes-with-ffe-sample.xml Room info in header, building blocks, dynamic page set
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
RDS - simple sample.xfd Beginner Rooms -> Room Data Sheet xml/rds-datatypes-sample.xml Room info in header, dynamic page set
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
RDS - cafeteria sample, 2-column with images.xfd Medium Rooms -> Room Data Sheet → With pictures xml/rds-cafeteria-sample.xml Layout in two columns. Positioning and including images.
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.
Creating reports in dRofus with XF Designer
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:
RDS - room template simple sample Filename: Level XML from report: XML sample file: Key concepts
RDS - room template simple sample.xfd Beginner Room Templates (or Templates) -> Room Data Sheet xml/ rds-room-template-offices.xml Room info in header, building blocks, dynamic page set
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
RDS - room template simple sample with FF&E list.xfd Beginner Room Templates (or Templates) -> Room Data Sheet xml/ rds-room-template-offices.xml Room info in header, building blocks, dynamic page set
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
Page layout sample.xfd Medium Room → Room Data Sheet OR Equipment list per room xml/rds-datatypes-sample.xml Cover page, different page layout for different part of the document
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.
Creating reports in dRofus with XF Designer
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:
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 don’t 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:
Creating reports in dRofus with XF Designer
Page 28
Dynamic GUI (RDS, FF&E specification) styles and options Filename: Level XML from report: XML sample file: Key concepts
Example of dynamic GUI styles and options.xfd Medium Room -> Room Data Sheet xml/rds-datatypes-layout-sample.xml Building Blocks, Dynamic GUI, Parameters
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
Custom placement of tabs and groups from dynamic GUI.xfd Medium Room -> Room Data Sheet xml/rds-room-template-offices.xml Building Blocks, Dynamic GUI, Parameters
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:
Using CSS styles to modify dynamic GUI report.xfd and Using CSS styles to modify dynamic GUI report-original.xfd Level Easy XML from report: Room -> Room Data Sheet XML sample file: xml/rds-datatypes-layout-sample.xml Key concepts Building Blocks, Dynamic GUI, Parameters, Style Sheets These reports use the dynamic GUI building block to print RDS, but assign a different style sheet (drofus2.css and drofus.css) to show how they report changes. It also contains some tips and tricks if you would like to make your report more compact.
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.
Creating reports in dRofus with XF Designer
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).
Creating reports in dRofus with XF Designer
Page 30
Dynamic GUI Simple (RDS/FF&E specification etc) Filename: dynamic-gui-bb-simple.xfc Level Medium XML context: Any node that has flags, e.g. RDS, equipment-specification etc This will create a table and show all dynamic GUI in a table. All data is presented using one building block which means you can easily modify everything. All the formatting is set in the style sheet for easy manipulation. See chapter 6.5 for how this xml is exported. See 5.4 for description of the different styles used. Note that this does not use the flag and group layout-mode so that all data is presented in the same setup/layout. The building block is created as a table that creates a row for each flag and with flag label using style dyn-flag-header. For each group within the flag it creates a new row with the group label using style dyn-group-header. For each element within the group it creates a new row and shows the element label in the left cell using style dyn-element-label. In the right cell it shows all the fields for the element. Each field has a @label property but in order to know if this should be shown before or after the @value we use an inline condition and look at the attribute @show-label (1=before, 2=after). The field also has a property @data-type which specifies if the field is a logic (checkbox), numeric, option (combobox/radiobox), date, html (formatted text) or text. We use this information to print different values using an inline condition. If @data-type is logic we look at @db-value to show an image of a checked/unchecked check box instead of the Yes/No values. If @data-type is html we convert the html data in order to print the text and keeping the formatting (colors etc) from the database the html value in the child element html-data must be converted. We provide a sample XSL to convert this (reports/xhtml2fo.xsl). In order to use this you must first include this: Go to Review → Template → Global XSLT and add this value:
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:
Creating reports in dRofus with XF Designer
Page 31
Dynamic GUI (RDS/FF&E specification etc) Filename:
dynamic-gui-bb.xfc
This building block is also using: dynamic-gui-fields-bb.xfc dynamic-gui-flag-bb.xfc dynamic-gui-group-description-group-bb.xfc dynamic-gui-group-dyn-field-table-bb.xfc dynamic-gui-group-element-label-column-bb.xfc dynamic-gui-group-general-bb.xfc dynamic-gui-group-layout-selector-bb.xfc Level Medum (Usage), Advanced (Modifications) XML context: Any node that has flags, e.g. RDS, equipment-specification etc Parameter(s) options = see below for description This is an alternative (preferred) to using the dynamic-gui-bb-simple.xfc building block. Look at the sample reports Custom placement of tabs and groups from dynamic GUI.xfd and Example of dynamic GUI styles and options.xfd for how to pass parameters and see the effect of possible options. Instead of one building block that handles flag, group, element and field nodes, it is broken down into several building blocks. It also has logic where it uses different building blocks depending on the XSL report template defined in the Dynamic GUI editor in dRofus (layout-mode in XML) for both flag and group:
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
Creating reports in dRofus with XF Designer
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.
Different group styles The XSL report template styles for flag is mostly about how to layout the groups, but for groups we have more options for how the data is presented. The following styles are supported:
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.
Options to pass to the building blocks Custom element label column width: For all the group styles except flow-group and description-group we print the group element label in a separate column to align the fields (data). The default width of this is 35% of the available width and the rest goes to the data. But in some cases you have very long or very short labels and would like to change this. If Creating reports in dRofus with XF Designer
Page 33
so just pass the option element-label-column-percentage-width=XX where XX is the percentage value for the column (do not include the %). Column width when using multiple columns: If you have a flag or group XSL style with more than one column we adjust this up so that you get a larger % of the available group for the label. Two/three columns style is often used when you have many "simple" elements with e.g. numeric or check boxes, and you therefor need more space for labels (if you have default 35% of the page width for labels and you have a two column then there is only 17.5% of the page width for label). In the case of two/three columns where therefore “automatically” adjust this value. The algorithm we use for this is as follows: two-columns: Label width = (column-width) + ((column-width) * (100-column-width)%). E.g. if column width is 35, then column width of two column = 35 + 35*65% = 58%. In other words - if you have a small percentage for column width then you get a relatively larger width in two columns (but the width in cm is still smaller) than if you already have a large percentage for the column width. Specify columns for dynamic field table: When using dynamic field table the default behavior is to give each field the same relative width. E.g. if three columns they all get 1/3 each no matter if it is a checkbox or a text field. You can pass options to specify the relative size for each column using the option: dyn-field-table-column-width-NN=XX. Here NN must be replaced with the column index and XX is the relative size. If you use this option it is important that you specify enough values for the maximum number of columns that are going to be printed. If you e.g. have one element with four fields and one with three, you must specify four values. The element with three would then only use the first three. Right align numeric data in dynamic field table: If using dynamic field table you can give an extra option: right-align-numeric-in-table=true to make right align numeric values in the column. Important note for dynamic field table: The built in version of this style is much more fragile when it comes to using this style. It expects that all the elements in the group has the same number of fields - and if it does not it will crash. So use this style with care, and if you use it the built in reports might not work. Indentation for disabled elements: In dRofus you can set up the dynamic GUI so that some fields are enabled or disabled depending on if a check box is checked or not. This is a quite common "pattern" and used e.g. to enable a description field. But sometime you also use this to enable/disable all the fields in another element. In that case the whole element is enabled/disabled by another field. In the default reports these elements are not printed at all unless the field is checked. But when using these building blocks they are. The default style for this is that the label is grey (you can modify the style dyn-disabledlabel in the CSS if you would like to show this in another way). But one thing you cannot control using this style is the indentation. To set indentation of elements that are enabled/disabled by a checkbox in another element set: element-is-disabled-bylabelindent=XXyy. Note that this option not only need the value XX, but also the unit yy (e.g. mm, px, pt etc). Creating reports in dRofus with XF Designer
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
Creating reports in dRofus with XF Designer
Page 35
Dynamic GUI for one or more specific flag(s) Filename: Level XML context: Parameter(s)
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 id’s 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:
To get e.g. the FF&E number we do like this key('article-index',article/@ref)/core/@article_func_no
Creating reports in dRofus with XF Designer
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:
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.
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:
Creating reports in dRofus with XF Designer
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.
Creating reports in dRofus with XF Designer
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:
Export data from dRofus and assign it to a report Change the order of a repeating row (order of the rooms).
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:
Create a new report and define page sets and layout
Inserting a building block Customize the report by modifying the style sheet Set properties to block elements Create a custom cover page
5.6.
MARGIN AND PADDING PITFALLS
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 don’t appear in XF Designer but will appear in reports generated on the drofus reportserver.
margin and padding for table cells – it’s best to avoid assigning margins and padding to table cells since they seem to be supported quite differently.
Creating reports in dRofus with XF Designer
Page 39
6. DRO F U S X M L DO C UM ENT A T IO N 6.1.
GENERAL
drofus-xml: This is the root node
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/property-set/@print_date: Timestamp for when the XML was generated. drofus-xml/property-set/@title: Report title
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
Rooms are represented by the /drofus-xml/room-container/room node. This node has a @id attribute that references back to a /drofus-xml/level/room/@ref attribute as explained above. Room core attributes are contained in the /drofus-xml/room-container/room/core node. The content of this will be dependent on the project as also extra room core attributes, group types etc. are included as attributes. Most of the attributes are self explainable but the most important are:
room/core/@room_func_no: Room function number
Creating reports in dRofus with XF Designer
Page 40
room/core/@name: A concatenation of the room_name and description attribute, separated by a comma room/core/@room_name: Room name
room/core/@description: Room description
room/core/@program_area: Program area
room/core/@design_area: Designed / Actual area room/core/@architect_no: Geographical room number
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.
room/occurrence-list: FF&E list / Equipment in room list. o room/occurrence-list/occurrence: Represent an occurrence of equipment in room room/occurrence-list/occurrence/@parent_article_id: If this attribute is present, the occurrence is a sub article occurrence and the id is a reference to the parent article id. room/occurrence-list/occurrence/@priority: The priority of the occurrence. room/occurrence-list/occurrence/article: Reference the article / FF&E item in the article-container room/occurrence-list/occurrence/cost/amount: Contains the net and gross quantity of this occurrence room/occurrence-list/ occurrence/cost/price: Contains the net and gross sum price for this quantity (net/gross count * unit price) room/cost: Contains the sum and count of occurrence/cost with the same nodes and attributes as the occurrence/cost.
6.4.
FF&E ITEM / ARTICLE
Articles are represented by the /drofus-xml/article-container/article node. This node has a @id attribute that references back to a /drofus-xml/level/article/@ref attribute as explained above. Article core attributes are contained in the /drofus-xml/article-container/article/core node. Most of the attributes are self explainable but the most important are:
article/core/@article_func_no: Article number article/core/@article_name: Article name article/core/@price: Unit price
Creating reports in dRofus with XF Designer
Page 41
article/core/@reference: Reference
In addition you will find the following in the article node.
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.
DYNAMIC GUI (RDS, FF&E SPE CIFICATION)
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:
Flag - (tab) E.g. El power Group - E.g. Supply Element - (row) E.g Reserve power - prioritized supply Field - (data element/parameter) E.g. numeric/text/boolean input
Image 4: Dynamic GUI XML
The XML has the structure: Creating reports in dRofus with XF Designer
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.
Creating reports in dRofus with XF Designer
Page 43