Introducing Bookmarks

Introducing Bookmarks

Logi Info
Updated: 11 Dec 2014
For version: 11.4.046 SP2

Page 1

1 | 2

Bookmarks provide a mechanism for storing and re-using the request parameters, user input data, and configuration choices made by report users at runtime. Topics in this document include:

 

About Bookmarks

Depending on how they're developed, Logi reports can offer users many opportunities to customize their reports at runtime. Developers can include user input controls and "super-elements", such as the Analysis Grid, in the reports. Super-elements have their own user interface and give users a lot of freedom to work with data, arrange table columns and rows, and add charts to their reports.

However, the time users invest in configuring their reports may be lost when their session ends. Logi "bookmarks" allow these settings to be saved, on an individual user basis, so users don't have to re-configure their reports each time they view them. Bookmarks can save the following:

  • Values selected in user input controls
  • Session variables and link parameters
  • Super-element UI configurations

When a bookmark is created, it essentially "vacuums up" all the values that will become Request parameters, all super-element UI configuration settings, and all session variables (v10.0.428+) and saves them in an XML data file. The contents of the file can be "replayed" at runtime to recreate the report, with all of its selections and settings intact.

 Bookmarks will not work with values passed using a Target-type element's Request Forwarding attribute. When this attribute is used, request variable values are not passed in a query string so they will not subsequently be available to be saved in a bookmark. To achieve the desired results, instead of using Request Forwarding, use a Link Parameters element to send request variable values to the target report.
 

Bookmark Types and Scope

Manual bookmark functionality, which uses special Action.Bookmark elements, is report-wide in scope. All of the values listed above be saved. If a report definition includes two super-elements, the UI configuration values for both of them will be saved.

The special bookmark Action elements are available as children of Label, Button, Image, and other elements that can be used to initiate actions. These special elements are discussed in more detail in a later section.

Automatic bookmarks provide similar functionality but their scope is limited to recording the configuration details and parameters of their parent super-elements. These details are saved automatically every time a user makes a change in the super-element user controls. This makes working with bookmarks extremely easy. The Auto Bookmark element is available as a child of several super-elements and its use is discussed in a later section.

You can use either manual or automatic bookmarks in a report, but not both.
 

Bookmark Data

Regardless of type, bookmark data is stored in one or more XML data files, called a "Bookmark Collection" and, typically, there's one collection per user. The developer specifies the storage location and ID of the collection. If Logi Security is being used, these files can be named using the @Function.UserName~ token, thus tying the bookmark collection files to an individual user.

Bookmarks are identified by report name and a description. Special elements, discussed later, are available so developers can create their own Logi applications to manage bookmarks.

The Bookmark Organizer element allows users organize bookmarks into folders and sub-folders, which can be shared with other users.

Working examples of the Bookmark elements can be seen in our sample application.

  Back to the top

 

Adding Manual Bookmarks to a Report

Adding manual bookmarks to your report is easy and the following examples provide step-by-step guidance. First, ensure that your report is a good candidate for bookmarks: it needs to include a super-element and/or some kind of user input selection that affects the displayed data. A simple report that just executes a SQL query and displays the entire results in a data table is not a good candidate, for example.
 

     

  1. In Studio, open your application's _Settings definition and select the General element.
     
  2. If using v11.4+, set the Bookmark Collection Default attribute to the name for the bookmark data file. Do not include a path or .xml file extension. If you're using Logi Security, you can use the @Function.UserName~ token to individualize the collection; if not, enter some other value of your choice.

     In general, specifying this value here and leaving the corresponding attributes blank in individual bookmark-related elements is good practice. If necessary, you can override this value by providing one in those other elements.
     
  3. Set the Bookmark Location attribute value to the name of a folder, underneath the Logi application root folder where you want the bookmark files to be stored. You can use a token for the root folder here, as shown above. Don't use the system rdDataCache or rdDownload folders as these are periodically "cleaned up" automatically.
     
  4. If it doesn't already exist in the file system, create the bookmark location folder and be sure it inherits all the file access permissions of the application root folder.

     
  5.  

  1. In the report definition you want to add bookmark features to, make a note of the element ID of any user input elements whose values you want to save. In the example shown above, there's an Input Select List element with an ID of "inpCustID" that we want to save.

     

  1. In an appropriate place in the definition, add a Label, Button, Image or similar element, which will become the "Save Bookmark" link, as shown above.
     
  2. Beneath it, add an Action.Add Bookmark element. Unlike most Action elements, it needs no Target element.
     
  3. If using v11.4+, you can leave the Bookmark Collection attribute blank, unless you want to override the default value set in the _Settings definition.

    If using a release prior to v11.4, set the attribute value to an arbitrary name for the saved bookmarks XML data file. Do not include a path or .xml file extension. This file will be created in the location identified in the _Settings definition in Step 1. This is the attribute value where, if the application uses Logi Security, you can create user-specific bookmarks collections, by entering the @Function.UserName~ token.
     
  4. Set its ID attribute to a unique ID. This is very important, especially if you have multiple reports with "Save Bookmark" links in the same application.
     
  5. Set its Bookmark Name attribute to a meaningful name, usually the name of the report. This value can be used later, along with the Description, to identify individual bookmarks.
     
  6. Set its Bookmark Request Parameter IDs attribute to a comma-separated list of one or more element IDs for user input control elements or link parameter IDs. In the example above, the element ID from Step 4 is entered. These identify the values to be stored in the bookmark; any value from this report that would be referenced in a subsequent report using an @Request token can be identified here.

That's all it takes to save bookmarks. Run the report, click the Save Bookmark link, and inspect the files created in the specified bookmark file location. Assuming a bookmark collection name of "MyBookmarks", you should see:
 

The first file is the main bookmark file and will always be present. The other files, with a GUID as part of their names, are referenced in the main file and contain information about any super-elements in the report. These may nor may not exist, depending on your report definitions.

Here are the other Action.Add Bookmark element attributes you might want to use:
 

Attribute Description

Bookmark Custom Column 1
Bookmark Custom Column 2

Specifies a custom value to saved in the bookmark, which will be returned by DataLayer.Bookmarks. This could be use to provide additional information or datalayer filtering.
Bookmark Description

Normally, when saving a bookmark, the user enters a description of their own. This attribute value specifies custom default description text.

Bookmark Description Message

Specifies the prompt text for the description in the bookmark "save" dialog box. When this attribute has a value and the bookmark link is clicked at runtime, a dialog box will open prompting the user to enter a description, which is saved in the bookmark. If this attribute has no value, no dialog box will be displayed when the link is clicked.

Bookmark Save Caption

Specifies a custom caption for the Save button that appears in the bookmark dialog box. The default caption is "Save". (v10.0.479+)

Bookmark Session Parameter IDs

Specifies one or more Session variables names, in a comma-separated list, to be saved in the bookmark. For example, to save the value of the token @Session.UserID~, you would enter UserID here. (v10.0.428+).

If you use the Metadata Builder Wizard's Custom Tables feature and include Session tokens in its SQL queries, you should enter the session variables here. For example, if the query uses tokens like @Session.CustomerID~ and @Session.OrderID~ then enter CustomerID,OrderID here.


  Back to the top

 

Adding Automatic Bookmarks

Adding automatic bookmarks to your report is easy and the following examples provide step-by-step guidance. First, ensure that your report is a good candidate for automatic bookmarks: it needs to include one of the super-elements listed in the earlier About Bookmarks section. Remember that automatic bookmarks do not record values for user input controls outside of super-elements.

 

     

  1. In Studio, open your application's _Settings definition and select the General element.
     
  2. Set the Bookmark Collection Default attribute to the name for the bookmark data file. Do not include a path or .xml file extension. If you're using Logi Security, you can use the @Function.UserName~ token to individualize the collection; if not, enter some other value of your choice.

     In general, specifying this value here and leaving the corresponding attributes blank in individual bookmark-related elements is good practice. If necessary, you can override this value by providing one in those other elements.
     
  3. Set the Bookmark Location attribute value to the name of a folder, underneath the Logi application root folder where you want the bookmark files to be stored. You can use a token for the root folder here, as shown above. Don't use the system rdDataCache or rdDownload folders as these are periodically "cleaned up" automatically.
     
  4. If it doesn't already exist in the file system, create the bookmark location folder and be sure it inherits all the file access permissions of the application root folder.
     
  1. Add an Auto Bookmark element as a child of the target super-element, as shown above.
     
  2. You can leave the Bookmark Collection attribute blank, unless you want to override the default value set in the _Settings definition.
     
  3. Specify a unique Bookmark ID to differentiate this bookmark in the collection. This value will be incorporated into the bookmark file names, so don't use any exotic characters here that the web server file system considers invalid in file names.
     
  4. With the exception of Allow Shared Bookmark Updates (discussed later), the rest of the element's attributes are identical to those for Action.Add Bookmark but, of course, without those for the Save Bookmark dialog box user interface. Refer to the table in the previous section for information about these attributes.
     
  5. The last thing you need to do to initiate automatic bookmarks. This is done by calling the report with rdLoadBookmark=True in the query string. One way to do this is by using Link Parameters with the link that calls the report.

Now you can run the report and manipulate the super-element interface. After that you can inspect the files created in the specified bookmark file location. Assuming a bookmark collection name of "MyAutoBookmarks", you should see:

 

The first file is the main bookmark file and will always be present. The other file, with Bookmark ID you specified as part of its name, is referenced in the main file and contains information about the super-element in the report. It will appear once the super-element UI is manipulated.

Here are some additional important usage tips:

 

To automatically generate the Bookmark ID: If you want the application to generate the Bookmark ID automatically, using a GUID, as shown above, leave the element's Bookmark ID attribute blank and call the report with rdNewBookmark=True in the query string.

With Report Center Menu: If the report includes a ReportCenter Item element, the automatically-created bookmark will be listed with the ReportCenter Menu element.

With Dashboards: If using Auto Bookmark with a Dashboard, do not set the Dashboard element's Save File attribute. The bookmark will in effect become the dashboard's Save File.

  Back to the top

 

Organizing Bookmarks

Users may want to group and organize the bookmarks they create. The Bookmark Organizer element allows users to place their bookmarks into "bookmark folders" at runtime.

A bookmark folder is not an actual folder in the web server file system; instead, the bookmark data is referenced in the master bookmark data file in a hierarchy that creates "logical folders". The Bookmark Organizer lets users manage bookmarks and folders. Multiple bookmarks can be collected into a folder and folders can have sub-folders.
 

Runtime Display and Manipulation

The Bookmark Organizer displays the bookmark folders and works with a Data Table element, in the same definition, that lists the bookmarks. Clicking an entry in the data table runs the bookmarked report. When a folder is clicked, the data table is refreshed to show the contents of that folder. Folders can be created, renamed, and deleted, and bookmarks are organized by dragging them into folders. Here's an example:

 

The example above shows a Bookmark Organizer and its companion data table. They can be physically arranged on the page however you desire, and theme selection and/or styling can vary their appearance.

The example shows the default "My Items" bookmark folder and several sub-folders created by the user. When bookmarks are first created, they're placed in the My Items folder by default. The "gear" icon appears when the mouse hovers over a folder and allows you to add new sub-folders, and rename or delete sub-folders. The data table displays the bookmarks in each folder (the selected folder name is shown in bold text).

 

To move a bookmark from one folder to another, the user just drags the data table row's drag icon to the desired folder, as shown above.
 

Sub-folders can also be rearranged into other folders by clicking their folder icon and dragging, as shown above.
 

Implementation

As mentioned above, to implement this you'll need to add a Bookmark Organizer element and a companion Data Table element. Here's how:

  1. Implement manual or automatic bookmarks, as discussed in earlier sections.

     

  1. Include a Bookmark Organizer element in your report definition (one possible arrangement is shown above). Set its Data Table ID attribute to the element ID you'll give its companion data table.



  2. Add the companion Data Table, as shown above, and ensure its ID matches the one entered in the previous step.




  3. Add a DataLayer.Bookmarks element beneath the data table, as shown above. Unless you want to override the Bookmark Collection Default value set in _Settings.lgx, you can leave the collection name blank here.




  4. Add a Compare Filter beneath the datalayer and set its attributes as shown above. The Bookmark Organizer element automatically creates and updates the session variable rdSelectedFolderID each time the user selects a folder, so this filter causes the data table to only show the bookmarks in the selected folder.




  5. Add Data Table Column, Image, and Action.Drag Bookmark elements, as shown above. If you prefer, you can use a Label or Button element instead of the image. Set the action element's attributes as shown.

     If you want to use the standard "drag icon" image - - provided with Logi Info, enter the following for the Image element's Caption attribute value: ../rdTemplate/rdBookmarkOrganizer/rdDragHandle.png




  6. Enter one or more Data Table Column and Label elements, as shown above, to display information identifying the bookmarks.




  7. Finally, in order to actually run the bookmarks, add an Action.Run Bookmark element beneath the Label element and set its attribute, as shown above. (The Bookmark User Name attribute was added in v11.4.046 SP2).

     

When run, with the Clarity theme applied, this simple example looks like the image shown above. The bookmark can be dragged into any of the folders and clicking its bookmark description will run the report and apply the bookmark.

 

  Back to the top

1 | 2


© copyright 2007-2015 Logi Analytics, Inc. all rights reserved