Documentation Center

Dynamically filter the taxonomy structure based on the values of another field

We will configure the Tridion Docs SES Connector in such a way the values a user selected for another field limits the terms he can select for this field. This type of filtering configuration can be combined with entry points and relational filtering.

About this task

In Hypothetical taxonomy tree structure we defined a certain taxonomy structure. Instead of always showing the entire taxonomy structure, we will configure the field FLOCATION in such a way it will dynamically filter the tree structure based on the values selected by the user for another field (FCONTINENTS). As this filter is dynamic, the tree structure shown depends on the values chosen in the other field. We will limit the user so he can only select cities.

Some examples of the dynamically filtered tree structure:
  • If the user did not select anything yet, the tree structure is unfiltered and looks like this:
    
    Continents                      {id=34, class=category, selectable=no}
        - Australia                 {id=5, class=continent, selectable=no}
            - Australia             {id=38, class=country, selectable=no}
                - Sydney            {id=46, class=city, selectable=yes}
        - Europe                    {id=17, class=continent, selectable=no}
            - France                {id=105, class=country, selectable=no}
                - Paris             {id=12, class=city, selectable=yes}
    Hemispheres                     {id=99, class=category, selectable=no}
        - Northern                  {id=203, class=hemisphere, selectable=no}
        - Southern                  {id=14, class=hemisphere, selectable=no}
    
  • If the user selected the continent Australia in the other field, the tree structure would look like this:
    
    Continents                      {id=34, class=category, selectable=no}
        - Australia                 {id=5, class=continent, selectable=no}
            - Australia             {id=38, class=country, selectable=no}
                - Sydney            {id=46, class=city, selectable=yes}
    
  • If the user selected the continent Europe in the other field, the tree structure would look like this:
    
    Continents                      {id=34, class=category, selectable=no}
        - Europe                    {id=17, class=continent, selectable=no}
            - France                {id=105, class=country, selectable=no}
                - Paris             {id=12, class=city, selectable=yes}
    

  • If the user selected both Australia and Europe you would see both Australia and Europe with their countries and cities.

Procedure

  1. Open the extension configuration in Organize Space via Settings > XML Settings > Extensions.
    By default the extension configuration only contains
    <infoShareExtensionConfig version="1.0"/>
  2. Add a basic configuration and configure the field to use and the common initialization parameters for the data source.
    As an example, you can paste the following xml where you replace: the field name (FLOCATION), the field level (logical), the source id (SESExampleModelDataSource), the SES URL (http://smartlogic.example.com/ses, where smartlogic refers to an example server dedicated to logic.) and the SES model name (Example) with values appropriate for you.
    
    <infoShareExtensionConfig version="1.0">
      <metadatabindings>
        <metadatabinding ishfieldname="FLOCATION" sourceref="SESExampleModelDataSource" />
      </metadatabindings>
      <sources>
        <source id="SESExampleModelDataSource" handler="SmartLogicSESConnector">
          <initialize>
            <parameters>
              <parameter name="ses.api.url">http://smartlogic.example.com/ses</parameter>
              <parameter name="ses.api.tbdb">Example</parameter>
              <parameter name="metadatabinding">
                <fields>
                  <field name="FLOCATION" level="logical">
                    <read>
                      <entrynodes/>
                      <fieldfilters/>
                      <selectable/>
                      <relations/>
                    </read>
                  </field>
                </fields>
              </parameter>
              <parameter name="relations">
                <relations/>
              </parameter>
            </parameters>
          </initialize>
        </source>
      </sources>
    </infoShareExtensionConfig>
    
    With this basic configuration in place, the tree only shows the 2 root terms Continents and Hemispheres, nothing else. All terms would be selectable.
  3. Add the relations you want to use for the tree structure.
    In order to see the children of the root terms we need to define which relationships to use (follow) to get to the child terms.
    The relations defined for the field are applied multiple times (recursively), so you will get child terms of the root terms, child terms of the child terms, ...
    1. Define the relation in the relations parameter.
      For the example, we will just define the standard SES narrower term (NT) relationship, so you can use the following XML part for the relations parameter
      
      <parameter name="relations">
          <relations>
              <relation type="hierarchical" id="narrowerterm" abbreviation="NT" direction="Forward"/>
          </relations>
      </parameters>
      
    2. Reference the relation in the relations of the read section of the field.
      For the example, we will just refer to the standard SES narrower term (NT) relationship, so you can use the following XML part for the field relations
      
      <relations>
          <relation ref="narrowerterm" />
      </relations>
      
    With this configuration in place, the tree shown would have the 2 root terms Continents and Hemispheres, and all continents, countries, cities underneath Continents + all hemispheres underneath Hemispheres. The continents underneath the hemispheres will not be shown in the tree as they use a different relationship type than NT. All terms would be selectable.
  4. Configure the filter field as a metadata bound field.
    As an example, you can configure it by pasting following XML part
    
        <metadatabinding ishfieldname="FCONTINENTS" sourceref="SESExampleModelDataSource" />
    
  5. Configure the filter field for the field.
    This configures that we want to use the values of the field provided to filter the tree structure for this field.
    You can only define one field as a fields filter.
    As an example, you can configure it by pasting the following XML part as fieldfilters for the FLOCATION field
    
    <fieldfilters>
        <field name='FCONTINENTS' level='logical'/>
    </fieldfilters>
    
    With this configuration in place, if the user fills in Australia the tree is filtered to show Australia and it's subtree only. The ancestors of Australia are also calculated and shown.
  6. (Optional) Add a conversion relation
    For our example, we actually don't need a conversion relation, we will just describe here what you could do in case you do need it. Suppose you had a field FHEMISPHERE where the user selected Northen and you would want to filter the Continents tree based on the continents associated to the Northern hemisphere, this is what you could define a relation and add it as conversion relation
    You can only have one conversion relation. Both associative or hierarchical relationships can be used. The relation is applied only once (so non-recursively), meaning you will only get directly related terms
    1. Define the relation you want to use
      If it is already present there is no need to define it again.
      As an example, you can configure it by adding the relation into the relations element of the relations parameter. In this example we also added conditions on the relation to limit the derived values to continents only (should there be other related terms), but that is not always necessary.
      
      <relation type="associative" id="hemisphere2continent" abbreviation="RT" direction="Forward">
         <to>
             <condition name="CLASS">continent</condition>
         </to>
      </relation>
      
    2. Reference the relation as a conversion relation
      As an example, you can configure it by pasting the following XML part as entrynodes for the FLOCATION field
      
      <fieldfilters>
          <field name='FCONTINENTS' level='logical'>
              <conversion>
                  <relation ref="hemisphere2continent" />
              </conversion>
          </field>
      </fieldfilters>
      
    With this configuration in place, if the user filled in Northern in the FHESMISPHERE field, we will follow the conversion relation to convert the user value "Northern" to the derived value "Europe". This derived value "Europe" will be used to filter the tree for the FLOCATION field. If you would have multiple continents related to the Northern hemisphere, you would have multiple filter terms (which are or'ed).
  7. Limit the terms the user can select using conditions
    The only supported condition name is "CLASS". Multiple conditions will be or'ed
    For the example, we only want to select cities add a condition.
    
    <selectable>
        <condition name="CLASS">city</condition>
    </selectable>
    
    Same tree structure is shown, but from now on only cities would be selectable.
  8. You need to configure the other field (the filter field) as well, so the user can fill in values for it.

Results

Complete Extensions configuration

<infoShareExtensionConfig version="1.0">
  <metadatabindings>
    <metadatabinding ishfieldname="FLOCATION" sourceref="SESExampleModelDataSource" />
    <metadatabinding ishfieldname="FCONTINENTS" sourceref="SESExampleModelDataSource" />
  </metadatabindings>
  <sources>
    <source id="SESExampleModelDataSource" handler="SmartLogicSESConnector">
      <initialize>
        <parameters>
          <parameter name="ses.api.url">http://smartlogic.example.com/ses</parameter>
          <parameter name="ses.api.tbdb">Example</parameter>
          <parameter name="metadatabinding">
            <fields>
              <field name="FLOCATION" level="logical">
                <read>
                  <entrynodes/>
                  <fieldfilters>
                    <field name='FCONTINENTS' level='logical'/>
                  </fieldfilters>
                  <selectable>
                    <condition name="CLASS">city</condition>
                  </selectable>
                  <relations>
                    <relation ref="narrowerterm" />
                  </relations>
                </read>
              </field>
              <field name="FCONTINENTS" level="logical">
                <read>
                  <entrynodes>
                    <static>
                      <id>34</id>   <!-- 34 is the id of Continents -->
                    </static>
                  </entrynodes>
                  <fieldfilters/>
                  <selectable>
                    <condition name="CLASS">continent</condition>
                  </selectable>
                  <relations>
                    <relation ref="narrowerterm" />
                  </relations>
                </read>
              </field>
            </fields>
          </parameter>
          <parameter name="relations">
            <relations>
              <relation type="hierarchical" id="narrowerterm" abbreviation="NT" direction="Forward"/>
            </relations>
          </parameter>
        </parameters>
      </initialize>
    </source>
  </sources>
</infoShareExtensionConfig>