Table of Contents
Rules Overview
Rules are used in several places in HelpStudio (Build Profile Editor Filters page, the Project Search Tool) to match items or content according to one or more conditions. For example, the Build Profile Editor Filters page allows you to specify one or more rules that govern whether items are included in the output generated by that Build Profile.
Rules save you time and effort by allowing you to match a set of items without having to find and manually flag or identify them manually.
Rule Kinds
There are several different kinds of Rules that you can use when defining a Rule set:
Build Flag Rule
Compares against Build Flags applied to items or defined in Content. This Rule is commonly used in the Build Profile editor to selectively include items and content only if they have specific Build Flag(s) applied.
Item Name Rule
Compares against the item name. This Rule matches items that have a specific name, or naming pattern.
Item Property Rule
This powerful Rule allows you to compare against the value of a wide variety of Metadata Elements - the same elements that can be used in custom Template Page Layouts. Using this kind of Rule it is possible to match on almost any value present in the generated output.
Item Type Rule
Compares against the type of item, allowing specific item types to be selected. This kind of Rule is commonly used in combination with one of the other Rule kinds - e.g. selecting methods named "Refresh" by combining with an Item Name Rule to select specifically named items, but only if they are of the "Method" item type.
Rule Group
This Rule kind exists to allow you to create child groups of rules, in order to logically combine several rules in "And" or "Or" groupings.
If you are using the Rule Editor in the Project Search Tool, there are several additional Rule Kinds that you can use. See the Project Search topic for more information on those additional Rule Kinds.
Rule Grouping
For more complex Rule sets, you may find it necessary to group rules into logical "And" or "Or" groups to achieve the desired logic. You can do this by adding Rule Group items to your Rule Set which allow you to group child rules using a logical "And"/"Or" operator.
Grouping Example
In the screenshot below, the illustrated Build Profile Rule set will exclude any methods with names that begin with "internal" or "hidden". The Rule Group is necessary in this scenario as items should only be excluded if both top level parts of the Rule set must match (Item Type must be "Method" And Item Name is one of the patterns specified), but the Item Name rule group should match any of the Item Name values (Item Name begins with "internal" Or Item Name begins with "hidden").
Image Title
Step by Step to create the example Rule Set
To create the example rule set above:
- Open the Build Profile Editor and select the Filters page;
- From the Filter kind drop down, select "Exclusion: Exclude any content or items that match the Rules below";
- Click the Add New Rule button and select Item Type from the Rule Kind list that appears;
- An Item Type rule will be added. Click the
New toolbar button in the Item Type Rule Designer and choose "Method" from the displayed list of Item Types;
- Click the Add New Rule button and select Rule Group from the Rule Kind list that appears;
- A new Rule Group will be added. Select "One or more Rules must be True" from the drop down in the header of the newly added Rule Group;
- Click the Add New Rule button in the footer area of the Rule Group (this will add a new Rule to the Rule Group rather than the main Rule Set) and select Item Name from the Rule Kind list that appears;
- Type "internal.*" in the text box within the newly added Item Name Rule. Select the Use RegEx option (the .* part of the name is a RegEx pattern that matches any characters);
- Repeat 7. and 8., this time typing "hidden.*" as the Item Name value.
This Rule Set will now exclude any methods that have names that begin with "internal" or "hidden".
Grouping by adding Rule Groups to the Rule set allows for complex Rule sets to be defined that would not otherwise by possible.