ReferenceSearchFilter can contain multiple attributes used in filters. In addition, more search operators are available. There may be multiple filters configured for one attribute: one filter for one source-target template pair. After one filter has been saved, a new empty filter text area will appear for defining a new filter.

Currently ReferenceSearchFilter can be used with any reference attribute whose handler doesn't alter the default editing view of the attribute. This means that ReferenceSearchFilter does not work for example with CategoryDropDownReferenceHandler.

Configuration of ReferenceSearchFilter is done in attribute metadata editor with the EQL Editor. A filter created with the editor is automatically converted into Efecte Query Language (EQL).

Example of configuring a reference search filter using the EQL editor.

Attribute metadata editor showing an example ReferenceSearchFilter configuration. The metadata value is an EQL query, generated by the EQL Editor.

Source Template Configuration

As illustrated above, the filter configuration contains an editor for selecting source and target templates for filter, matching conditions and ordering of the results. This editor is also used in configuring some other functionality and is therefore explained in the  EQL Editor article with the exception of source template field that is specific to the reference search filter.

Source template is essential if the attribute to be edited is attached to multiple templates and it is intended to have different filters for separate templates. A filter can be set for all source templates containing the attribute. The All-value is usable also when the reference attribute is attached to one template only. However, it is not possible to attach the same filter to some, but not all, potential source templates. For this kind of usage, multiple filters must be created for all needed source templates.

Using Filtered Reference Search

Since 2015, references are displayed as dropdown elements. The filters are applied automatically and they can't be disabled by end-user.

Non-matching Filtering Conditions can be Ignored by ? Character

Conditions can contain reference paths, which are not valid, if the part of the path is missing in data card's data. Such paths can be marked "ignorable" by using ? character in search condition.

For example:

select entity from entity
           where $mid_category$ in #referrer:?ce_mid_category#
           and $mid_category$ in #referrer:?ce_low_category:mid_category#
           and template.code = 'top_category'exclude

• ?ce_mid_category - if there is no value in ce_mid_category, the condition is ignored
• ?#referrer:?ce_low_category:mid_category - if there is no value in ce_low_category, the condition is ignored

This feature can be used to replace Handler - CategoryDropdownReference which can be started to select values from middle levels too.

See example template configuration:

Reference search filter example - Categorization using single template

Category feature can be implemented using one Category template only. This is usable if all levels of categorization holds the same data. In data card editor user can start selecting data values from which level he wants. Categorization is tree: a category can have multiple subcategories but only one parent.

Categorization template must have 3 attributes. Template code is "single_category_template".

• Name: a String
• Children: Multivalue reference attribute fixed to the same template. Code “children”
• Parent: Singlevalue reference to the Children-attribute. Code "parent"

The template who uses this kind of categorization can have as many sub categories as needed. Here is example with three-level categories. Pay attention to attribute codes meaning categorization levels "first", "second" and "third".

Top level category attribute refers to Category-template. Code is "first". Metadata for filtering is:

select entity from entity
where $children$ in #referrer:?second#
and $children$ in #referrer:?third:parent#
and $parent:parent$ is null
and $parent$ is  null
and template.code = 'single_category_template'

Second level category attribute refers to Category-template. Code is "second" Metadata for filtering is:

select entity from entity
where $parent$ in #referrer:?first#
and $children$ in #referrer:?third#
and $parent$ is not null
and $parent:parent$ is null
and template.code = 'single_category_template'

Third level category attribute refers to Category-template. Code is "third". Metadata for filtering is:

select entity from entity
where $parent$ in #referrer:?first:children#
and $parent$ in #referrer:?second#
and $parent$ is not null
and $parent:parent$ is not null
and template.code = 'single_category_template'

Reference Search Filter Example - Categorization Using Multiple Template

<?xml version="1.0" encoding="utf-8"?>

<templateset>
    <template>
        <id>269</id>
        <code>single_category_template</code>
        <name>Single category</name>
        <system-code>bso</system-code>
        <protected>false</protected>
        <metadata>
            <name>allow_copy_data_cards</name>
            <value>true</value>
        </metadata>
        <class>
            <id>612</id>
            <template-class-id>1154</template-class-id>
            <name>Single category</name>
            <order>0</order>
            <collapsed>false</collapsed>
            <attribute>
                <id>2762</id>
                <class-attribute-id>3208</class-attribute-id>
                <code>name</code>
                <name>Name</name>
                <datatype>string</datatype>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>100</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>true</required>
                <protected>false</protected>
            </attribute>
            <attribute>
                <id>2863</id>
                <class-attribute-id>3209</class-attribute-id>
                <code>parent</code>
                <name>Parent category</name>
                <datatype>reference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>200</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
            <attribute>
                <id>2867</id>
                <class-attribute-id>3214</class-attribute-id>
                <code>children</code>
                <name>Children</name>
                <datatype>backreference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>true</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>300</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>backreference_269_3214</name>
                    <value>269_3209</value>
                </metadata>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
        </class>
    </template>
    <template>
        <id>268</id>
        <code>single_category_template_example</code>
        <name>Single category template example</name>
        <system-code>bso</system-code>
        <protected>false</protected>
        <metadata>
            <name>allow_copy_data_cards</name>
            <value>true</value>
        </metadata>
        <class>
            <id>613</id>
            <template-class-id>1155</template-class-id>
            <name>Single category</name>
            <order>0</order>
            <collapsed>false</collapsed>
            <attribute>
                <id>2762</id>
                <class-attribute-id>3213</class-attribute-id>
                <code>name</code>
                <name>Name</name>
                <datatype>string</datatype>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>50</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
            </attribute>
            <attribute>
                <id>2864</id>
                <class-attribute-id>3210</class-attribute-id>
                <code>first</code>
                <name>First level</name>
                <datatype>reference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>100</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>empty_result_when_filter_invalid</name>
                    <value>true</value>
                </metadata>
                <metadata>
                    <name>filter_single_category_template_example-&gt;single_category_template</name>
                    <value>select entity from entity
where $children$ in #referrer:?second#
and $children$ in #referrer:?third:parent#
and $parent:parent$ is null
and $parent$ is  null
and template.code = 'single_category_template'</value>
                </metadata>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
            <attribute>
                <id>2865</id>
                <class-attribute-id>3211</class-attribute-id>
                <code>second</code>
                <name>Second level</name>
                <datatype>reference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>200</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>empty_result_when_filter_invalid</name>
                    <value>true</value>
                </metadata>
                <metadata>
                    <name>filter_single_category_template_example-&gt;single_category_template</name>
                    <value>select entity from entity
where $parent$ in #referrer:?first#
and $children$ in #referrer:?third#
and $parent$ is not null
and $parent:parent$ is null
and template.code = 'single_category_template'</value>
                </metadata>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
            <attribute>
                <id>2866</id>
                <class-attribute-id>3212</class-attribute-id>
                <code>third</code>
                <name>Third level</name>
                <datatype>reference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>300</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>empty_result_when_filter_invalid</name>
                    <value>true</value>
                </metadata>
                <metadata>
                    <name>filter_single_category_template_example-&gt;single_category_template</name>
                    <value>select entity from entity
where $parent$ in #referrer:?first:children#
and $parent$ in #referrer:?second#
and $parent$ is not null
and $parent:parent$ is not null
and template.code = 'single_category_template'</value>
                </metadata>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
        </class>
    </template>
</templateset>

Reference Search Filter Example - Categorization Using Single Template - Entity Set

<?xml version="1.0" encoding="utf-8"?>
<entityset>
    <entity id="7" name="A">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A</value>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="8" name="A-A" code="parent"/>
            <reference id="10" name="A-B" code="parent"/>
            <reference id="12" name="A-C" code="parent"/>
        </attribute>
    </entity>
    <entity id="8" name="A-A">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-A</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="7" name="A"/>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="9" name="A-A-A" code="parent"/>
        </attribute>
    </entity>
    <entity id="9" name="A-A-A">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-A-A</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="8" name="A-A"/>
        </attribute>
    </entity>
    <entity id="10" name="A-B">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-B</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="7" name="A"/>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="11" name="A-B-A" code="parent"/>
        </attribute>
    </entity>
    <entity id="11" name="A-B-A">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-B-A</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="10" name="A-B"/>
        </attribute>
    </entity>
    <entity id="12" name="A-C">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-C</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="7" name="A"/>
        </attribute>
    </entity>
    <entity id="15" name="B">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>B</value>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="14" name="B-B" code="parent"/>
        </attribute>
    </entity>
    <entity id="14" name="B-B">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>B-B</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="15" name="B"/>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="13" name="B-B-C" code="parent"/>
        </attribute>
    </entity>
    <entity id="13" name="B-B-C">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>B-B-C</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="14" name="B-B"/>
        </attribute>
    </entity>
</entityset>

Empty Result When Search Filter Cannot be Applied

By default, if a search filter can't be applied (e.g. missing reference paths) the result will contain all possible datacards. If this value is set true, the result will be empty. Default value is false.