Provides functionalities for entity fields autocompletion, like a menu callback that autocompletes any entity that defines a label, or a ready to use form element.
The purpose is to help developers by having a ready-to-use auto-complete form element to retrieve a reference to an entity using AJAX. This module does not store anything, this part being to the responsibility of the developer.
A helper function allows to get the entity ID from the input value: entity_autocomplete_get_id()
.
How to use
To use the auto-completion feature within a custom module:
- Entity definition: Make sure the entity to use have a label, especially if you use a custom entity type. The entity's info array returned from hook_entity_info() needs to declare 'label' in 'entity keys'. This needs to be set to a field name you want to use as the display label of the entity.
- Using in own forms: There are two ways to use the module:
- Using built-in type: Create an element of type entity_autocomplete with the key #autocomplete_path defining the path to the auto-complete path. You can specify extra keys to override the default values provided by the element (@see
entity_autocomplete_element_info()
).
This element type returns directly the entity ID. - Using custom element: you can define a form element and specify the #autocomplete_path key. Take care that this feature is not compatible with all element types. It is expected to be used with text fields.
Using this way, the value needs to be processed byentity_autocomplete_get_id()
to get the entity ID.
- Using built-in type: Create an element of type entity_autocomplete with the key #autocomplete_path defining the path to the auto-complete path. You can specify extra keys to override the default values provided by the element (@see
Example
$form['my_entity_reference'] = array(
'#type' => 'entity_autocomplete',
'#title' => t('My Entity'),
'#default_value' => '',
'#autocomplete_path' => 'entity-autocomplete/myentity',
);
Auto-complete paths
There are several possible path types that may be used.
Without bundle restriction
- Path:
entity-autocomplete/[entity-type]/[search-string]
, where:- [entity-type] is the machine name of the entity type.
- [search-string] is the user entered string.
- Path specified in the #autocomplete_path key:
entity-autocomplete/[entity-type]
When using the entity_autocomplete form element, there is no need to specify the auto-complete path, which can be created automatically when you specify the #entity_type key:
$form['my_entity_reference'] = array(
'#type' => 'entity_autocomplete',
'#title' => t('Entity Autocomplete test field'),
'#entity_type' => 'store_location',
'#default_value' => '',
);
With bundle restriction
- Path:
entity-autocomplete/bundle/[entity-type]/[list-of allowed-bundles]/[search-string]
, where:- [entity-type] is the machine name of the entity type.
- [list-of allowed-bundles] is a list of allowed bundle machine names, like my_bundle_1+my_bundle_2
- [search-string] is the user entered string.
- Path specified in the #autocomplete_path key:
entity-autocomplete/[entity-type]/[list-of allowed-bundles]
The auto-complete path is optional if using the #bundles key:
$form['my_entity_reference'] = array(
'#type' => 'entity_autocomplete',
'#title' => t('Entity Autocomplete test field'),
'#entity_type' => 'store_location',
'#bundles' => array('info', 'another'),
'#default_value' => '',
);