How to Use Rules in Displayr

This article describes how to apply rules to drag-and-drop tables, many R tables*, and "With Test" visualizations in Displayr (that is, not R-based visualizations). This can be done on any number of outputs you have selected, and if you select a Page(s) or Folder(s) in the Report tree, all applicable outputs contained within those. Rules are a set of predefined automated functions – most commonly, they could be thought of as a way of conditionally formatting tables (where you specify the conditions). However, the range of available functions extends well beyond formatting. The current library of automated options includes (but is not limited to):

• Highlighting cells or chart series via custom criteria (e.g., ranges, greater/less than, top n).
• Applying color scales to entire tables or charts.
• Adding text or symbols to table cells or chart data labels.
• Customizing significance comparisons.
• Removing rows or columns or hiding cells based on specific criteria (e.g., minimum sample size).
• Reformatting columns (e.g., include sample size; re-label but leave source variable intact).
• Customizing footers.
• Automatically re-sorting charts or tables, by columns or rows of your choice.
• Weighting selected columns or rows.

*Not all rules are currently compatible with R tables. Incompatible rules will display a warning in the Rules field and in the Rule's pop-up window (if available). See Caveats and Limitations for Rules for more information.

Requirements

• A Displayr document with at least one table. The table cannot be a Visualization > Specialty tables, such as a Table with Custom Formatting (Autofit table). Formatting for that can be done via the menu or by editing the R code directly (see here). If you receive an error that says it's not applicable because "this item has no underlying table", you likely have one of the specialty tables that are not supported.

Method - Apply rules

1. To apply a rule, simply select your table or visualization and click the Plus (+) button under the Rules section of the Properties tab in the object inspector .
2. The selected rule will then be added to the Rules field box.
3. You are able to add multiple rules to your table or visualization. Note: the rules will be applied in the order they appear in this box. Depending on the rules being used, you may need to change the order by dragging one above the other to ensure they work as intended. For example, if you wish to shade table cells but also want to remove values under a specific value, you would need to apply the shading cells rule first.
4. To automatically apply this rule to all new tables, right-click the rule and tick Use for new table and charts.
5. To add this rule to all existing tables, right-click and select Apply > Add to every item in the document.
6. To add this rule to all selected tables, right-click and select Apply > Add to selected items.
7. Note that changing the dimensions of a table by, for example, using the Switch rows and columns option will affect the implementation of the rule. You may then need to apply an alternate rule if it is specific to rows or columns.

Note: You must apply the rule directly to the input table if you see a table icon in the Data > Data Source > Data field in the object inspector of a visualization.

You will also see a warning in the Rules section of the object inspector if you have applied a rule directly to a non-compatible visualization, and you will need to apply it to the input table instead. For example:

Method - Edit rules

1. To edit rules, right-click the appropriate rule in the object inspector and select Edit.
2. OPTIONAL: Select Edit JavaScript to customize the underlying code further. Note, Highlight, Top/Bottom, and Color Scales rules cannot be modified in this way.
3. Change the necessary settings.
4. OPTIONAL: Tick the Modify this rule only for the selected outputs. This will create a new rule while leaving other outputs unchanged option if you wish for the changes to only be applied to the output(s) you had selected when you edit the rule. It will then create a new version of the rule with your changes, while leaving the original rule unchanged. Otherwise, your changes will be applied to all outputs in the document that use the rule.
5. Press OK.

Method - Delete rules

1. To delete rules, right-click the appropriate rule in the object inspector > Delete. Note, if you have applied this rule to all tables in one step (as opposed to doing so individually) or have copied a table with the rule already applied, this option will delete it from all tables that use this rule. You can highlight which tables are connected by this rule by selecting the Show all tables using this rule option.
2. Alternatively, you can delete the rule from all existing tables by right-clicking and selecting Apply > Remove from every item in the document.
3. To only remove the rule from selected tables, right-click and select Apply > Remove from selected items.

Method - Custom rules

All the rules are written in JavaScript (see Table JavaScript and Plot JavaScript for details). You can write your own rules in JavaScript, applying them by selecting New custom rule (write your own JavaScript). See How to Create a Custom Rule and How to Customize a Rule for more information.

Next

How Rules Work in Displayr

How to Customize a Rule

How to Create a Custom Rule

Creating Rules Video