Purpose
Publishing is a module in the Perfion application that orchestrates the generation of reports and compiling them into a single result. Publishing is appropriate when the output contains many pages and the pages can be broken up into discrete chapters.
Publication provides control over of processing, the side an inner report starts and also the assembly of indexes.
Simple example
The following example highlights Publishing for a simple case.
In the image below, you can see a categorizing structure has been assembled for the purposes of Publishing.
In the structure shown above, the publishing system will run internal reporting on all the items that have a CatalogTemplate entry. Each time internal reporting is activated, it derives the report template to use from the value in the CatalogTemplate column.
In the example above internal reporting will be activated six times with the following reports:
Frontpage Report, run against the Frontpage item
Index Report, run against the Index item
Content – Sporty Report, run against the Sporty item
Content – Normal Report, run against the Family Cars item
Content – Normal Report, run against the Executive item
Terms and Conditions Report, run against the Terms and Conditions item
The corresponding Reports folder would contain the following:
After each report has been generated, the results are aggregated into a publication. Then the publication is presented in the report viewer.
A Publication can be invoked by right clicking in the Publishing hierarchy and selecting Publishing->Publish… from the context menu.
Key Concept
The publication module can be thought of as a person whose role is to execute a series of reports in an order, then collate the results into a single output.
The task list for the publication module is provided in the form of a Publishing structure, and in the items of the publishing structure are the names of the reports to run.
Setup
The Publishing module is controlled by the data from two Features. The CatalogTemplate Feature is mandatory and is used to direct the publishing module to a report to execute. The CatalogPage Feature is optional. This Feature is used to supply the Publishing module directives on how to process the current report in terms of its page side and page number.
Setup of CatalogTemplate Feature
For publishing, it is mandatory that you have a feature named CatalogTemplate. The CatalogTemplate feature should be created as a String and made Selectable.
Enter the names of your reports into the Feature Data area for the CatalogTemplate. These names should match exactly to the names given in the Perfion Reports directory.
The following is an example of how the values might look:
Setup of CatalogPage Feature
The CatalogPage Feature is optional in Publishing. When used, it indicates to the Publishing module on how it handle pages of the associated CatalogTemplate report. For example a CatalogPage value could be used to indicate that the associated report should start with a specific page number or perhaps that it should start on a left side page.
Create a String Feature called CatalogPage. Depending on the usage you might make this Feature Selectable.
If you want to direct the Publication module to change to a specific page number during the creation process, then not Selectable might be best. This is so the user can type in a page number.
If however, the primary requirement is to control the Left / Right starting point of chapters, then Selectable would be best. If, both scenarios are required, then not Selectable would be appropriate.
The usage of CatalogTemplate and CatalogPage features are described below in Working with Catalog Templates and Forcing a page to left or right sides.
CatalogPage accepted values:
Value | Command | Description |
{nn} | Set current page number | An integer page number. This will represent the page number to continue counting forward with from this point onwards. |
Left | This chapter should start on the left side. | This will insure that the chapter is collated into the publication as a left page. It will insert a page into the publication if necessary. |
Right | This chapter should start on the right side. | This will insure that the chapter is collated into the publication as a right page. It will insert a page into the publication if necessary. |
Optional | This indicates an optional insert page. | A single page report can be indicated as optional. It will only be ‘optionally’ used if the following chapter is marked as Left or a Right and an insert page is required. An optional page can also be specified at the end of a publication. Here it is used to fill out the end pages, if the publication is to be made with a Booklet layout. |
Setup of a feature that represents the structure of the publication
A Feature should be created that represents the structure of the publication. A typical example of this Feature is as follows:
Organizing the structure to follow the organization of the physical output is considered a best practice.
Example publication structure
Launch the configuration editor for the publishing feature and add CatalogTemplate and CatalogPage to its configuration. Additionally, add the two features to the Family, Item view. This will make editing their values easier from the grid.
Setup Recap
Publishing is setup by creating two Features CatalogTemplate and CatalogPage. A publication feature needs to be created to represent the structure of the publication. The publication feature needs to be configured with the CatalogTemplate and the CatalogPage features.
CatalogTemplate values needs to be added that match the reports names that you have for the publication.
Link products into the chapters of the publication. Finally, select the reports you wish to run against each chapter by setting the CatalogTemplate values respectively. After these steps you are ready to run a publication. This is available from the context menu such:
Working with CatalogTemplates
When a report is specified on the publication via a CatalogTemplate value, then the reporting system will be invoked with the report that match the CatalogTemplate value.
The matching will be done on the report name. As of Perfion version 2020 R2 SR2 (4.8.6), reports are looked for both eternally and internally.
If there is no CatalogTemplate value for an item, then that item will not be included in the publication.
In the example above, Chapter 2 will not be included in a publication because there is no CatalogTemplate value for it.
Reports are executed at the point the CatalogTemplate value is defined
When CatalogTemplate is Inheritable, then its value is projected down on its children. You can see this in the above example for Chapter 1. The publishing module will only run the report at the top level. So in the example above, the Chapter 1 Template is only once against Chapter 1, and not a second time against detail.
A CatalogTemplate Report always starts on a new page
When a CatalogTemplate is specified, the report that is executed will always start on a new page. Content that should flow together should be contained in the same report.
Forcing page numbering
Page numbers in a publication can be changed at any point. This can be useful if there is a postproduction step to be made on the final pdf publication. An example could be where there are some inserts that are to be made.
To force an alteration to the page numbering, page number can be entered into the CatalogPage feature value.
In the example above, the page number will be reset to 10 at the start of Chapter 1.
The report designs need to take into account that they will be used within a publication. If a page number is required, then a text label should be used for it with its Tag property set to PageNumber. Page Info control, that would normally be used will not be updated by the CatalogPage directive.
Forcing page to left or right sides
The publishing system is able to insert an optional or a blank page in order to ensure a CatalogTemplate report starts on a Left or Right page if desired.
Left/Right control is achieved by used the CatalogPage feature value.
When a CatalogPage has a value of Left or Right, then the CatalogTemplate report will be inserted into the publication on the required side. For that to happen the Publication module may have to insert a page.
Left Right order
In publishing the front page is considered on the right. Following this, the pages that follow swap from side to side. When a left/right directive is used it is calculated based upon the first page being on the right side.
A common misunderstanding is that the page number set by CatalogPage is used to control the Left/Right directive. This is not the case, it is simply controlled by the first page is right, then next is left and so on.
Controlling the page used as an Insert
When the publication module has to insert a page, it will use a blank page unless an insert page has been indicated.
To indicate an insert page to the publication system, the Optional directive can be entered against a CatalogTemplate.
In the example above, Chapter 1 should be inserted on the Left side. If an insert page is required to do this, then the Blank Page Template will be used.
It’s important to remember that an optional item will ONLY be used when a non-optional item requires a page to be inserted.
Designing reports to work with Publication
Reports for publishing work exactly the same as regular reports.
That said, there are a few extra items that can be added to help the publishing system.
IndexMarker
The purpose of the IndexMarker is to supply the Indexes that are generated during publication with details of where rows are used in the report.
The index marker is a transparent Label that should be added to the report where the most detail is included. Typically, this is in the detail band. Sometimes the detail band is not used because of grouping, and in this case, it would be the most detailed grouping band.
The index marker should be added and given a transparent foreground so this it is not visible. It should have its Tag property set to IndexMarker. The text value for the label should be set to: [Structure.CatalogID]:[Structure.ItemID]
Setting its Height to 5 and to Can Grow to false will make it as small as possible on the design surface.
PageNumber
The purpose of the PageNumber is to output the correct publication page number.
The PageNumber label should be placed in the design at the location the page number should be shown. The label should be set with the Tag property of PageNumber. The Text property can be set to blank, as it will be filled in by the Publishing module.
By using the PageNumber label, the page numbering will follow the directives applied by the CatalogPage feature.
Working with Indexes
An index in the publication module is a special type of report. The data that is supplied to the index contains data for the publication as a whole. In this data there are also details of which pages the data was used on.
Before a report can be used as an Index, it must be marked as a PublicationIndex. This is achieved by adding an entry into the OutputsParameters section of Reports view.xml file.
Here is an example superquery that specifies the report as an Index:
| Code Block |
|---|
<SuperQuery> <Query> <Select languages='EN' view='CatalogRoot,Virtual,Normal,Branded'> <Feature id='*' view='Config' /> </Select> <From id ='Publishing' /> </Query> <Query> <Select languages='EN' view='Normal,Branded'> <Feature id='*' view='Config' /> </Select> <From id ='Product'/> </Query> <OutputParameters> <Parameter id='PublicationIndex' value='true' /> </OutputParameters> </SuperQuery> |
_PageIndex special Value
There is a special data field present in Indexes. The _PageIndex is available in the Structure table and contains the page index where data is used in the publication. Said differently, only rows that have one or more of their values outputted into the publication will have a _PageIndex value.
Reducing the data to entries that appear on a Page
When working with the data supplied into an index, it is normal to reduce it to just the data rows that actually are used on the output pages.
Select the Catalog in the report Explorer, then apply following Filter String [_PageIndex] Is Not Null
One Once the data has been reduced, It is possible to create groups based on values in the publication (including _PageIndex) if you want items in page order.
TIP: Before an Index can be previewed correctly, the publication should be run once. This will generate the data that is supplied to an Index.
| Info |
|---|
NOTE: Indexes require that the publication reports have been setup with the IndexMarker label. See the section about IndexMarker. |
| Info |
|---|
NOTE: Applying this Filter String is also necessary for the page numbers to appear in the index. |
Setting up One Click Publications
One click publications is a feature of the Publication module where all of the input parameters to a publication can be stored in the database. When a user selects the publication, then the publication module can proceed without interaction from the user.
In the example above, there are two one click publications available:
Publish_EN
Publish_DE
The name should give some clue to the user about the parameters it sets up.
One click publications are configured in the Publications menu that is found within the Reports menu. To find this, select Tools -> Reports -> Publications.
The editing UI for the publication looks like this:
| Example | Options |
Execute action | View publication | Show options, View publication, Export publication |
Languages | EN | User languages |
OutputFormat | Html, mht, rtf, image, xls, xlsx, csv, text, pdf | |
TemplateChoice | Colorful |
|
ImageResolution | High | Low, Medium, High |
BookletPages | 4 |
|
Publication with template extension
Template extensions are a mechanism of varying the report templates that are selected during the publication process.
A template extension value can be supplied in a publication xml file through one click publications described above.
When a TemplateChoice is supplied, then the Publication module will construct an alternative report name for each of the reports specified by the CatalogTemplate values. The alternative name is constructed by concatenating the TemplateChoice value to the CatalogTemplate value, delimited by an underscore.
The publication module will attempt to load a report template using the extended name. If a report template is found then it is used instead of the default. If it is not found then the system falls-back to using the original name.
Consider the following structure:
If a TemplateChoice of Colorful is used and a report folder called ‘Chapter 1 Template_Colorful’ is found then this will be used instead of ‘Chapter 1 Template’.
Using Remote values and variants from a Publication
When you run a publication, only default values can be supplied to the reports. There is no opportunity for a dialog to be presented to the user for each report executed.
These default values are obtained from the reports superquery, for example:
| Code Block |
|---|
<SuperQuery> <Query> <Select languages='EN' view='CatalogRoot,Virtual,Normal,Branded'> </Select> <From id ='Category' /> </Query> <Query> <Select languages='EN' view='Normal,Branded'> <Feature id='*' view='Item' /> <Feature id='NetPrice'> <Parameter id='@CustomerNo' dataType='String'>100204</Parameter> <Parameter id='@Dataarea' dataType='String'>AU</Parameter> <Parameter id='@Pricedate' dataType='Date'>1/1/2014</Parameter> </Feature> </Select> <From id ='Product'/> </Query> </SuperQuery> |
In the example above the parameters for the remote values are filled out with defaults, these default values will be taken during publishing.
It can also be useful to setup different variations by using the TemplateChoice mechanism described above.
Booklet Layout
Booklet layout is a mode where a publication output is guaranteed to be collated into a booklet form. If this option is selected, then it may require the insertion of extra pages at the end of the publication.
By default any extra pages will be blank pages. It is possible to select a specific page as the insert by specifying an optional page as the last entry.
Bookmarks
Bookmarks are merged into the publication from each of the CatalogTemplate reports that are run. Bookmarks that share the same parent across multiple inner reports will be merged.
Watermarks
Watermarks can be setup per report and will be preserved into the final publication.
Report Background Colour
Perfion reports can only have one background color due to constraint in the report component used.
When publishing is used several reports are merged to one final publish report and the background color of this final report is either white if several different colors are used in the reports or the common color used in the reports if same background color used.
If several background colors is needed in the reports a workaround exists in adding a watermark for each report and use an image stretching whole paper with the wanted color.
| Table of Contents |
|---|