modules/userlist/README.txt

$Id$ 


Description
-------------
User List provides an API to extend the User Administration user list 
(admin/user/user) by adding filters and data columns. The module adds one 
filter and data column through its own API that may help account 
administration: last access time. Options are provided to hide or reformat 
several of the default data columns so that the display does not become overly 
crowded.

User List displays badge icons to visually indicate commonly needed information 
for administration: Account blocked, New account, and Account online. These 
badges may optionally be displayed on user profile pages to user's with 
"administer users" or "view badge icons" access permission.

User List is packaged with three optional modules to extend its functionality. 
  User List Flag Account: accounts can be flagged and filtered with badge icons
  User List Node Count: number of nodes created by users displayed and filtered
  User List TAC Lite: Taxonomy Access Control Lite terms displayed and filtered


Prerequisites
-------------
None


Installation
-------------
1. copy the userlist directory and all its contents to your 
   modules directory.
2. enable the module: admin/build/modules.
3. configure the module: admin/user/settings/userlist
4. (optional) grant roles "view badge icons" access: admin/user/user/access


API
-------------
Module developers can extend the User Administration user list by including a
userlist callback handler in their module.

function MODULE_userlist() {
  return array(
    'KEY' => array(                  //required: key must be unique

      'table' => "TABLENAME",        //required

      'field' => "FIELDNAME",        //required

      'join' => "FIELD2NAME = 1",    //optional: userlist joins tables on uid
                                     //additional criteria for the join such
                                     //as fid if joining profile_values

      'aggregate' => "COUNT",        //optional: aggregate function COUNT, 
                                     //AVG, SUM, MAX, or MIN for field
                                     //userlist will group by u.uid and
                                     //convert any filter WHERE to HAVING

      'filter' => array(             //optional: filter is not required, for
                                     //example if only adding data column

        'title' => 'FILTER_TITLE',   //required

        'operator' => ">",           //optional: comparison operator
                                     //default is greater than ">"

        'arg' => '%d',               //required: typically %d or %s

        'options' => array(),        //required: key=>value for select

        'callback' => 'FUNC_FILTER', //optional: userlist will callback this
                                     //function with selected key, return
                                     //array of new key value and operator
      ),

      'data' => array(               //optional: data is not required, for
                                     //example if only adding new filter

        'title' => 'COL_TITLE',      //required: name of column

        'callback' => 'FUNC_DATA'    //optional: userlist will callback this
                                     //function with $row object which includes
                                     //u.uid, u.name, u.status, u.created, 
                                     //u.access, and any other fields from 
                                     //query, return new value for column
                                     //Note that providing a callback will 
                                     //make data column non-sortable
      )
    )
  );
}


Known Issues
-------------
User List includes a query builder that helps extend the User Administration 
user list in most circumstances, but will never be as robust or optimized as a
query crafted by hand. For more complex user reporting requirements, another 
recommended solution would be using Usernode in combination with Views.


Bugs/Features/Patches
---------------------
If you want to report bugs, feature requests, or submit a patch, please do so 
at the project page on the Drupal web site.
http://drupal.org/project/userlist


Todo List
-------------
+ add support for field aliases
+ add support for multiple joins to the same table
+ extend API to badge icons


Credits
-------------
Module development sponsored by LifeWire, a subsidiary of The New York Times 
Company.
http://www.lifewire.com

Icons were created by Mark James and licensed under a Creative Commons 
Attribution 2.5 License. 
http://famfamfam.com


Author
-------------
John Money
ossemble LLC.
http://ossemble.com
1	$Id$
2
3
4	Description
5	-------------
6	User List provides an API to extend the User Administration user list
7	(admin/user/user) by adding filters and data columns. The module adds one
8	filter and data column through its own API that may help account
9	administration: last access time. Options are provided to hide or reformat
10	several of the default data columns so that the display does not become overly
11	crowded.
12
13	User List displays badge icons to visually indicate commonly needed information
14	for administration: Account blocked, New account, and Account online. These
15	badges may optionally be displayed on user profile pages to user's with
16	"administer users" or "view badge icons" access permission.
17
18	User List is packaged with three optional modules to extend its functionality.
19	User List Flag Account: accounts can be flagged and filtered with badge icons
20	User List Node Count: number of nodes created by users displayed and filtered
21	User List TAC Lite: Taxonomy Access Control Lite terms displayed and filtered
22
23
24	Prerequisites
25	-------------
26	None
27
28
29	Installation
30	-------------
31	1. copy the userlist directory and all its contents to your
32	modules directory.
33	2. enable the module: admin/build/modules.
34	3. configure the module: admin/user/settings/userlist
35	4. (optional) grant roles "view badge icons" access: admin/user/user/access
36
37
38	API
39	-------------
40	Module developers can extend the User Administration user list by including a
41	userlist callback handler in their module.
42
43	function MODULE_userlist() {
44	return array(
45	'KEY' => array( //required: key must be unique
46
47	'table' => "TABLENAME", //required
48
49	'field' => "FIELDNAME", //required
50
51	'join' => "FIELD2NAME = 1", //optional: userlist joins tables on uid
52	//additional criteria for the join such
53	//as fid if joining profile_values
54
55	'aggregate' => "COUNT", //optional: aggregate function COUNT,
56	//AVG, SUM, MAX, or MIN for field
57	//userlist will group by u.uid and
58	//convert any filter WHERE to HAVING
59
60	'filter' => array( //optional: filter is not required, for
61	//example if only adding data column
62
63	'title' => 'FILTER_TITLE', //required
64
65	'operator' => ">", //optional: comparison operator
66	//default is greater than ">"
67
68	'arg' => '%d', //required: typically %d or %s
69
70	'options' => array(), //required: key=>value for select
71
72	'callback' => 'FUNC_FILTER', //optional: userlist will callback this
73	//function with selected key, return
74	//array of new key value and operator
75	),
76
77	'data' => array( //optional: data is not required, for
78	//example if only adding new filter
79
80	'title' => 'COL_TITLE', //required: name of column
81
82	'callback' => 'FUNC_DATA' //optional: userlist will callback this
83	//function with $row object which includes
84	//u.uid, u.name, u.status, u.created,
85	//u.access, and any other fields from
86	//query, return new value for column
87	//Note that providing a callback will
88	//make data column non-sortable
89	)
90	)
91	);
92	}
93
94
95
96	Known Issues
97	-------------
98	User List includes a query builder that helps extend the User Administration
99	user list in most circumstances, but will never be as robust or optimized as a
100	query crafted by hand. For more complex user reporting requirements, another
101	recommended solution would be using Usernode in combination with Views.
102
103
104	Bugs/Features/Patches
105	---------------------
106	If you want to report bugs, feature requests, or submit a patch, please do so
107	at the project page on the Drupal web site.
108	http://drupal.org/project/userlist
109
110
111	Todo List
112	-------------
113	+ add support for field aliases
114	+ add support for multiple joins to the same table
115	+ extend API to badge icons
116
117
118	Credits
119	-------------
120	Module development sponsored by LifeWire, a subsidiary of The New York Times
121	Company.
122	http://www.lifewire.com
123
124	Icons were created by Mark James and licensed under a Creative Commons
125	Attribution 2.5 License.
126	http://famfamfam.com
127
128
129	Author
130	-------------
131	John Money
132	ossemble LLC.
133	http://ossemble.com