groups / readme.txt

readme.txt in Groups – Memberships and Access Control 1.1.5, at readme.txt

328 lines 12.6 KB

Raw Download Zip

1	=== Groups ===
2	Contributors: itthinx
3	Donate link: http://www.itthinx.com/plugins/groups
4	Tags: access, access control, capability, capabilities, content, download, downloads, file, file access, files, group, groups, member, members, membership, permission, permissions
5	Requires at least: 3.0
6	Tested up to: 3.3.2
7	Stable tag: 1.1.5
8
9	Groups provides group-based user membership management, group-based capabilities and content access control.
10
11	== Description ==
12
13	Groups provides group-based user membership management, group-based capabilities and content access control.
14	It integrates standard WordPress capabilities and application-specific capabilities along with an extensive API.
15
16	### Extensions ###
17
18	- [Groups File Access](http://www.itthinx.com/plugins/groups-file-access/) Groups File Access is an extension that allows to provide file download links for authorized users. Access to files is restricted to users by their group membership.
19
20	### Features ###
21
22	#### User groups ####
23
24	- Supports an unlimited number of groups
25	- Provides a Registered group which is automatically maintained
26	- Users can be assigned to any group
27	- Users are added automatically to the Registered group
28
29	#### Groups hierarchy ####
30
31	- Supports group hierarchies with capability inheritance
32
33	#### Group capabilities ####
34
35	- Integrates standard WordPress capabilities which can be assigned to groups and users
36	- Supports custom capabilities: allows to define new capabilities for usage in plugins and web applications
37	- Users inherit capabilities of the groups they belong to
38	- Groups inherit capabilities of their parent groups
39
40	#### Access control ####
41
42	- Built-in access control that allows to restrict access to posts, pages and custom content types to specific groups and users only
43	- control access to content by groups: shortcodes allow to control who can access content on posts, show parts to members of certain groups or to those who are not members
44	Shortcodes: [groups_member], [groups_non_member]
45	- control access to content by capabilities: show (or do not show) content to users who have certain capabilities
46	Shortcodes: [groups_can], [groups_can_not]
47
48	#### Easy user interface ####
49
50	- integrates nicely with the standard WordPress Users menu
51	- provides an intuitive Groups menu
52	- conceptually clean views showing the essentials
53	- quick filters
54	- bulk-actions where needed, for example apply capabilities to groups, bulk-add users to groups, bulk-remove users from groups
55
56	#### Sensible options ####
57
58	- administrator overrides can be turned off
59	- optional tree view for groups can be shown only when needed
60	- provides its own set of permissions
61	- cleans up after testing with a "delete all plugin data" option
62
63	#### Access Control ####
64
65	Groups defines some capabilities of its own. The groups_read_post capability
66	is used to restrict access to certain posts or pages to groups (and users)
67	with that capability only.
68
69	#### Framework ####
70
71	- Solid and sound data-model with a complete API that allows developers to create group-oriented web applications and plugins
72
73	#### Multisite ####
74
75	- All features are supported independently for each blog in multisite installations
76
77	### Feedback ###
78
79	Feedback is welcome!
80
81	If you need help, have problems, want to leave feedback or want to provide constructive criticism, please do so here at the [Groups plugin page](http://www.itthinx.com/plugins/groups/).
82
83	Please try to solve problems there before you rate this plugin or say it doesn't work. There goes a _lot_ of work into providing you with free quality plugins! Please appreciate that and help with your feedback. Thanks!
84
85	#### Twitter ####
86
87	[Follow @itthinx on Twitter](http://twitter.com/itthinx) for updates on this and other plugins.
88
89	### Introduction ###
90
91	#### Content Access Control ####
92
93	##### Access restrictions on posts ####
94
95	On posts an pages (and custom content types) a new meta box titles Access restrictions appears.
96	By checking Enforce read access, you can restrict access to the post to groups and users who have the groups_read_post capability.
97	You need to assign this capability to a group and make users members of that group to allow them to see those posts.
98
99	#### Content visibility for members and non-members ####
100
101	The [groups_member] and [groups_non_member] shortcodes are used to limit visibility of content to users who are members of a group or users who are not members of a group. Multiple comma-separated groups can be specified.
102
103	Example: Limiting visibility of enclosed content to registered users.
104
105	[groups_member group="Registered"]
106
107	Only registered users can see this text.
108
109	[/groups_member]
110
111	#### Content visibility based on capabilities ####
112
113	The [groups_can] and [groups_can_not] shortcodes limit visibility of enclosed content to those users who have the capability or those who do not have it. Multiple capabilities can be given.
114
115	Example: Showing enclosed content to users who can edit_posts (standard WordPress capability).
116
117	[groups_can capability="edit_posts"]
118
119	You can see this only if you have the edit_posts capability.
120
121	[/groups_can]
122
123	### Integration in the 'Users' menu: ###
124
125	Users - group membership is managed from the standard Users admin view.
126	Users are automatically added to the _Registered_ group. You can add multiple users to other groups here and also remove them.
127
128	### Sections in the 'Groups' menu: ###
129
130	#### Groups ####
131
132	Here you can:
133
134	- add groups
135	- remove groups
136	- assign capabilities to groups
137
138	#### Capabilities ####
139
140	This is where you add, remove and manage capabilities.
141
142	Capabilities can be assigned to groups and users (1). These capabilities include
143	the standard WordPress capabilities but you can also define additional
144	capabilities for your web-application.
145
146	Groups defines some capabilities of its own. The groups_read_post capability
147	is used to restrict access to certain posts or pages to groups (and users)
148	with that capability only.
149
150	(1) Assigning capabilities to users is not integrated in the user interface yet but can be done through API calls.
151
152	#### Options ####
153
154	##### Administrator override #####
155
156	Administrator overrides can be turned off.
157
158	##### Permissions #####
159
160	For each role these permissions can be set:
161
162	* Access Groups: see information related to Groups.
163	* Administer Groups: complete control over everything related to Groups.
164	* Administer Groups plugin options: grants access to make changes on the Groups > Options admin section.
165
166	##### Testing the plugin #####
167
168	A convenient option is provided to delete all data that has been stored by the Groups plugin.
169	This option is useful if you just need to start from fresh after you have been testing the plugin.
170
171	### Shortcodes ###
172
173	#### Limit content visibility ####
174
175	These shortcodes are used to limit the visibility of the content they enclose:
176
177	- [groups_member]
178	- [groups_non_member]
179	- [groups_can]
180	- [groups_can_not]
181
182	See above for examples and descriptions.
183
184	#### Show group information ####
185
186	- [groups_group_info]
187
188	This shortcode takes the following attributes to show information about a group:
189
190	- _group_ : (required) the group ID or name
191	- _show_ : (required) what to show, accepted values are: _name_, _description_, _count_
192	- _single_ : (optional) used when show="count" and there is 1 member in the group
193	- _plural_ : (optional) used when show="count" and there is more than 1 member in the group, must contain %d to show the number of members
194
195	Examples:
196
197	* [groups_group_info group="Registered" show="count"]
198
199	* There [groups_group_info group="1" show="count" single="is one member" plural="are %d members"] in the [groups_group_info group="1" show="name"] group.
200
201	#### Show user groups ####
202
203	- [groups_user_groups]
204
205	This shortcode lists the current user's or a specific user's groups.
206
207	For detailed information about this shortcode, please refer to the [Groups plugin page](http://www.itthinx.com/plugins/groups/).
208
209	#### Show site groups ####
210
211	- [groups_groups]
212
213	This shortcode lists the site's groups.
214
215	For detailed information about this shortcode, please refer to the [Groups plugin page](http://www.itthinx.com/plugins/groups/).
216
217	== Installation ==
218
219	1. Upload or extract the `groups` folder to your site's `/wp-content/plugins/` directory. You can also use the Add new option found in the Plugins menu in WordPress.
220	2. Enable the plugin from the Plugins menu in WordPress.
221
222	== Frequently Asked Questions ==
223
224	= Where is the documentation? =
225
226	The official Groups documentation root is at the [Groups Documentation](http://www.itthinx.com/documentation/groups/) page.
227	The documentation is a work in progress, if you don't find anything there yet but want to know about the API, please look at the code as it provides useful documentation on all functions.
228
229	= I have a question, where do I ask? =
230
231	You can leave a comment at the [Groups plugin page](http://www.itthinx.com/plugins/groups/).
232
233	== Screenshots ==
234
235	See also [Groups](http://www.itthinx.com/plugins/groups/)
236
237	1. Groups - this is where you add and remove groups and assign capabilities to groups.
238	2. Capabilities - here you get an overview of the capabilities that are defined and you can add and remove capabilities as well.
239	3. Users - group membership is managed from the standard Users admin view.
240	4. Access restrictions meta box - on pages and posts (or custom content types) you can restrict access to users who are part of a group with the groups_read_post capability.
241	5. Usage of the [groups_member] and [groups_non_member] shortcodes to limit visibility of content to users who are members of a group or users who are not members of a group. Multiple comma-separated groups can be specified.
242	6. Usage of the [groups_can] and [groups_can_not] shortcodes. Limits visibility of enclosed content to those users who have the capability or those who do not. Multiple capabilities can be given.
243	7. Options - you can adjust the plugin's settings here.
244
245	== Changelog ==
246
247	= 1.1.5 =
248	* Added shortcode & API functions [groups_user_group] / [groups_user_groups] that allows to show the list of groups the current user or a specific user belongs to
249	* Added shortcode & API functions [groups_groups]to show the site's list of groups
250	* Class comments.
251
252	= 1.1.4 =
253	* Reduced plugin admin footer.
254
255	= 1.1.3 =
256	* Added safety & warning to test page.
257
258	= 1.1.2 =
259	* Tested on WP 3.3.2
260
261	= 1.1.1 =
262	* Multisite: Fixed (removed) conditions that would only make Groups act on public and non-mature sites
263	* Multisite: Adding add/remove to group only on sites', not network users admin screen
264	* Multisite: Added constraint in user_register hook checking if the user is a member of the blog
265
266	= 1.1.0 =
267	* Added Groups menu to network admin
268	* Added option to delete plugin data for all sites on multisite installations; removed option for individual sites
269	* Improved activation and deactivation for network installs
270	* Increases column sizes on capabilities table and fixes cut-off capabilities delete_published_pages and delete_published_posts
271
272	= 1.0.0-beta-3d =
273	* Fixed issues caused by an excessively long index for the capability DB table.
274	Some installations wouldn't work correctly, showing no capabilities and making it impossible to add new ones.
275	* Taking into account blog charset/collation on newly created tables.
276
277	= 1.0.0-beta-3c =
278	* Groups shortcodes now allow nesting.
279
280	= 1.0.0-beta-3b =
281	* Fixed admin override option not being updated
282	* DB tables checked individually to create (motivated by case of all but capability table not being created)
283
284	= 1.0.0-beta-3 =
285	* Groups wouldn't activate due to a fatal error on WP <= 3.2.1 : is_user_member_of_blog() is defined in ms-functions.php
286	* Added [groups_group_info] shortcode
287
288	= 1.0.0-beta-2 =
289	* Increased length of capability.capability, capability.class, capability.object columns to support long capabilities.
290	* Improved admin CSS.
291
292	= 1.0.0-beta-1 =
293	* This is the first public beta release.
294
295	== Upgrade Notice ==
296
297	= 1.1.5 =
298	...
299
300	= 1.1.4 =
301	* Several bug fixes and improvements.
302
303	= 1.0.0-beta-3d =
304	* The capability DB table had a ridiculously long index, this update fixes it.
305
306	= 1.0.0-beta-3c =
307	* Groups shortcodes now allow nesting: [groups_member], [groups_non_member], [groups_can], [groups_can_not]
308
309	= 1.0.0-beta-3b =
310	* Admin override fix and DB tables checked individually to create them.
311
312	= 1.0.0-beta-3 =
313	* New shortcode to show group info & WP <= 3.2.1 compatibility fix.
314
315	= 1.0.0-beta-2 =
316	* Increased length of capability.capability, capability.class and capability.object columns from to 255 => you need to update your DB manually if you want that updated.
317	* Improved some admin CSS.
318
319	= 1.0.0-beta-1 =
320	* This is the first public beta release.
321
322	== API ==
323
324	The Groups plugin provides an extensive framework to handle memberships, group-based capabilities and access control.
325	Read more on the official [Groups](http://www.itthinx.com/plugins/groups/) page and the [Groups documentation](http://www.itthinx.com/documentation/groups/) page.
326
327
328