Receiving messages

The data components, which refers to tables, charts, crosstabs and geographic maps, in a library component can receive messages, including the built-in messages 0001 - Filter, 0002 - Sort, 0003 - Parameter, and user defined messages that are sent out by itself or another library component. You can then specify actions such as filtering, sorting, running library component with predefined parameter values and changing object properties on the data component to respond the received messages.

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

1. Select the data component in a library component, right-click and select Receive Message from the shortcut menu. The Receive Message dialog appears. See the dialog.

   

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.
   • 0003 - Parameter
     When the data component receives this message with the type set to Automatic, the library component which contains the data component will rerun with all the parameter values defined in the message.

     When the data component receives this message with the type set to Customized, the library component which contains the data component will rerun with the parameter value 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, 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 Property web action enables you to change properties of the data component itself 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 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 .
6. For message of the same ID and name, you can make the data component receive it more than once, and in which order the actions defined in the message will be executed is determined by the order of the messages in the list. To adjust the order, select the message and click or , then for message with the same ID and name, the higher a message is placed in the list, the earlier the action defined in it will be executed.
7. Upon finish, click OK to close the dialog.

To receive the built-in message 0001 - Filter:

1. In the Receive Message dialog, select the built-in message 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. See the dialog.

   

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, specify And or Or in the More column so as to add a new filter condition or you can click to add a new filter condition.

   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 message 0002 - Sort:

1. In the Receive Message dialog, select the built-in message 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. See the dialog.

   

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 a new sort condition.

   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 message 0003 - Parameter:

1. In the Receive Message dialog, select the built-in message 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.
     1. If you want to edit the parameters, click in the Actions column and click that appears in the text box. The Parameter dialog appears. See the 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 =.

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

     3. Click to add a new parameter line and specify the parameter and value as you want.

        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 rerun, using all the predefined parameter values.
   • When Customized is selected, the parameter value defined in the sent message will be automatically applied.
     1. If you want to edit the parameter, click in the Actions column and click that appears in the text box to open the Parameter dialog. See the 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 rerun, 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 condition 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 condition as required.
4. Click OK to accept the settings.

To receive a user defined message and respond the 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. See the dialog.

   

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.

   In the two drop-down lists, you may find some items have the icon ahead of them and they are listed under the Message Key node. If you choose an item of this type, it means the item will not be used directly in the property changing condition, instead, it will be mapped to a key in the message and JReport will search for the value that is specified to the key from the message first and then use that value to compose the property changing condition.

4. If necessary, click to add a new line to change another property.

   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. See the dialog.

   

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 a parameter line and specify the parameter and value if needed.

   In the Parameter Name and Value drop-down list, you may find some items have the icon ahead of them and they are listed under the Message Key node. If you choose an item of this type, it means the item will not be used directly in the parameter condition, instead, it will be mapped to a key in the message and JReport will search for the value that is specified to the key from the message first and then use that value to compose the parameter condition.

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.