Skip to content

Latest commit

 

History

History
101 lines (69 loc) · 3.24 KB

users-fields.md

File metadata and controls

101 lines (69 loc) · 3.24 KB
Raw

Users Fields

Users fields type allow you relate users to other elements.

Settings

Users fields have the following settings:

  • Sources – Which user groups (or other user index sources) the field should be able to relate users from.
  • 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.

Multi-Site Settings

On multi-site installs, the following setting will also be available (under “Advanced”):

  • Manage relations on a per-site basis – Whether each site should get its own set of related users.

The Field

Users fields list all of the currently-related 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.

Inline User Editing

When you double-click on a related user, a HUD will appear where you can edit the user’s custom fields.

Templating

Querying Elements with Users Fields

When querying for elements that have a Users field, you can filter the results based on the Users field data using a query param named after your field’s handle.

Possible values include:

Value Fetches elements…
':empty:' that don’t have any related users.
':notempty:' that have at least one related user. 
{# Fetch entries with a related user #}
{% set entries = craft.entries()
    .<FieldHandle>(':notempty:')
    .all() %}

Working with Users Field Data

If you have an element with a Users field in your template, you can access its related users using your Users field’s handle:

{% set relatedUsers = entry.<FieldHandle> %}

That will give you a user query, prepped to output all of the related users for the given field.

To loop through all of the related users, call all() and then loop over the results:

{% set relatedUsers = entry.<FieldHandle>.all() %}
{% if relatedUsers|length %}
    <ul>
        {% for rel in relatedUsers %}
            <li><a href="{{ url('profiles/'~rel.username) }}">{{ rel.name }}</a></li>
        {% endfor %}
    </ul>
{% endif %}

If you only want the first related user, call one() instead, and then make sure it returned something:

{% set rel = entry.<FieldHandle>.one() %}
{% if rel %}
    <p><a href="{{ url('profiles/'~rel.username) }}">{{ rel.name }}</a></p>
{% endif %}

If you just need to check if there are any related users (but don’t need to fetch them), you can call exists():

{% if entry.<FieldHandle>.exists() %}
    <p>There are related users!</p>
{% endif %}

You can set parameters on the user query as well. For example, to only fetch users in the authors group, set the groupId param:

{% set relatedUsers = entry.<FieldHandle>
    .group('authors')
    .all() %}

See Also