Documentation Center

Show only a subtree of the taxonomy structure (depending of values of another field)

We will configure the SDL Tridion Docs SES Connector in such a way the user will only be able to browse a subtree of terms from the taxonomy depending of the selected values of another field.

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 (dynamically) takes the values the user filled in for the FHEMISPHERE field and use them as entry points. For example: suppose that the user fills in the value "Northern" for the FHEMISPHERE field, the configuration will show these terms as root terms of the FLOCATION field, making only continent, countries, cities of the "Northern" hemisphere visible to the user. We will also limit the user so that he can only select countries or cities.

Some examples of the tree structure with dynamic entry points:

  • If the user did not select any value for the FHEMISPHERE field yet, the SES Connector would give an error as it does not have any terms to show as root nodes.
  • So, if the user filled in "Northern" for the FHEMISPHERE field, the tree structure shown for the FLOCATION field would be:
    
    Europe                    {id=17, class=continent, selectable=no}
      - France                {id=105, class=country, selectable=yes}
          - Paris             {id=12, class=city, selectable=yes}
    
  • So, if the user filled in "Southern" for the FHEMISPHERE field, the tree structure shown for the FLOCATION field would be:
    
    Australia                 {id=5, class=continent, selectable=no}
      - Australia             {id=38, class=country, selectable=yes}
          - Sydney            {id=46, class=city, 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. 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 countries and cities so define these as "CLASS" conditions.
    
    <selectable>
        <condition name="CLASS">country</condition>
        <condition name="CLASS">city</condition>
    </selectable>
    
    Same tree structure is shown, but from now on only countries or cities would be selectable.
  5. Configure the dynamic entry point field as a metadata bound field.
    As an example, you can configure it by pasting following XML part
    
        <metadatabinding ishfieldname="FHEMISPHERE" sourceref="SESExampleModelDataSource" />
    
  6. Configure the dynamic entry point field for the field.
    This configures that we want to show the values of the field as entry points or root terms of the tree structure for the field.
    As an example, you can configure it by pasting the following XML part as entrynodes for the FCOUNTRYORCITY field
    
    <entrynodes>
        <dynamic>
            <field name="FHEMISPHERE" level="logical"/>
        </dynamic>
     </entrynodes>
    
    With this configuration in place, if the user filled in Northern in the FHESMISPHERE field, the tree would show "Northern" as entry points of the tree for the FLOCATION field. It would not show anything else, as the continents underneath the hemispheres use a different relationship type.
  7. (Optional) Add a conversion relation
    If you want to use the terms the user filled in for the field to be your root terms of the tree, you can skip this step. In our case, we actually don't want the value(s) the user filled in to be the root terms of our tree, but terms related to them. To accomplish this, we define a conversion relation that defines which relation we want to use to convert the values the user filled in to the terms we want to show as entry points (root nodes) of the tree.
    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
      
      <entrynodes>
          <dynamic>
              <field name="FHEMISPHERE" level="logical">
                  <conversion>
                      <relation ref="hemisphere2continent" />
                  </conversion>
              </field>
          </dynamic>
       </entrynodes>
      
    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 the entry point of the tree for the FLOCATION field. If you would have multiple continents related to the Northern hemisphere, you would have multiple entry points. From these entry points, we now follow the defined relationships of the FLOCATION field (in our case only "narrowerterm"), so the tree will show the children of Europe.
  8. You need to configure the other field (the "dynamic entry point" field) as well, so the user can fill in values for it.

Results

Complete XML Extension Settings configuration

<infoShareExtensionConfig version="1.0">
  <metadatabindings>
    <metadatabinding ishfieldname="FLOCATION" sourceref="SESExampleModelDataSource" />
    <metadatabinding ishfieldname="FHEMISPHERE" sourceref="SESExampleModelDataSource" />
  </metadatabindings>
  <sources>
    <source id="SESExampleModelDataSource" handler="SmartLogicSESConnector">
      <initialize>
        <parameters>
          <parameter name="ses.api.url">http://smarlogic.example.com/ses</parameter>
          <parameter name="ses.api.tbdb">Example</parameter>
          <parameter name="metadatabinding">
            <fields>
              <field name="FLOCATION" level="logical">
                <read>
                  <entrynodes>
                    <dynamic>
                      <field name="FHEMISPHERE" level="logical">
                        <conversion>
                          <relation ref="hemisphere2continent" />
                        </conversion>
                      </field>
                    </dynamic>
                  </entrynodes>
                  <selectable>
                    <condition name="CLASS">country</condition>
                    <condition name="CLASS">city</condition>
                  </selectable>
                  <relations>
                    <relation ref="narrowerterm" />
                  </relations>
                </read>
              </field>
              <field name="FHEMISPHERE" level="logical">
                <read>
                  <entrynodes>
                    <static>
                      <id>99</id>  <!-- 99 is id of "Hemispheres" term -->
                    </static>
                  </entrynodes>
                  <selectable>
                    <condition name="CLASS">hemisphere</condition>
                  </selectable>
                  <relations>
                    <relation ref="narrowerterm" />
                  </relations>
                </read>
              </field>
            </fields>
          </parameter>
          <parameter name="relations">
            <relations>
              <relation type="hierarchical" id="narrowerterm" abbreviation="NT" direction="Forward"/>
              <relation type="associative" id="hemisphere2continent" abbreviation="RT" direction="Forward">
                <to>
                  <condition name="CLASS">continent</condition>
                </to>
              </relation>
            </relations>
          </parameter>
        </parameters>
      </initialize>
    </source>
  </sources>
</infoShareExtensionConfig>