Skip to content

Commit b0424fd

Browse files
bryannielsenbryannielsen
authored
Merge pull request #601 from ExpressionEngine/feature/7.x/member-field
members field docs
2 parents 155c698 + e4dfcda commit b0424fd

File tree

8 files changed

+238
-2
lines changed

8 files changed

+238
-2
lines changed

‎docs/_images/field_members.png‎

16.5 KB
Loading

‎docs/add-ons/pro-variables/type.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ Allows applying modifiers, which, among other, are used to apply [on-the-fly ima
6060

6161
## Grid
6262

63-
Uses the native [Grid field](/fieldtypes/grid.md). All native types are available, _except for Relationships_. To output the variable, use the `{exp:pro_variables:pair}` or `{exp:pro_variables:single}` tag where appropriate. You can use any of Grid’s [parameters](/fieldtypes/grid.md#parameters) and [variables](/fieldtypes/grid.ms#variables) using these tags. Additionally, one more parameter is available:
63+
Uses the native [Grid field](/fieldtypes/grid.md). All native types are available, _except for Relationships and Members_. To output the variable, use the `{exp:pro_variables:pair}` or `{exp:pro_variables:single}` tag where appropriate. You can use any of Grid’s [parameters](/fieldtypes/grid.md#parameters) and [variables](/fieldtypes/grid.ms#variables) using these tags. Additionally, one more parameter is available:
6464

6565
### Parameters
6666

‎docs/development/extension-hooks/extension-hooks-overview.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Core hooks are categorized into 5 categories:
2929
- [Output Library](development/extension-hooks/global/output.md)
3030
- [Pagination Library](development/extension-hooks/global/pagination.md)
3131
- [Relationships Fieldtype](development/extension-hooks/global/relationships.md)
32+
- [Members Fieldtype](development/extension-hooks/global/member-ft.md)
3233
- [Session Library](development/extension-hooks/global/session.md)
3334
- [Template Library](development/extension-hooks/global/template.md)
3435
- [Text Helper](development/extension-hooks/global/text-helper.md)

‎docs/development/extension-hooks/global/member-ft.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
lang: php
3+
---
4+
5+
<!--
6+
This source file is part of the open source project
7+
ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide)
8+
9+
@link https://expressionengine.com/
10+
@copyright Copyright (c) 2003-2020, Packet Tide, LLC (https://packettide.com)
11+
@license https://expressionengine.com/license Licensed under Apache License, Version 2.0
12+
-->
13+
14+
# Members Fieldtype Extension Hooks
15+
16+
[TOC=3]
17+
18+
### `member_relationships_display_field($entry_id, $field_id, $sql)`
19+
20+
| Parameter | Type | Description |
21+
| ---------- | -------- | ------------------------------------------------------- |
22+
| \$entry_id | `Int` | Entry ID of entry being edited. |
23+
| \$field_id | `Int` | Field ID of field currently being loaded. |
24+
| \$sql | `String` | Compiled SQL about to be run to gather related members. |
25+
| Returns | `Array` | Result Array of query result. |
26+
27+
Allows developers to modify the existing query that retrieves related members for the publish field or to perform their own queries to return related members.
28+
29+
How it's called:
30+
31+
if (ee()->extensions->active_hook('member_relationships_display_field') === TRUE)
32+
{
33+
$related = ee()->extensions->call(
34+
'member_relationships_display_field',
35+
$entry_id,
36+
$this->field_id,
37+
ee()->db->_compile_select()
38+
);
39+
}
40+
else
41+
{
42+
$related = ee()->db->get()->result_array();
43+
}
44+
45+
NOTE: **Note:** To use this hook, you can either add to the existing Active Record call, or call `ee()->db->_reset_select()` to cancel the Active Record call and start your own, or modify the passed compiled SQL.
46+
47+
### `member_relationships_post_save($ships, $entry_id, $field_id)`
48+
49+
| Parameter | Type | Description |
50+
| ---------- | ------- | ---------------------------------------------- |
51+
| \$ships | `Array` | Array of member IDs to be related to the entry. |
52+
| \$entry_id | `Int` | Entry ID of entry being saved. |
53+
| \$field_id | `Int` | Field ID of field currently being saved. |
54+
| Returns | `Array` | Array of relationships. |
55+
56+
Allows developers to modify or add to the relationships array before saving.
57+
58+
How it's called:
59+
60+
$ships = ee()->extensions->call('member_relationships_post_save', $ships, $entry_id, $field_id);

‎docs/fieldtypes/member.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
<!--
2+
This source file is part of the open source project
3+
ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide)
4+
5+
@link https://expressionengine.com/
6+
@copyright Copyright (c) 2003-2020, Packet Tide, LLC (https://packettide.com)
7+
@license https://expressionengine.com/license Licensed under Apache License, Version 2.0
8+
-->
9+
10+
# Members Fieldtype
11+
12+
The Members Fieldtype allows selecting one or multiple members and associating those with a channel entry
13+
14+
[TOC]
15+
16+
The Members fieldtype helps you connect Members to Channel Entries. This lets you create powerful relationships between Members and content in your Channel entries. For example, you could create a Channel called "Articles" and a Channel Field called "Authors" that uses the Members fieldtype. You could then associate one or more Members with each Article entry. This would allow you to display the author's name, bio, photo, etc. on the Article page.
17+
18+
![members field](_images/field_members.png)
19+
20+
## Field Settings
21+
22+
#### Roles to include
23+
24+
Only allow selecting member with chosen primary roles. Note that secondary roles are not being taken into account when working with Members field.
25+
26+
#### Maximum number of available members
27+
28+
Sets the number of members displayed in the field's dropdown. Leave blank to allow all members. All members are still available to the search, this is simply a display setting.
29+
30+
#### Order By
31+
32+
Default ordering of members in the field's dropdown.
33+
34+
#### Allow Multiple Relationships?
35+
36+
When set to yes, authors will be allowed to create multiple relationships in a single field.
37+
38+
#### Minimum selection
39+
The minimum number of members that can be added to the field.
40+
41+
#### Maximum selection
42+
The maximum number of members that can be added to the field.
43+
44+
#### Display Member IDs?
45+
When enabled, member IDs will be displayed together with member screen name inside the field.
46+
47+
#### Defer field initialization?
48+
When enabled, this field won’t initialize until the Edit Members button is clicked on. This can result in faster control panel page load times.
49+
50+
## Template Tag Pair
51+
52+
The field is most useful when used as tag pair in the template. All variables are prefixed with the field's short name, followed by semicolon, to avoid naming conflicts.
53+
54+
{members_field}
55+
<div class="{members_field:switch="one|two"} id="row-{members_field:count}>
56+
<b>{members_field:screen_name}</b>
57+
- {members_field:username}
58+
- {members_field:custom_field}
59+
</div>
60+
{/members_field}
61+
62+
### Parameters
63+
64+
#### `backspace=`
65+
66+
backspace="7"
67+
68+
Just like the backspace parameter on the [Channel Entries](channels/entries.md) module, backspacing removes characters (including spaces and line breaks) from the last iteration of the loop.
69+
70+
### Variables
71+
72+
All variables inside field's tag pair are prefixed with the field's name and semicolon. So if the field is `members_field` you'll be accessing the related member's screen name as `{members_field:screen_name}`
73+
74+
#### `member_id`
75+
76+
#### `username`
77+
78+
#### `screen_name`
79+
80+
#### `email`
81+
82+
#### `join_date`
83+
84+
#### `last_visit`
85+
86+
#### `last_activity`
87+
88+
#### `last_entry_date`
89+
90+
#### `last_comment_date`
91+
92+
#### `last_forum_post_date`
93+
94+
#### `total_entries`
95+
96+
#### `total_comments`
97+
98+
#### `total_forum_topics`
99+
100+
#### `language`
101+
102+
#### `timezone`
103+
104+
#### `total_forum_posts`
105+
106+
##### `join_date`
107+
108+
{members_field:join_date format="%m/%d/%Y"}
109+
110+
##### `last_visit`
111+
112+
{members_field:last_visit format="%m/%d/%Y"}
113+
114+
#### `avatar_url`
115+
116+
#### `avatar_filename`
117+
118+
#### `avatar_width`
119+
120+
#### `avatar_height`
121+
122+
#### `role_id`
123+
124+
#### `primary_role_id`
125+
126+
#### `primary_role_name`
127+
128+
#### `primary_role_description`
129+
130+
#### `primary_role_short_name`
131+
132+
#### Custom Member Fields
133+
134+
All custom member fields as available using their prefixed short name.
135+
136+
{members_field:member_custom_field}
137+
138+
## Single Template Tag Modifiers
139+
140+
In addition to using as template tag pair, the Members field can display its data as single tag, when used with some pre-defined template modifiers.
141+
142+
### `:member_ids`
143+
Fetching Member IDs Only
144+
145+
Sometimes it's useful to get just a list of IDs of related members to pass on to another tag as a parameter. If you need to do this you can use the single variable `:member_ids` shortcut modifier:
146+
147+
{members_field:member_ids}
148+
149+
Which outputs the member IDs in the following format:
150+
151+
43|58|127
152+
153+
#### Parameters
154+
155+
The member field tag with the `:member_ids` modifier has an optional `delimiter` parameter.
156+
157+
By default the member IDs will be pipe-delimited, but you can choose to have them delimited with something else:
158+
159+
{members_field:member_ids delimiter=","}
160+
161+
Would output in the following format:
162+
163+
43,48,127
164+
165+
### `:length`
166+
### `:total_rows`
167+
168+
Both of these modifiers can be used to display the number of members that are related via a certain field
169+
170+
{members_field:length} // 2
171+
{members_field:total_rows} // 2

‎docs/fieldtypes/relationships.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
[TOC]
1313

14-
Relationships are an extremely powerful tool that allow you to connect Entries in one Channel to those in another one, or even to other entries in the same channel. This ability allows you to store very complex content in your Channel entries.
14+
Relationships are an extremely powerful tool that allows you to connect Entries in one Channel to those in another one, or even to other entries in the same channel. This ability allows you to store very complex content in your Channel entries.
1515

1616
This fieldtype is currently only limited to Channels.
1717

‎docs/toc_sections/_advanced_usage_toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,8 @@
203203
href: development/extension-hooks/global/pagination.md
204204
- name: Relationships Fieldtype
205205
href: development/extension-hooks/global/relationships.md
206+
- name: Members Fieldtype
207+
href: development/extension-hooks/global/member-ft.md
206208
- name: Session Library
207209
href: development/extension-hooks/global/session.md
208210
- name: Template Library

‎docs/toc_sections/_the_fundamentals_toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,8 @@
235235
href: fieldtypes/fluid.md
236236
- name: Grid
237237
href: fieldtypes/grid.md
238+
- name: Members
239+
href: fieldtypes/member.md
238240
- name: Notes
239241
href: fieldtypes/notes.md
240242
- name: Number Input

0 commit comments

Comments
 (0)