include JavaServer Page tag

Use the include JSP tag to instruct stream processing to insert one stream within the current stream. This tag lets you define a commonly used segment of HTML or XML text in one rule instance and then incorporate the text where needed.

This tag is useful in source HTML text for user interface forms, in source HTML text for correspondence, and in XML text for interfaces.

Use the include tag to include any of nine rule types:

  • Fragments ( Rule-HTML-Fragment rule type)
  • Flow actions ( Rule-Obj-FlowAction rule type)
  • Paragraphs ( Rule-HTML-Paragraph rule type)
  • HTML rules ( Rule-Obj-HTML rule type)
  • Correspondence rules ( Rule-Obj-Corr rule type)
  • Correspondence fragments ( Rule-Corr-Fragment rule type)
  • Control rules ( Rule-HTML-Property rule type)
  • Sections ( Rule-HTML-Section rule type)
  • XML rules ( Rule-Obj-XML rule type)

For example, this code inserts a fragment of HTML text into the currently processed stream:

<pega:include name="NewHeader" type="Rule-HTML-Fragment" />

The name attribute identifies only the final key part or key parts of the target rule to be included. For rule types that contain an Applies To key part, the system uses the Applies To key part of the current rule at runtime and uses rule resolution to find the target rule to include.

<pega:include > JSP tags can also appear in rules of other types derived from the Rule-Stream class, such as harness, section, flow action, list view and summary view rules. In most cases, the HTML code and JSP tags for these rules are automatically generated.

Don't use this tag to include a rule within itself (recursion), as that often causes an infinite loop.

Complete syntax

In the following syntax presentation:

  • Square bracket characters [ and ] define optional parts of the tag. Do not type the brackets.
  • Replace any text in italics with your choice of value of that type.
<pega:include
	[name="name"]
	[ref="indirect reference "]
	[type="rule type"]
	[inline="true"|"false" ]
/>

Either name or ref is required as an attribute.

Attribute Description
name The name -- second key part -- of the rule to included. Use this attribute when the name is known during design.
ref Used for indirect references, which allow the rule name to be determined dynamically at runtime. See How to reference properties indirectly in JSP tags.
type

Identify the class of the rule to be included, for example Rule-Obj-HTML, Rule-HTML-Property, Rule-HTML-Paragraph, or Rule-HTML-Section.

If the type attribute is omitted, then the type that is included depends on the including type, as follows:

  • A Rule-Obj-HTML or Rule-HTML-Fragment includes a Rule-HTML-Fragment.
  • A Rule-HTML-Property includes a Rule-HTML-Property.
  • A Rule-Obj-XML includes a Rule-Obj-XML.
  • A Rule-Obj-Corr or a Rule-Corr-Fragment includes a Rule-Corr-Fragment.

You can use any of these keywords:

  • standard — Indicates that the type of the rule to be included is the same as the type of the rule with the <pega:include > tag, with two exceptions: a Rule-Corr-Fragment rule includes a Rule-Obj-Corr rule, and a Rule-HTML-Fragment or Rule-HTML-Property rule includes a Rule-Obj-HTML.
  • property — Short for Rule-HTML-Property.
  • fragment — Short for Rule-HTML-Fragment.
  • noinput — Display the included HTML text as read-only. Like standard, noinput indicates that the type of the rule to be included is the same as the type of the rule with the <pega:include > tag, with two exceptions: a Rule-Corr-Fragment rule includes a Rule-Obj-Corr rule, and a Rule-HTML-Fragment or Rule-HTML-Property rule includes a Rule-Obj-HTML .

You can't include a Rule-HTML-Fragment rule or Rule-Obj-Corr rule within an XML Stream rule.

You can include a Rule-HTML-Property rule only within a Rule-Obj-Corr rule.

inline

Set to "false" in unusual situations to disable the default Java generation approach, which inlines Java code for this tag. The "false" setting may reduce the size of the Java class generated for the stream rule, possibly allowing it to fit within the 64KB limit.

The default value is "true"; inlining is preferred as it normally provides better performance.
mode

Determines whether input is enabled when the included stream is displayed. Set to:

  • input — Properties in the included stream are displayed in input mode where indicated. (This is the default value if the mode attribute is omitted.)
  • noinput — Properties in the included stream are never displayed in input mode (even if their pega:reference tags specify mode="input").

Three special cases — XML, Correspondence, and Correspondence Fragments

Three stream rule types have three key parts. If the stream rule class is Rule-Obj-Corr or Rule-Corr-Fragment, identify the second and third key parts in the value of the name attribute, separated by a period. The third key part is the Correspondence Type.

For example, the standard correspondence type Email can appear:

<pega:include name="SuccessCorr.Email" type="Rule-Obj-Corr"/>

Similarly, you can include a correspondence fragment for phone text:

<pega:include name="WorkDetail.PhoneText" type="Rule-Corr-Fragment"/>

Likewise, if the stream rule class is Rule-Obj-XML, use a period to separate the second and third key parts of the target XML Stream rule. For example: 

<pega:include name="Contact.MapFrom" type="Rule-Obj-XML" />

Including sections that accept parameters

A section may accept parameters, identified on the Params tab of the Section form. If the <pega:include > tag is for a section, you can use the <pega:params > JSP tag to supply parameter values.

For example:

<pega:include name=".GameResults" type="Rule-HTML-Section" >
	<pega:param name="HomeTeam" value="Boston"/>
	<pega:param name="VisitorTeam" value="Yankees" />
	<pega:param name="HomeTeamRuns" value="3" />
	<pega:param name="VisitorTeamRuns" value="7" />
</pega:include>

JavaServer Pages tags