Documentation Center

Show only a subtree of the taxonomy structure (using conditional relations)

We will configure the SDL Tridion Docs SES Connector in such a way the user will only be able to browse a specific subtree of terms. The tree shown is filtered even more by using conditions on the relations.

About this task

In Hypothetical taxonomy tree structure we defined a certain taxonomy structure. Instead of showing the entire taxonomy structure, we will configure the field FLOCATION in such a way that it will only show 2 fixed subtrees, namely the subtree below continents Australia and Europe. These terms will be the root terms or entry points in the tree. However, we will limit the tree even more, so that it will not show the cities anymore. We will allow all terms to be selectable.

So, we want the taxonomy structure shown for the FLOCATION field to be:

Australia                 {id=5, class=continent, selectable=yes}
  - Australia             {id=38, class=country, selectable=yes}
Europe                    {id=17, class=continent, selectable=yes}
  - France                {id=105, class=country, selectable=yes}

Procedure

  1. Open the extension configuration in the Content Manager web client via Settings > XML Extension Settings.
    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 static entry points for the field.
    1. Lookup the term ids you want to appear as root terms in SES
      As an example, the id for Australia=5 and Europe=17
    2. Configure the term ids as static entry points
      As an example, you can configure it by pasting the following XML part as entrynodes for the FLOCATION field
      
      <entrynodes>
          <static>
              <id>5</id>    <!-- id of continent Australia -->
              <id>17</id>   <!-- id of continent Europe -->
          </static>
       </entrynodes>
      
    With this configuration in place, the tree would show Australia and Europe as entry points of the tree for the FLOCATION field and their countries and cities (as they are narrower terms). All terms are selectable by the user.
  5. Add a condition on the relation definition
    By adding a condition on the relation, we limit the tree even more. You can define a condition on the "from" term and/or on the "to" term of the relation. The only supported condition name at this time is "CLASS".
    As an example, you could change the relation definition by pasting the following XML. You could leave out the "from" condition as the "to" condition alone is enough for the example as we only have countries under continents.
    
    <relation type="hierarchical" id="narrowerterm" abbreviation="NT" direction="Forward">
        <from>
            <condition name='CLASS'>continent</condition>
        </from>
        <to>
            <condition name='CLASS'>country</condition>
        </to>
    </relation>
    
    With this configuration in place, the tree would show Australia and Europe as entry points of the tree for the FLOCATION field and their countries. The cities would not be shown anymore, as we only follow the relation starting from continents towards countries, not to cities. All terms are selectable by the user.

Results

Complete XML Extension Settings configuration

<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>
                    <static>
                      <id>5</id>    <!-- id of continent Australia -->
                      <id>17</id>   <!-- id of continent Europe -->
                    </static>
                  </entrynodes>
                  <selectable/>
                  <relations>
                    <relation ref="narrowerterm" />
                  </relations>
                </read>
              </field>
            </fields>
          </parameter>
          <parameter name="relations">
            <relations>
              <relation type="hierarchical" id="narrowerterm" abbreviation="NT" direction="Forward">
                <from>
                  <condition name='CLASS'>continent</condition>
                </from>
                <to>
                  <condition name='CLASS'>country</condition>
                </to>
              </relation>
            </relations>
          </parameter>
        </parameters>
      </initialize>
    </source>
  </sources>
</infoShareExtensionConfig>