VMG Chosen Member - Fieldtype for Expression Engine 2
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
ee2/third_party/vmg_chosen_member
themes/third_party/vmg_chosen_member
README.md

README.md

VMG Chosen Member

Fieldtype for ExpressionEngine 2 + 3

Note: if you're using ExpressionEngine 2, download VMG Chosen Member version 2.2 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.

Installation

  • Upload ee2/third_party/vmg_chosen_member to system/user/addons
  • Upload themes/third_party/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.

Upgrading

  • Back up your database
  • Upload ee2/third_party/vmg_chosen_member to system/expressionengine/third_party
  • Upload themes/third_party/vmg_chosen_member to themes/third_party
  • Go to Add-Ons > Modules and click the "Run Module Updates" button

Importing Old Member Selections

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.

Usage

Single Variable Tag

{custom_field}

Outputs the pipe (|) delimited list of member IDs.

Parameters

  • 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.

Variable Tag Pair

{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.

Parameters

  • 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.

:total_members Tag

{chosen_member_field:total_members}

Outputs the total number of members selected within the field.

Associated Entries

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}

Parameters

  • {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.

Usage with Channel Form / SafeCracker

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.

Support for other fieldtypes/add-ons

VMG Chosen Member can be used within Matrix, Low Variables, and Better Workflow.

Compatibility

VMG Chosen Member has been tested to work on ExpressionEngine 3.3+ with PHP 5.6+.

Warranty/License

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.