Note: if you're using ExpressionEngine 2, download VMG Chosen Member version 2.2.1 here.
VMG Chosen Member is a fieldtype for allowing the selection of one or more members inside an entry. It's specifically designed for use on sites with a large amount of members, in cases where a regular <select> dropdown with thousands of <option>s would decrease publish page performance.
It includes autocomplete capabilities and the friendly selection/listing of large numbers of members using a modified version of the Chosen JavaScript plugin. VMG Chosen Member also offers various methods of using the selected members within your templates.
VMG Chosen Member can be used alone, within Matrix, Low Variables, and Better Workflow.
- Upload system/user/addons/vmg_chosen_member to system/user/addons
- Upload themes/user/vmg_chosen_member to themes/user
- Install the fieldtype by going to Add-Ons → Fieldtypes
- Ensure that both the Fieldtype and Module are installed
- See Importing Old Member Selections below if you are converting from a different field type that contains pipe-delimited member IDs.
- Back up your database
- Upload system/user/addons/vmg_chosen_member to system/user/addons
- Upload themes/user/vmg_chosen_member to themes/user
- Go to Add-Ons > Modules and click the "Run Module Updates" button
If you are upgrading to VMG Chosen Member from a different field type that contains pipe-delimited member IDs, you can have those selection automatically imported in to VMG Chosen Member's data structure by following the steps below:
- Ensure the desired fields have been switched to the VMG Chosen Member field type.
- Go to Add-Ons > Modules > VMG Chosen Member
- Click the "Convert old field data" button, and your previous selections will be automatically imported.
{custom_field}
Outputs the pipe (|) delimited list of member IDs.
- member_id = "1|2|3"
Limit returned members to those specified. - group_id = "1|2|3"
While you can limit selections to specific member groups in the field's settings, this parameter allows you to further limit results on output. - orderby = "email"
The orderby parameter sets the display order of the output. - sort = "asc"
The sort order will be applied if you specify an orderby parameter. - limit = "1"
The limit parameter will set the number of results that will be returned. - backspace = "0"
Remove X number of characters from the final tag output.
{custom_field}
<h2>{cm_screen_name}</h2>
<p>Email: {cm_email}</p>
<p>Some custom member field: {cm_some_custom_member_field}</p>
{/custom_field}
Outputs member data for the selected members and provides access to all data tags.
Note: A prefix of "cm_" is added by default, but can be manually changed or set to empty if desired.
- All parameters from the Single Tag Pair plus:
- prefix = "cm_"
Set to "cm_" by default
By providing a prefix, all data tags will be parsed prepended with the string of your choosing. This can be helpful for avoiding naming collisions. - backspace = "0"
Remove X number of characters from the final tag output. - disable = "member_data"
Setting this to member_data will bypass the loading of custom member fields.
{chosen_member_field:total_members}
Outputs the total number of members selected within the field.
To view Channel Entries that a member has been selected in (via a VMG Chosen Member field), you can use the {exp:vmg_chosen_member:assoc_entries} tag.
NOTE: As of v2.0, this tag mimics the functionality of a Channel Entries loop. To disable this, and simply return a pipe-delimited list of entry IDs, set display_entries="no".
{!-- Standard usage --}
{exp:vmg_chosen_member:assoc_entries
field="chosen_member_field"
member_id="1|2|3"
}
<ul>
{chosen_member_field prefix="cmf_"}
<li>
<h3>{cmf_screen_name}</h3>
<img src="/path/to/avatars/{cmf_avatar_filename}"/>
</li>
{/chosen_member_field}
</ul>
{/exp:vmg_chosen_member:assoc_entries}
{!-- Example of using display_entries="no" --}
{exp:vmg_chosen_member:assoc_entries
field="chosen_member_field"
member_id="1|2|3"
prefix="cm_"
display_entries="no"
}
Pipe-delimited list of related entry IDs: {cm_entry_ids}
{/exp:vmg_chosen_member:assoc_entries}
- {exp:vmg_chosen_member:assoc_entries} can take nearly all of {exp:channel:entries}’ tag parameters, as well as the following:
- field = "chosen_member_field"
The VMG Chosen Member field you would like to search. If your VMG Chosen Member field is within a Matrix field, you would set the name of the parent Matrix field. - col = "my_matrix_col"
If your VMG Chosen Member field is within a Matrix field, you would set the name of the Matrix column here. - member_id = "1|2|3"
Member IDs that you would like to search for. - display_entries = "yes"
Set to "yes" by default
If "yes", this tag will mimic a Channel Entries loop. Otherwise, it returns a variable called {entry_ids} containing a pipe delimited list of all relevant entry IDs. - prefix = "cm_"
Set to "cm_" by default
If display_entries = "no", the {entry_ids} single variable will be parsed prepended with the string of your choosing. This can be helpful for avoiding naming collisions.
Returns all relevant entries. If display_entries = "no", outputs the prefixed {entry_ids} tag.
In order to correctly render the Chosen field within Channel Form or SafeCracker, you will need to ensure that the field assets are loaded. Simply include the following tag somewhere on your page:
{exp:vmg_chosen_member:init_ft type="css|js"}
Note that you can pass a type parameter to render the CSS, JS, or both.
VMG Chosen Member can be used within Matrix, Low Variables, and Better Workflow.
VMG Chosen Member has been tested to work on ExpressionEngine 3.3+ with PHP 5.6+.
There's no warranty of any kind. If you find a bug, please report it or submit a pull request with a fix. It's provided completely as-is; if something breaks, you lose data, or something else bad happens, the author(s) and owner(s) of this add-on are in no way responsible.
This add-on is owned by Vector Media Group, Inc. You can modify it and use it for your own personal or commercial projects, but you can't redistribute it.