Adding facets to the content collection using facet template matches in the .XIL file

You add a facet category to the content collection by defining a facet in a facet template match in an indexsheet (.xil file). Facet template matches specify the rules for creating and associating facet categories when the content is indexed. The number of facet template matches that you create is flexible: each facet template match can create thousands of facet categories and can be associated to tens of thousands of documents. Each document can be associated with more than one facet category.

When the content collection is built, sets of facet categories are generated from each template.

NXT supports two types of facet template matches:

Query facet template matches
XSL-based facet template matches

Facet template matches must be named. The names of facet categories are generated using the name of the facet template match that created them. The following restrictions apply to facet category names and facet template matches:

A facet category name cannot be blank, and cannot contain only spaces or only forward slashes ( / ).
The maximum length of the full facet category name is 256 characters.
Spaces are not allowed before or immediately after a forward slash ( / ). For example, the following combinations are not allowed: ' /text', 'text /text', or 'text/ text'.
Spaces are not allowed at the beginning or at the end of the facet category name: ' text/text', 'text/text '. However, spaces within the text are allowed. For example: 'text text/text text'
Two forward slashes together are not allowed: 'text//text'

Creation of facets and facet categories

Creation of facets and facet categories starts with parsing of your content, XIL files, and creation of facet category templates. Names of facets and templates must meet the server requirements for names. Otherwise, facets, and templates are not created. During the indexing process, the NXT server receives names of facet categories from a text. The NXT server stores names of categories in the encoded view (for example, the facet/my text! facet is encoded as facet/my#20text#21). NXT services and components decode this view to present the facet and the facet category in a user-friendly way. In addition to the name, each facet and facet category has a title. The title is the facet view that users see in the Filters section on your NXT site. You can customize titles, if you want to set the specific view of the title. For more information about customization of a facet view, see Customizing facet view on a website.

Figure 1 shows the process of a facet creation.

Figure 1. Process of facet creation

Adding a Query facet template match

You can add facet categories with the Query facet template match. A regular NXT query determines whether a document is included to this facet category or not. The following limitations apply to the query:

boolean
non-ranked
written in the Server syntax
must not include the [category:] primitive

Field based queries are not mandatory.

Each HTML document in the Olympic collection contains the metatag that indicates the number of medals that an athlete won. By using a Query facet template match, you can create the following facet category tree:

medal_count
- medal_count/1_medal - one medal
- medal_count/2_and more - two medals and more
- medal_count/5_and_more - five medals and more
- medal_count/7_and_more - seven medals and more

To use the Query facet template match, add a field definition to the XIL file and create the medal_count facet at the top of query with medal_count_field:


<np:definition>
	<!-- Declare field -->
	<field name="medal_count" type="long"/>

	<!-- Create facet medal_count and facet values 1_medal, 2_and_more, 5_and_more, 7_and_more -->
	<facet name="medal_count/1_medal" query="[field, medal_count_field:1]" />
	<facet name="medal_count/2_and_more" query="[field, medal_count_field:[&gt;=:2]]" />
	<facet name="medal_count/5_and_more" query="[field, medal_count_field:[&gt;=:5]]" />
	<facet name="medal_count/7_and_more" query="[field, medal_count_field:[&gt;=:7]]" />
</np:definitions>

<!-- Create field medal_count from tag medal_count -->
<xsl:template match="medal_count">
	<np:index field-element-name="yes"/>
</xsl:template>

Adding XSL-based facet template matches

XSL-based facet template matches are defined in the .xil file. The definition rules for XSL-based facet template matches correspond to the definition rules for fields. The names of facet categories are generated from the markup language of the documents. In this way, the facets are generated and the documents are included in the appropriate facet categories.

You can create the following types of facets:

Flat facet
Hierarchical facet

Flat facet example using XSL-based template matches

Each HTML document in the Olympic collection contains the <medal_value> field. Consider the following example:


<table class="medals">
	<tr>
		<th class="text center" colspan="4"> Competitor for
				<country>Russia</country>
		</th>
	</tr>
	<tr>
		<td class="text center" colspan="4">
				<game>2000 Summer Olympics</game>
		</td>
	</tr>
	<tr>
		<td>
			<i class="silver medal">
			</i>
		</td>
		<td>
				<medal_value>Silver</medal_value>
		</td>
		<td>
				<discipline>Shooting</discipline>
		</td>
		<td>
			<event>Men's 10 metre air rifle</event>
		</td>
	</tr>
</table>

Using a flat facet, you can create the following facet categories:

medal_value
- medal_value/bronze
- medal_value/gold
- medal_value/silver

To create this example, match the medal_value field to the facet in the XIL file. Consider the following example:


<xsl:template match="medal_value">
	<np:index facet-element-name="yes">
		<xsl:apply-templates/>
	</np:index>
</xsl:template>

Figure 2 shows how the Online Server displays the medal_value facet category.

Figure 2. The medal_value facet category

Hierarchical facet using XSL-based template matches

Each HTML document in the Olympic collection includes the olympic_event field that contains categories in the following format: game/sport/event. If you want to include the olympic_event field value to the facet category olympic_event/summer1992/table_tennis/woman_single, add an appropriate match expression to the XIL file:


<xsl:template match="olympic_event">
	<np:index facet="by_event"/>
</xsl:template>

All documents with the value xxx/yyy/zzz of the olympic_event field are included to the facet by_event/xxx/yyy/zzz.

Online Server displays this facet category as the following facet:

Figure 3. The by_event facet

Sample facets with transformations

Both flat facets and hierarchical facets can contain transformation rules. You can check the transformation rules using the Facet Rule Tester utility.

Flat facet with transformation

Each HTML document in the Olympic collection contains the metatag that indicates the number of medals that an athlete won. Using this metatag, you can create the following facet category tree:

medal_count
- medal_count/1_medal - one medal
- medal_count/2_and more - two medals and more
- medal_count/5_and_more - five medals and more
- medal_count/7_and_more - seven medals and more

To generate the facet from the metatag values, define the match expression and the set of rules. The rule element defines the rule for the name transformation. You can include child rules. Consider the following example:


<np:definitions>
	<facet-name-rules>
		<rule match="^medal_count(\d)/(.*)$" replace="%1%/%2%">
			<rule match="1/1" replace="medal_count/1_medal" stop="yes"/>
			<rule match="1/.*" replace="medal_count_hidden/1" stop="yes"/>
			<rule match="2/[2-9]" replace="medal_count/2_and_more" stop="yes"/>
			<rule match="2/\d{2,}" replace="medal_count/2_and_more" stop="yes"/>
			<rule match="2/.*" replace="medal_count_hidden/2" stop="yes"/>
			<rule match="5/[5-9]" replace="medal_count/5_and_more" stop="yes"/>
			<rule match="5/\d{2,}" replace="medal_count/5_and_more" stop="yes"/>
			<rule match="5/.*" replace="medal_count_hidden/5" stop="yes"/>
			<rule match="7/[7-9]" replace="medal_count/7_and_more" stop="yes"/>
			<rule match="7/\d{2,}" replace="medal_count/7_and_more" stop="yes"/>
			<rule match="7/.*" replace="medal_count_hidden/7" stop="yes"/>
		</rule>
	</facet-name-rules>
</np:definitions>

<xsl:template match="meta[@name='medal_count']">
	<np:index-attribute name="content" facet="medal_count1;medal_count2;medal_count5;medal_count7"/>
</xsl:template>

Create four facets and corresponding categories for each medal value. In the previous example, the names of facets are medal_count1, medal_count2, medal_count5, and medal_count7. For category 1, these facets have corresponding categories: medal_count1/1, medal_count2/1, medal_count5/1, medal_count7/1. This set of rules divide these four facets into two facets: medal_count and medal_count_hidden. The medal_count_hidden facet can be hidden in Content Network Manager UI, and then only the medal_count facet remains.

The input value of <name of facet category template>/<tag/attribute value> string is converted to the facet category name as an output.

You can use the Facet Rule Tester to tune the rules.

Note: Additional transformation of the categories can be required. See Generating readable facet categories for details.

Hierarchical facet with transformation

Each HTML document in the Olympic collection contains the birth_date field that contains values in the following format: YYYY-MM-DD. To build the facet category hierarchy such as birth_date/<century>/<decade>/<year>, add the following rule to the XIL file:


<np:definitions>
	<facet-name-rules>
		<rule match="birth_date/(\d\d)(\d)(\d).*$" replace="birth_date/%1%/%2%/%3%" stop="yes"/>
	</facet-name-rules>
<np:definitions>

<xsl:template match="birth_date">
	<np:index facet-element-name="yes"/>
</xsl:template>