Core - Administration Guide : Autocomplete

21 March 2016

1. Autocomplete

The autocomplete makes it easier to enter values in fields. It can be used for example when specifying what kind of Part the user wants to create, enter the Responsible Design Organization (related object) for a part or select units of measure for a part (ranges of attribute).

On server side the AutoCompleteHandler (handler) is responsible for providing available values for a field. The value consist of the actual value that is stored in the database, ex. object id, and a display value which the user is presented with. TVC comes with a number of built-in handlers.

Selectize is used on client side to render the field where user can enter values along with the dropdown containing available options. The plugin has a high level of configurability making it possible to set for instance how many options that should be presented, how to render them, ordering of options and much more.

This autocomplete documentation applies to Top Panel, Structure Browser tables and Create/Edit Forms.

1.1. Settings

There are two categories of settings:

  1. Selectize. These controls the behavior of the Selectize plugin. See the Selectize usage page for a full reference.

  2. AutoCompleteHandler. Defines settings for the handler. Handler settings are wrapped in a handler object to don’t collide with Selectize settings. These settings are described in detail in the following chapters.

1.2. Built-in handlers

Use lowercase name of handler when specifying handler to use.

Common settings for all handlers:

Name Description Default

name

Defines the AutoCompleteHandler to use. Enter the name of a built-in handler or specify the qualified name of your java class.

user

caseSensitive

Defines if searches are case sensitive.

false

contains

Must the value start with the search criteria.

true

limit

Maximum amount of results that is returned from server.

50 (configured by the tvc.core.autocomplete.defaultLimit property)

localize

1.2.1. User

Name Description Default

assignments

Users must be assigned the role/group to be displayed.

returnOid

Returns the object id instead user name as value.

false

1.2.2. Type

Name Description Default

rootTypes

Defines types to be searched. All sub types are also searched

All types

returnAbstractTypes

Defines if abstract types should be searched.

false

exclude

Defines which types are to be excluded from the selection.

 
<Field id="typeField">
	<Label>Type</Label>
	...
	<FieldType>select</FieldType>
	<Setting name="options">
	{
		"autocomplete": {
			"handler" : {
				"name": "type",
				"rootTypes":["Part","DOCUMENTS"],
				"exclude":["type_ArtworkTemplate","Artwork Annotation"]
			}
		}
	}
	</Setting>
</Field >
exclude accepts comma separated values. Values can be either symbolic or actual names of types to be excluded.

1.2.3. DataSet

Uses a dataset to define available search options. If the field is in context of an object, e.g. in a top panel, the object id will be available in the dataset. This makes it possible to do operations which requires input, e.g. expansions.

Name Description Default

dataset

Name of the dataset to use. The settings is mandatory.

Example:

"dataset" : "tvc:dataset:tvx:enc/ECOs.xml"

value

Select expression selecting the value

id

label

Defines what data to use as label. Supports macros.

Examples:

"label" : "$<name>"

"label" : "$<attribute[attribute_MarketingName]> ($<name>)"

$<name>

select

Defines additional data to fetch and return to the UI. Add one or more select expressions. Supports macros.

The selected data can be used to make more advanced option rendering at the client using the Selectize settings rendering.

Examples:

"select" : ["id"]

"select" : ["id", "description", "$<attribute[attribute_MarketingName]>"]

Example using dataset handler in Forms:

<ConnectField>
    <Label>Part Family</Label>
    <Relationship>
        <Name>relationship_ClassifiedItem</Name>
        <Direction>to</Direction>
    </Relationship>
    <AutoCompleteHandler>dataset</AutoCompleteHandler>
    <AutoCompleteSettings><![CDATA[{
        handler : {
            dataset : 'tvc:dataset:tvx:enc/PartFamilies.xml',
            value : 'id',
            label : '$<name>'
        }
    }]]></AutoCompleteSettings>
</ConnectField>

1.2.4. Ranges

Displays ranges available for the field/cell.

1.2.5. Organization

No additional settings.

1.2.6. BusinessObject

Searches for business objects using a query. Most often you enter some criteria to limit the search result, for example you will add a typePattern and whereClause to only get the first revision of parts.

Name Description Default

typePattern

Type pattern to search for.

namePattern

Name pattern to search for.

revisionPattern

Revision pattern to search for.

vaultPattern

Vault pattern to search for.

whereClause

Where clause to use.

matchOn

expandType

True

displayMacro

searchType

How the search criteria will operate.

Available values:

* contains * startsWith * endsWith

1.3. Examples

Custom rendering of options using dataset handler in Forms:

<ConnectField>
    <Label>ECO to release</Label>
    <Relationship>
        <Name>relationship_AffectedItem</Name>
        <Direction>to</Direction>
    </Relationship>
    <AutoCompleteHandler>dataset</AutoCompleteHandler>
    <AutoCompleteSettings><![CDATA[{
        'handler' : {
            'dataset' : 'tvc:dataset:tvx:enc/ECOs.xml',
            'value' : 'id',
            'select' : ['$<name>', '$<attribute[attribute_Severity]>', '$<attribute[attribute_Priority]>']
        },
        'labelField' : 'name',
        'searchField' : ['name', 'select_2', 'select_3'],
        'render' : {
            'option' : function(item, escape) {
                var option = [];
                option.push('<div style="border-bottom: 1px solid #ccc;">');
                option.push(escape(item.name)
                    + "<br/><b>Severity:</b> "
                    + escape(item.select_2)
                    + "<br/><b>Priority:</b> "
                    + escape(item.select_3));
                option.push('</div>');
                return option.join('');
            }
        }
    }]]></AutoCompleteSettings>
</ConnectField>
Select statements are replaced with select_1, select_2 and so on. This is done because complex select statements doesn’t comply with JSON naming standards.