Previous Page Next Page

Delivering Messages Between Library Components

Message types

Sending messages

Receiving messages

Example of delivering a message

A message is a carrier of information that can be delivered between library components. It makes the runtime data synchronization possible. For example, you have two library components containing a crosstab and a table respectively, and both have the field Country. When you click any of the Country value in the crosstab at runtime, you want the crosstab and table to be filtered to show data of this country only. To achieve such synchronization, you can send out a filter message from the Country field in the crosstab and make the crosstab itself and the table receive the same message.

Messages can also be defined at runtime in JDashboard. For details see Synchronizing Data Components in the JReport Server User's Guide.

Message types

The messages that can be delivered between library components includes the built-in messages Filter, Sort, and Parameter, and user customized messages. In a customized message, users can specify to send out multiple messages from one object on different trigger events and edit the message information as they want.

JReport provides the following built-in messages:

• Filter
  The message is sent out for asking the message receivers to filter themselves based on the filter condition defined in the message.
• Sort
  The message is sent out for asking the message receivers to sort themselves based on the sort condition defined in the message.
• Parameter
  The message is sent out for asking the library components that contain the message receivers to re-run using the specified parameter values in the message. It has two sub types:
  • Automatic
    This Parameter message type automatically contains all the parameters used in the current library component.
  • Customized
    Using this Parameter message type, you can customize the parameter you want to include in the message.

A message consists of message ID, message name and message value set. A message ID is a natural number. JReport reserves the IDs from 1 to 1000, which are used in built-in messages, so you can only use IDs beyond 1000 to identify user defined messages. A message name is the name of a message. A message value set is a set of key-value pairs. Each key-value pair has one key and one value. A key or a value can be static or dynamic. A key is of String type, and each value has its own data type, which can be Number, Integer, String, Date, Time, Date Time, Boolean or Currency.

Sending messages

An object in a library component can send out different messages when different events occur on it to ask the message receivers to perform specific web actions defined in the messages.

The following objects in the library component body can be used as the trigger objects to send out messages: labels, data fields (DBFields, formula fields, parameter fields, summary fields), special fields, the category axis, legend and data markers of charts, markers and areas in geographic maps, parameter controls, and the Submit button of parameter form controls.

To send out a message:

Select the trigger object, right-click it and click Send Message > Filter/Sort/Parameter/Customize on the shortcut menu (for the Submit button of a parameter form control, only Parameter and Customize are available).

• If Filter is selected, a built-in Filter message will be sent out when the Click event occurs on the object at runtime, which will ask the message receivers to filter themselves using the default filter condition Current Field = Current Value. You can edit the filter condition when specifying the message receivers if necessary.
• If Sort is selected, a built-in Sort message will be sent out when the Click event occurs on the object at runtime, which will ask the message receivers to sort themselves using the default sort condition Current Field Ascending. You can edit the sort condition when specifying the message receivers.
• If Parameter is selected, a built-in Parameter message of the Automatic type that contains all the parameter values in the current library component will be sent out when the Click event occurs on the object at runtime, which will ask the library components that contain the message receivers to re-run using the same parameter values. You can edit the parameter values when specifying the message receivers.
• If Customize is selected, you can define the message by yourself in the Send Message dialog.

  

  1. Check a trigger event in the Events box, then click on the name of the event to select it.
  2. From the Message drop-down list, select the message to be sent out when the selected event is triggered on the object at runtime: 0001 - Filter, 0002- Sort, 0003 - Parameter, or User Defined.
  3. Define the message as you want.

     For the built-in message, you can edit the condition of how to perform the web action bound with the message in the Value column. To make the condition dynamic, select the values under the Dynamic Key node.

     For a user defined message,

     1. Specify the ID and Name of the message in the ID and Name text boxes. The ID should be a natural number beyond 1000.
     2. Click to add a message key-value line.
     3. In the Key column, specify a key from the drop-down list or select the <Input...> item from the list and then input a key into the text box.
     4. In the Value column, specify the value of the key from the drop-down list or select <Input...> from the list and then input a value into the text box.
     5. If you choose to input the value by yourself in the above step, you need to specify the data type of the value. If the value is selected from the Value drop-down list, the data type of the value is automatically displayed in the Data Type column and cannot be changed.
     6. If necessary, add more key-value lines and specify the key, data type and value in each line.

        To delete a message key-value line, select it and click . To adjust the order of the lines, click or .

     Tip: You can also create a blank user defined message by only specifying the ID and name of the message.

  4. Repeat the above steps to define other messages that will be sent out from the object on different events.
  5. Click OK to accept the settings.

In addition to the above method, you can also use the Send Message web action to send out messages. To do this:

1. Do one of the following:
   • Right-click a data field, or a label in a table/crosstab, or a label, a parameter control or the Submit button of a parameter form control which is not in the library component's configuration panel, select Display Type from the shortcut menu. In the Display Type dialog, select a trigger event from the drop-down list in the Events column and click in the Actions column.
   • In the Behaviors tab of some chart format dialogs, select a trigger event from the drop-down list in the Events column and click in the Actions column.
   • While creating or editing a geographic map, in the Display screen of the map wizard, select a group level and click the Web Behaviors button. In the Web Behaviors dialog, select a trigger event from the drop-down list in the Events column, click in the Actions column and click in the Actions column.
2. In the Web Action List dialog, select *SendMessage and click OK. The Send Message - Web Action Builder dialog appears.

   

3. Define the message that will be triggered on the specified event.
4. Click OK to confirm the settings.
5. In the dialog you are returned to, add more event lines and repeat the above steps to specify to send out more messages as you want.
6. Click OK to finish defining the messages to send out.

Receiving messages

The data components (tables, charts, crosstabs, KPIs and geographic maps) in a library component can receive messages that are sent out from the current library component or another library component. When a data component receives a message at runtime, it will perform the web actions defined in the message, such as filtering, sorting itself using conditions specified in the message, running the current or another library component with predefined parameter values, or changing its object properties.

To make a data component receive messages and respond corresponding web actions, take the following steps:

1. Right-click the data component and select Receive Message from the shortcut menu. The Receive Message dialog appears.

   

2. Click to add a message line.
3. Select the message you want the data component to receive from the Message ID column.
   • 0001 - Filter
     When the data component receives this message, it will filter itself based on the filter condition defined in the message.
   • 0002 - Sort
     When the data component receives this message, it will sort itself based on the sort condition defined in the message. Not available to KPI.
   • 0003 - Parameter
     When the data component receives this message, the library component that contains the data component will re-run with the parameter values defined in the message.
   • User Defined
     A data component in a library component can also receive user defined messages and then respond web actions, such as Filter, Sort, Change Property and Parameter.

     The Filter web action enables you to filter the records of the data component when it receives the message.

     The Sort web action enables you to sort the records of the data component when it receives the message.

     The Change Property web action enables you to change properties of the data component when it receives the message.

     The Parameter web action enables you to run a library component, especially a library component with parameters using predefined parameter values, or re-run the current library component with predefined parameter values when the message is received.

4. If a built-in message is selected, the action the message will respond cannot be changed, but you can edit how the action will be performed as you want.

   If a user define message is selected, you can specify the action the data component will respond when it receives the message and define how the action will be performed.

5. Repeat the above steps to add more messages to receive and define the actions to respond the messages.

   To delete a message, select it and click . To adjust the display order of the messages in the message box, select a message and click or .

6. Upon finish, click OK to close the dialog.

The following details how to make a data component receive different messages.

To receive the built-in Filter message:

1. In the Receive Message dialog, select 0001 - Filter from the drop-down list of the Message ID column. The filter condition defined in the message will be automatically applied.
2. If you want to edit the filter condition, click in the Actions column and click that appears in the text box. The Filter dialog appears.

   

3. Specify the filter condition by selecting the field on which the filter will be based from the Filter On drop-down list, the operator to compose the condition from the Operator drop-down list and the value of how to filter the field from the Value drop-down list.
4. If necessary, click to add more filter conditions to filter other field values and specify the relationship between the conditions in the More column.

   To delete a filter condition, select the condition and click . To adjust the order of the filter conditions, click or .

5. Click OK to finish defining the filter conditions.

To receive the built-in Sort message:

1. In the Receive Message dialog, select 0002 - Sort from the drop-down list of the Message ID column. The sort conditions defined in the message will be automatically applied.
2. If you want to edit the sort condition, click in the Actions column and click that appears in the text box. The Sort dialog appears.

   

3. Specify the sort condition by selecting the field on which to sort the records from the Sort On drop-down list, and in which order to sort the records from the Sort Value drop-down list.
4. If necessary, click to add more sort conditions to sort other fields.

   To delete a sort condition, select the condition and click . To adjust the order of the sort conditions, click or .

5. Click OK to finish defining the sort conditions.

To receive the built-in Parameter message:

1. In the Receive Message dialog, select 0003 - Parameter from the drop-down list of the Message ID column.
2. Choose a message type from the Message Info column: Automatic or Customized.
   • When Automatic is selected, all the parameter values specified in the sent message will be automatically applied. If you want to edit the parameters,
     1. Click in the Actions column and click that appears in the text box. The Parameter dialog appears.

        

     2. Specify the parameter and the value of the parameter from the Parameter Name and Value drop-down lists. The operator can only be =.

        Parameter Name* in the Parameter Name drop-down list means that all the parameters defined in the message will be used to re-run the library component, and its corresponding value can only be Parameter Value* that represents all the parameter values.

     3. If necessary, click to add more parameter lines to specify other parameter values. If you specify a parameter value more than once, the last setting takes effect.

        To delete a parameter line, select it and click . To adjust the order of the parameters, click or .

     4. Click OK to accept the settings. Then at runtime, when the data component receives the message, the library component which contains it will re-run, using all the predefined parameter values.
   • When Customized is selected, the parameter value defined in the sent message will be automatically applied. If you want to edit the parameter,
     1. Click in the Actions column and click that appears in the text box to open the Parameter dialog.

        

     2. Specify the parameter and the value of the parameter from the Parameter Name and Value drop-down lists. The operator can only be =.
     3. Click OK to accept the settings. Then at runtime, when the data component receives the message, the library component which contains it will re-run, using the predefined parameter value.

To receive a user defined message and respond the Filter web action:

1. In the Receive Message dialog, input the ID and name of the user defined message in the Message ID column and Message Name column separately, then click in the Actions column and click that appears in the text box.
2. In the Web Action List dialog, select *Filter in the Action Name column and click OK.
3. In the Filter dialog, specify the filter conditions as required.
4. Click OK to accept the settings.

To receive a user defined message and respond the Sort web action:

1. In the Receive Message dialog, input the ID and name of the user defined message in the Message ID column and Message Name column separately, then click in the Actions column and click that appears in the text box.
2. In the Web Action List dialog, select *Sort in the Action Name column and click OK.
3. In the Sort dialog, specify the sort conditions as required.
4. Click OK to accept the settings.

To receive a user defined message and respond the Change Property web action:

1. In the Receive Message dialog, input the ID and name of the user defined message in the Message ID column and Message Name column separately, then click in the Actions column and click that appears in the text box.
2. In the Web Action List dialog, select *Property in the Action Name column and click OK. The Change Property dialog appears.

   

3. Specify the property you want to change and the value for it respectively from the Properties and Value drop-down lists. Only the properties of the data component itself can be changed at runtime.
4. If necessary, click to add more property lines to change values of other properties.

   To delete a property line, select it and click . To adjust the order of the properties, click or .

5. Click OK to accept the settings.

To receive a user defined message and respond the Parameter web action:

1. In the Receive Message dialog, input the ID and name of the user defined message in the Message ID column and Message Name column separately, then click in the Actions column and click that appears in the text box.
2. In the Web Action List dialog, select *Parameter in the Action Name column and click OK. The Parameter dialog appears.

   

3. Specify the handler which will receive the parameters of the web action. The handler may be the default one in the current server, or in another server specified by Customized Path.
4. Specifies whether to apply the action to run another library component or refresh the current. If you choose to run another library component, click the Browse button to specify the library component, then select the window or frame in which the library component will be opened from the Target Frame drop-down list.
5. If the specified library component contains parameters, the parameters will be automatically listed in the parameters box. Specify the value for each parameter. You can also click to add more parameter lines to specify other parameter values.
6. To delete a parameter line, select it and click . To adjust the order of the parameters, click or .
7. Click OK to accept the settings.

Example of delivering a message

This example demonstrates how to deliver a filter user defined message between two library components in order to synchronize the data components in them. It contains the following tasks:

• Task 1: Create two library components
• Task 2: Send out a filter user defined message from the chart
• Task 3: Make the two data components receive the same message
• Task 4: Publish the library components to JReport Server
• Task 5: Deliver the message in a dashboard for data synchronization

Task 1: Create two library components

1. Make sure SampleReports.cat is the currently open catalog file. If not click File > Open Catalog to open it from <install_root>\Demo\Reports\SampleReports.
2. Use the business view SaleStat in Data Source 1 to create two library components and save them as Component 1.lc and Component 2.lc.

   For Component 1, create a chart which displays in the clustered bar 2-D chart type, shows Assigned Region on X-Axis and Total Actual as Bar Length. For Component 2, create a crosstab using Order ID and Assigned Region respectively as the row and column fields, and Total Actual as the summary field. Apply the style Commercial to both of them.

Task 2: Send out a filter user defined message from the chart

In this task, we will send a filter user defined message from the chart in Component 1 when the Click event occurs on any legend entry value.

1. Open Component 1.lc.
2. Right-click the chart legend and click Send Message > Customize on the shortcut menu to bring out the Send Message dialog.
3. In the Events box, check Click as the trigger event, then click on the event to activate the message options on the right.
4. From the Message drop-down list, select User Defined, then input 1001 and Filter - Assigned Region as the message ID and name.
5. Click to add a message line.
6. Select the <Input> item from the drop-down list in the Key column and input Assigned Region in the text box.
7. Select Current Value from the drop-down list in the Value column. String is displayed automatically in the Data Type column.

   The message is defined as follows:

   

8. Click OK to finish defining the message to be sent out.
9. Save the library component.

Task 3: Make the two data components receive the same message

In this task we will make the chart and crosstab in the two library components receive the same filter message to filter on the Assigned Region values when they receive the message sent out from a chart legend entry.

1. Right-click the chart platform and select Receive Message from the shortcut menu to display the Receive Message dialog.
2. Click to add a message line.
3. Select the <Input> item from the drop-down list in the Message ID column, then input 1001 in the text box.
4. Input Filter - Assigned Region in the text box of the Message Name column.
5. Click the blank text box in the Actions column, then click that appears.

   

6. In the Web Action List dialog, select *Filter and click OK to display the Filter dialog.
7. Select Assigned Region from the Filter On drop-down list, keep the default operator, then select <Input> under the Message Key node in the Value drop-down list and input Assigned Region in the text box.

   

8. Click OK to go back to the Receive Message dialog. The message Component 1 receives is defined as follows:

   

9. Click OK, then save the library component.
10. Open Component 2.lc.
11. Right-click the crosstab and select Receive Message from the shortcut menu.
12. In the Receive Message dialog, specify the message the crosstab is going to receive as shown above.
13. Save the library components.

Task 4: Publish the library components

Start JReport Server and publish the library components along with the catalog SampleReports.cat to the component library in JReport Server. For details about publishing resources from JReport Designer to JReport Server, see Publishing resources remotely.

Task 5: Deliver the message in a dashboard for data synchronization

1. Open the JReport Server console > Resources page, click New > Dashboard on the task bar. A blank dashboard is displayed in JDashboard.
2. Open the Resources panel and browse to the folder where the two library components are published.
3. Drag and drop the two library components to the dashboard.

   

4. Click Asia-Pacific in the chart legend to send out the message. The chart and the crosstab are both filtered to show data in the Asia-Pacific region only.

   

5. Click the Clear Filters button on the toolbar to clear the filter in both components.
6. Click Europe, Middle East, Africa in the chart legend and the chart and crosstab are filtered based on this region now.

   

Previous Page Next Page