Users Fields
Users fields type allow you relate users to the parent element.
# Settings
Users fields have the following settings:
- Sources – The user groups you want to relate users from. (Default is “All”)
- Limit – The maximum number of users that can be related with the field at once. (Default is no limit.)
- Selection Label – The label that should be used on the field’s selection button.
# The Field
Users fields list all of the currently selected users, with a button to select new ones:
Clicking the “Add a user button will bring up a modal window where you can find and select additional users:
# Templating
If you have an element with a Users field in your template, you can access its selected users using your Users field’s handle:
{% set users = entry.usersFieldHandle %}
That will give you an ElementCriteriaModel object, prepped to output all of the selected users for the given field. In other words, the line above is really just a shortcut for this:
{% craft.users({
relatedTo: { sourceElement: entry, field: "usersFieldHandle" },
order: "sortOrder",
limit: null
}) %}
(See Relations for more info on the relatedTo
param.)
# Examples
To check if your Users field has any selected users, you can use the length
filter:
{% if entry.usersFieldHandle | length %}
...
{% endif %}
To loop through the selected users, you can treat the field like an array:
{% for user in entry.usersFieldHandle %}
...
{% endfor %}
Rather than typing “entry.usersFieldHandle
” every time, you can call it once and set it to another variable:
{% set users = entry.usersFieldHandle %}
{% if users | length %}
<h3>Some great users</h3>
{% for user in users %}
...
{% endfor %}
{% endif %}
You can add parameters to the ElementCriteriaModel object as well:
{% set authors = entry.usersFieldHandle.group('authors') %}
If your Users field is only meant to have a single user selected, remember that calling your Users field will still give you the same ElementCriteriaModel, not the selected user. To get the first (and only) user selected, use first()
:
{% set user = entry.myUsersField.first() %}
{% if user %}
...
{% endif %}