findDistinctValuesForField( (string) $element_handle, (string) $term = “”, (int) $maxValues = 0, (array) $scope_group_ids = array(), (array) $scope_uids = array(), (bool) $usePerGroupFilters = false )

Description

Find the different values stored for a form element, each one once, in alphabetical order. Optionally, only the values that contain some text, and only so many of them. Like findAllValuesForField, the values can be limited by user, by group, and by group permission filters.

Use this rather than findAllValuesForField when you only need some of the values, such as the ones that match what someone is typing. The database does the matching and the counting, so it doesn’t read every value in the form.

Parameters

$element_handle - the element handle to get values for
$term - Optional. Only values that contain this text. Its % and _ characters are matched as they are. Default is any value.
$maxValues - Optional. At most this many values. Default is 0, for no limit.
$scope_group_ids - Optional. An array of group ids that should be used to limit the query.
$scope_uids - Optional. An array of user ids that should be used to limit the query
$usePerGroupFilters - Optional. A boolean to indicate whether the current user’s group permission filters should be used to limit the query. The group permission filters are set in the permissions for the form, and can be used to restrict the entries that users can access according to arbitrary criteria.

Return Values

Returns an array of the values found, without blank values. If no values match, the array will be empty.

Returns false if the query fails.

Examples

// the first 20 cities in the Customers form that contain "san"
$dataHandler = new formulizeDataHandler(CUSTOMERS_FORM_ID);
$cities = $dataHandler->findDistinctValuesForField('cities', 'san', 20);
// every city, once each, in entries created by groups 5 and 10
$dataHandler = new formulizeDataHandler(CUSTOMERS_FORM_ID);
$cities = $dataHandler->findDistinctValuesForField('cities', scope_group_ids: array(5, 10));