Documentation Center

Show only a subtree of the taxonomy structure (using explicit 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 explicit 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 show a fixed subtree, namely the subtree below continent Australia and the subtree below Hemispheres. However, we will use explicit relations in this example to limit the tree even more and not show cities. We limit the user so that he can only select hemispheres.

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

Australia                 {id=5, class=continent, selectable=no}
    - Australia           {id=38, class=country, selectable=no}
Hemispheres               {id=99, class=category, selectable=no}
    - Northern            {id=203, class=hemisphere, selectable=yes}
    - Southern            {id=14, class=hemisphere, 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. Configure the static entry points for the field.
    1. Lookup the term id(s) you want to appear as root terms in SES
      As an example, the ids for Australia=5 and Hemispheres=99
    2. Configure the term id(s) as static entry points
      As an example, you can configure the ids by pasting the following xml part as entrynodes for the FLOCATION field
      
      <entrynodes>
          <static>
              <id>5</id>    <!-- id of continent Australia -->
              <id>99</id>   <!-- id of category Hemispheres -->
          </static>
       </entrynodes>
      
    With this configuration in place, the tree would show Australia and Hemispheres. All terms are selectable by the user.
  4. Add an explicit relation you want to use for the taxonomy 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 define a specific relationship to go from continent to country. To do that you can add the following XML part to the relations parameter
      
      <relation type="hierarchical" id="continent2country" abbreviation="NT" direction="Forward">
          <from>
              <condition name='CLASS'>continent</condition>
      				</from>
      				<to>
              <condition name='CLASS'>country</condition>
      				</to>
      </relation>
      
    2. Reference the relation in the field
      For the example, we will refer to the continent to country relationship, so you can add the following XML part to the field relations
      
      <relation ref="continent2country" />
      
    With this configuration in place, the tree would show Australia and Hemispheres + all countries underneath Australia (cities and hemispheres are not shown!). All terms are selectable by the user.
  5. (Optional) Add another explicit relation you want to use for the taxonomy structure
    1. Define the second relation in the relations parameter
      For the example, we will define a specific relationship to go from category to hemisphere. To do that you can add the following XML part to the relations parameter
      
      <relation type="hierarchical" id="category2hemisphere" abbreviation="NT" direction="Forward">
          <from>
              <condition name='CLASS'>category</condition>
          </from>
          <to>
              <condition name='CLASS'>hemisphere</condition>
          </to>
      </relation>
      
    2. Reference the second relation in the field
      For the example, we will refer to the category to hemisphere relationship, so you can add the following XML part to the field relations
      
      <relation ref="category2hemisphere" />
      
    With this configuration in place, the tree would show Australia and Hemispheres + all countries underneath Australia + all hemispheres underneath Hemispheres (cities are still not shown). All terms are selectable by the user.
  6. 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 hemispheres so add the condition.
    
    <selectable>
        <condition name="CLASS">hemisphere</condition>
    </selectable>
    
    Same taxonomy structure is shown, but from now on only hemispheres would be selectable.

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>99</id>   <!-- id of category Hemispheres -->
                    </static>
                  </entrynodes>
                  <selectable>
                    <condition name="CLASS">hemisphere</condition>
                  </selectable>
                  <relations>
                    <relation ref="continent2country" />
                    <relation ref="category2hemisphere" />
                  </relations>
                </read>
              </field>
            </fields>
          </parameter>
          <parameter name="relations">
            <relations>
              <relation type="hierarchical" id="continent2country" abbreviation="NT" direction="Forward">
                <from>
                  <condition name='CLASS'>continent</condition>
                </from>
	               <to>
                  <condition name='CLASS'>country</condition>
                </to>
              </relation>
              <relation type="hierarchical" id="category2hemisphere" abbreviation="NT" direction="Forward">
                <from>
                  <condition name='CLASS'>category</condition>
                </from>
                <to>
                  <condition name='CLASS'>hemisphere</condition>
                </to>
              </relation>
            </relations>
          </parameter>
        </parameters>
      </initialize>
    </source>
  </sources>
</infoShareExtensionConfig>