Specifying dependencies between editors

You can set up dependencies between editors in the same cartridge such that the behavior of one editor is dependent upon a property that is bound to another editor in the cartridge.

In a typical editor definition you can specify whether the editor is enabled via the enabled attribute. Editors are enabled by default. You can disable the editor by setting the value of enabled to false as follows: 

<StringEditor propertyName="moreLinkText" label="Title" enabled="false"/>

In this case, the value of the associated property (in this case, moreLinkText) displays in the Content Details Panel but cannot be updated by the user.

The enabled status of an editor can be updated dynamically based on the value of another property by replacing the literal value of the enabled attribute (either true or false) with an expression that is evaluated to determine the editor's behavior. For example: 

<StringEditor propertyName="moreLinkText" label="Title" enabled="{showMoreLink == true}"/>

In this case, the string editor that enables editing of the text for the "More" link is not enabled unless the property showMoreLink (which is bound to another editor) is set to true. This kind of dependency enables you to assemble complex editing interfaces out of simple property editors, without writing custom editors that contain the dependency logic.

The following example shows a template with two editors, where the enabled state of one editor depends on the value of the property bound to the other editor. In this case, the string editor is disabled by default (because the value of showMoreLink is false by default) and is not enabled until the user selects the "Enable 'More' link" option in the Boolean editor. 

<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008"
                 xmlns:xavia="http://endeca.com/schema/xavia/2010"
                 xmlns:editors="editors"
                 type="SidebarItem" id="FlatDimension">
    <!-- additional elements deleted from this example -->
  <ContentItem>
    <Name>Flat Dimension Example</Name>
    <Property name="showMoreLink">
      <Boolean>false</Boolean>
    </Property>
    <Property name="moreLinkText">
      <String>Show More Refinements...</String>
    </Property>
  </ContentItem>
  <EditorPanel>
    <BasicContentItemEditor>
      <editors:BooleanEditor propertyName="showMoreLink" 
        label="Enable 'More' link" enabled="true"/>
      <StringEditor propertyName="moreLinkText" 
        label="'More' link text" enabled="{showMoreLink == true}"/>
    </BasicContentItemEditor>
  </EditorPanel>
</ContentTemplate>

The value of an attribute is treated as an expression if it is contained within {curly braces}, otherwise it is treated as a literal value.

There is no validation for editor dependency expressions within a template, however, if an expression contains syntax errors, an InvalidExpressionError is thrown upon initialization of the editor. Currently, the only attribute for which expressions are evaluated is the enabled attribute.

The expression language enables you to evaluate an expression based on the value of a particular property in the same cartridge by comparing it to either a Boolean or string literal.

Operand

Description

Example expression

property name

The name of the property that the editor depends on. The value of this property is used during the evaluation of the expression.

The property is treated as a Boolean if it is specified as the <Boolean> type, otherwise it is treated as a string.

{sort == 'static'}

true

Treated as a Boolean literal.

{showMoreLink == true}

false

Treated as a Boolean literal.

{showMoreLink == false}

'string in single quotes'

Treated as a string literal.

{sort == 'static'}

The expression language provides the following comparison operators for use in editor dependency expressions. Order of operations are respected in editor dependency expressions.

Operator

Description

Example expression

==

Equality

{sort == 'static'}

!=

Inequality

{sort != 'static'}

||

Logical OR

{sort == 'static' || sort == 'default'}

&&

Logical AND

{sort == 'price' && order == 'desc'}

no operator

If the expression is a property name, it evaluates to the value of the property.

{showMoreLink}

!

Logical NOT

{!showMoreLink}

( and )

Groups expressions in order to enforce a particular evaluation order.

{showMoreLink == true && (sort == 'static' || sort == 'default')}

Because the editor dependency expressions are embedded in XML, it is important to apply the appropriate escaping to special characters within expressions.

The editor dependency language supports two different ways to escape special characters.

Use this style of escaping for handling characters that may lead to invalid XML.

Name

Character representation

Escape sequence

Note

ampersand

&

&amp;

Required, otherwise the XML document is invalid.

less than sign

<

&lt;

Required, otherwise the XML document is invalid.

quotation mark

"

&quot;

Required. Quotation marks designate the attribute value in XML. Since the editor dependency expression is defined in an attribute value, the quotation mark must be escaped or the XML document is invalid.

greater than sign

>

&gt;

Optional. While escaping this character is not required to ensure that the XML is valid, Oracle recommends that you escape the greater than sign as with the less than sign.

apostrophe or single quotation mark

'

&apos;

Optional. Since single quotes are also used to designate string literals, you must escape single quotation marks within a string literal. However, for readability, Oracle recommends that you escape single quotes using the alternative sequence \' instead.

Use this style of escaping for an alternate method of escaping the single quotation mark or for handling other special characters.

Character name

Escape sequence

single quotation mark

\'

backslash

\\

backspace

\b

horizontal tab

\t

line feed (new line)

\n

vertical tab

\v

form feed

\f

carriage return

\r

The following examples show editor dependency expressions and their escaped forms.

Unescaped expression

Escaped format

{sort == 'price' && order == 'desc'}

{sort == 'price' &amp;&amp; order == 'desc'}

{generateMetadata == 'Don't generate'}

{generateMetadata == 'Don\'t generate'}

{welcomeMessage == 'Hello, <name>!'}

{welcomeMessage == 'Hello, &lt;name&gt;!'}

In some cases, when an editor is dynamically enabled based on the value of another property, you want to ensure that the associated property has a specific value when the editor is disabled.

Specifying a "disabled value" for an editor ensures that whenever the enabled expression evaluates to false (that is, the editor is dynamically disabled), the associated property is set to the specified value. This can be useful in the case where the value of the property associated with the editor should be set to a default value whenever the editor is disabled.

The disabled value for an editor is optional. If no value is specified and an editor is disabled, then its property retains its most recently set value (whether this was originally a default value or specified by the content administrator in Experience Manager). The content administrator cannot update the value while the editor is disabled, but it preserves the latest setting in the case that the content administrator re-enables the editor at a later point.

To specify a default value for an editor:

  1. Specify a disabledValue attribute in the editor definition. 

      <editors:RadioGroupEditor propertyName="showDisabledRefinements" 
    label="Show 'Disabled Refinements'" 
    enabled="{sort == 'static'}"
		  disabledValue="false"/>

    As with default property values, ensure that the disabled value for the property meets the constraints defined by the editor. For a choice editor or radio group editor, is must be one of the options defined for the editor in a <choice> element. For a numeric editor, it must be between the minimum and maximum values for the editor.

The following example shows a radio group editor configured with a disabled value. 

<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008"
                 xmlns:xavia="http://endeca.com/schema/xavia/2010"
                 xmlns:editors="editors"
                 type="SidebarItem" id="FlatDimension">
    <!-- additional elements deleted from this example -->
    <ContentItem>
        <Name>New Text Link Flat Dimension</Name>
        <!-- additional elements deleted from this example -->
        <Property name="sort">
            <String>default</String>
        </Property>
        <Property name="showDisabledRefinements">
            <String>false</String>
        </Property>
        <!-- additional elements deleted from this example -->
    </ContentItem>
    <EditorPanel>
        <BasicContentItemEditor>
            <!-- additional elements deleted from this example -->
            <editors:ChoiceEditor label="Sorting Options" propertyName="sort">
                <choice label="Dimension default" value="default"/>
                <choice label="Alphanumeric" value="static"/>
                <choice label="By frequency" value="dynRank"/>
            </editors:ChoiceEditor>
            <editors:RadioGroupEditor propertyName="showDisabledRefinements"
                label="Show 'Disabled Refinements'" 
                enabled="{sort == 'static'}"
                disabledValue="false">
                    <choice label="Yes" value="true"/>
                    <choice label="No" value="false"/>
            </editors:RadioGroupEditor>
            <!-- additional elements deleted from this example -->
        </BasicContentItemEditor>
    </EditorPanel>
</ContentTemplate>

When the Content Details Panel is first instantiated, the selected value for the radio group editor is false, which displays with the label "No," and the editor is disabled, because the default value of the sort property is not equal to static. If the content administrator selects "Alphanumeric" from the choice editor, the radio group editor is enabled, and the content administrator can change the value of showDisabledRefinements to true. However, if the content administrator later selects a different value from the choice editor (either "Dimension default" or "By frequency"), the radio group editor is once again disabled and the value of showDisabledRefinements set to false.

Copyright © Legal Notices