modules/menu_node_edit/README.txt

// $Id:$

Menu Node Edit
Allows node editing access based on menu relationships.

CONTENTS
--------

1. Introduction
2. Installation
3. Menu Node Edit and Node Access
4. Permissions
4.1 Security Considerations
5. Using the Module
5.1 Terminology
5.2 Menu Node Edit Settings
5.3 Creating Sections
5.4 Assigning Users as Section Editors
6. My Sections
6.1 About the My Sections Tab
6.2 Content Lists
6.3 Creating Content in a Section
7. Content Creation and Editing
8. Developer Information
8.1 Database Tables


----
1. Introduction

The Menu Node Edit module allows the site's menu system to be used as the sole
organizing principle. It does so by allowing specific menu items to be defined
as 'sections' of a Drupal web site. Individual users can then be assigned as
editors of one or more section.

This structure means that, for small web sites, the menu system can be used as
the sole ordering principle, removing the need for taxonomy or group-based
editing controls.

----
2. Installation

The Menu Node Edit module requires the Menu Node API module. After both modules
have been downloaded and inflated, place them in your modules directory.

Then proceed to the Modules admin page and activate both modules.

After you install the module, you will want to configure its permissions after
reading this document.

----
3. Menu Node Edit and Node Access

The Menu Node Edit module is deliberately _not_ a Drupal node access module. It
does not provide any access controls for the viewing or deleting of content.

Instead of using the {node_access} table to assert permissions, Menu Node Edit uses
hook_menu_alter() to rewrite the access rules for a node's edit page. As a
result, Menu Node Edit can provide flexible controls regarding who can and cannot
edit content within a given site section.

Menu Node Edit should work in harmony with standard Drupal permissions and node
access modules. Please read section 4 for additional details.

----
4. Permissions

The Menu Node Edit module generates four default permissions, plus a special
editing permission for each node type used on your site. The default permissions
are as follows:

  -- 'administer menu node edit'
      Allows users to adjust settings for the Menu Node Edit module.
  -- 'assign menu node edit'
      Allows users to assign other users to site sections
  -- 'publish to my sections'
      Allows users to select a target section for new and edited content.
      This permission is similar to the ability to assign a node to a menu path,
      but with far greater restrictions, based on the user's assigned sections.
  -- 'view my sections'
      Allows a user to see content overview pages that list all content in her
      assigned sections. This permision only works if the 'add menu node edit tab
      to user account page' setting is active.

In addition to these settings, the module generates the following permission for
each node type on your site:

  -- 'edit any TYPE content in assigned sections'

This permission should be used with care. It allows Menu Node Edit to override any
other node access permissions for the approved content types. You should assign
this permission only if you want users to be able to edit certain types of
content if and only if they are also assigned to one of his sections.

----
4.1 Security Considerations

By design, the Menu Node Edit module gives select users permission to view and edit
content that might normally be denied to them. This may include the ability to 
see and edit content that is 'unpblished' and not visibile to normal users.

Only trusted users and roles should be given any Menu Node Edit permissions.

The module allows users with the 'administer menu node edit' permission the right
to view the 'My sections' content lists of other users. You should use this
permission to ensure that you are comfortable with the data that the module
exposes to these users.

----
5. Using the Module

The Menu Node Edit module is not designed for all use cases. Please read this
document before using the module.

----
5.1 Terminology

The following terms are used consistently in the documentation and user
interfaces.

  -- Item
  A unique menu item, defined in Drupal's menu system. Typically this is
  a single row from the {menu_links} table.
  -- Node
  A unique piece of site content.
  -- Section
  A menu item (and its children) defined as a content group for editing.
  -- Editor
  A user assigned to one or more sections, with the appropriate permissions.
  
----
5.2 Menu Node Edit Settings

There are two settings available for the module. To adjust these settings, you
must have the 'administer menu node edit' permission.

  -- Add menu node edit tab to user account page
  Enabling this setting adds a 'My Sections' tab to the user page of 
  any user who is assigned to a section and is given the 'view my sections'
  permission. Default: TRUE

  -- Allow the following content types to be assigned to a section
  These settings control how content created by editors will be handled. For
  each node type, you may allow section editors to assign new or existing
  content to one of their sections. If a node type is not selected here, Then
  the section editor will not be able to assign the content to her section.
  Default: TRUE for all content types

Normally, you will not need to adjust these settings.

----
5.3 Creating Sections

To begin using Menu Node Edit, you must first create some sections. To do so,
you must have the 'administer menus' permission. To create a section, go to
the Menu administration page, select a menu, and look at the menu overview
form.

You should see a column marked 'Sections', with a checkbox for each menu item.
You can crate sections in a batch by using this form. Simply select each menu
item that you wish to make a section.

Optionally, you can edit the menu item and select the 'Menu node edit section'
checkbox on the editing form.

Once you have created some sections, you may assign users to be editors of those
sections.

----
5.4 Assigning Users as Section Editors

Now that you have created some sections, you can assign users to be section
editors. A user may be assigned to one or more sections.

To assign section editors, you must have the 'assign menu node edit' permission.

  -- Navigate to a user's account page and click the edit tab.
  -- On the user account form, find the fieldset labelled 'Section editing'.
  -- Check the sections that you wish to allow this user to edit.
  -- Submit the form to save the changes.

This form is also available when creating new users through the Add User admin
interface.

----
6. My Sections

The My Sections tab is a simple overview of content asigned to a user's 
sections. This tab is enabled by default, but may be turned off.

If a user is assigned as a section editor and has the 'view my sections' 
permission, the My Sections tab will appear on his or her account page.

----
6.1. About the My Sections Tab

My Sections displays a paginated overview of all content assigned within each
section that a user can edit. For example, if a user is assigned to edit the 
sections Foo and Bar, this page will show two sub-tabs.

By clicking on a sub-tab, the user can see a list of all content within that 
section, according to the following rules:

  -- The user must have one of the following permissions:
    -- 'administer nodes'
    -- 'edit any TYPE content in assigned sections'
    -- 'edit any TYPE content'
  -- The content must be assigned to the menu section being displayed.
  
Note that content not assigned to the menu system will never be displayed.

----
6.2 Content Lists

Each My Section tab shows a list of content. The list shows the following 
information:

  -- Title
  -- Author name
  -- Content type
  -- Status (published / unpublished)
  -- Edit link
  
Two critical notes here, both related to site security.

  1) It is possible for users to view the information for unpublished content.
  For some sites, this may be a concern. Those sites should be very careful
  about who is given editor access to specific sections.
  
  2) It is possible that a user may not be allowed to edit some content on
  this list _if_ access control permissions are not set correctly, or if a node
  access module trumps the permission 'edit any TYPE content'. If a user has
  the 'edit any TYPE content in assigned sections' permission, all content of
  that type should be editable.

----
6.3 Creating Content in a Section

The module can also help users without the 'administer menu' permission to
post content in the appropriate section.

When viewing a My Sections tab, the user is given a list of all content types 
that he is allowed to create. Clicking on these links will automatically
populate the content creation form with the proper section information.

Note that this only applies to users with the 'publish to my sections'
permission.

----
7. Content Creation and Editing

For users with the 'publish to my sections' permission but not the 'administer
menu' permission, the 'Section' form element is available when editing
content.

The Section form element presents a select list that shows all the section that
a user can edit. This dropdown shows all child items of the assigned section,
allowing the editor to assign the node a place in the menu hierarchy.

The title for the menu item will be created automatically, using the title of
the content node.

There are a handful of circumstances under which the Sections option will
not be visible to an editor. Those are as follows:

  1) If the content type cannot be set to a section (see 5.2)
  2) If the editor is not assigned to any sections.
  3) If the node is already assigned to a menu item that is outside
  any of the editor's sections.

Note that editors are not required to assign content to a section.

When content is assigned to a section, a new menu item with weight of zero
(0) will be created at the depth indicated by the selection form.

---
8. Developer Notes

This section is for general notes.

----
8.1 Database Tables

The module creates two tables to store its data:

  {menu_node_edit}
    Stores the menu link ids (mlids) identified as sections for your site.
    This table has one column, mlid (int), and it is a foreign key to
    {menu_links}.mlid.
  
  {menu_node_edit_user}
    Stores the relationship between sections and editors. This table has
    two columns, uid (int) is a foreign key to the {users}.uid, and {mlid}
    (int), which is a foreign key to {menu_node_edit}.mlid and {menu_links}.mlid.
1	// $Id:$
2
3	Menu Node Edit
4	Allows node editing access based on menu relationships.
5
6	CONTENTS
7	--------
8
9	1. Introduction
10	2. Installation
11	3. Menu Node Edit and Node Access
12	4. Permissions
13	4.1 Security Considerations
14	5. Using the Module
15	5.1 Terminology
16	5.2 Menu Node Edit Settings
17	5.3 Creating Sections
18	5.4 Assigning Users as Section Editors
19	6. My Sections
20	6.1 About the My Sections Tab
21	6.2 Content Lists
22	6.3 Creating Content in a Section
23	7. Content Creation and Editing
24	8. Developer Information
25	8.1 Database Tables
26
27
28	----
29	1. Introduction
30
31	The Menu Node Edit module allows the site's menu system to be used as the sole
32	organizing principle. It does so by allowing specific menu items to be defined
33	as 'sections' of a Drupal web site. Individual users can then be assigned as
34	editors of one or more section.
35
36	This structure means that, for small web sites, the menu system can be used as
37	the sole ordering principle, removing the need for taxonomy or group-based
38	editing controls.
39
40	----
41	2. Installation
42
43	The Menu Node Edit module requires the Menu Node API module. After both modules
44	have been downloaded and inflated, place them in your modules directory.
45
46	Then proceed to the Modules admin page and activate both modules.
47
48	After you install the module, you will want to configure its permissions after
49	reading this document.
50
51	----
52	3. Menu Node Edit and Node Access
53
54	The Menu Node Edit module is deliberately _not_ a Drupal node access module. It
55	does not provide any access controls for the viewing or deleting of content.
56
57	Instead of using the {node_access} table to assert permissions, Menu Node Edit uses
58	hook_menu_alter() to rewrite the access rules for a node's edit page. As a
59	result, Menu Node Edit can provide flexible controls regarding who can and cannot
60	edit content within a given site section.
61
62	Menu Node Edit should work in harmony with standard Drupal permissions and node
63	access modules. Please read section 4 for additional details.
64
65	----
66	4. Permissions
67
68	The Menu Node Edit module generates four default permissions, plus a special
69	editing permission for each node type used on your site. The default permissions
70	are as follows:
71
72	-- 'administer menu node edit'
73	Allows users to adjust settings for the Menu Node Edit module.
74	-- 'assign menu node edit'
75	Allows users to assign other users to site sections
76	-- 'publish to my sections'
77	Allows users to select a target section for new and edited content.
78	This permission is similar to the ability to assign a node to a menu path,
79	but with far greater restrictions, based on the user's assigned sections.
80	-- 'view my sections'
81	Allows a user to see content overview pages that list all content in her
82	assigned sections. This permision only works if the 'add menu node edit tab
83	to user account page' setting is active.
84
85	In addition to these settings, the module generates the following permission for
86	each node type on your site:
87
88	-- 'edit any TYPE content in assigned sections'
89
90	This permission should be used with care. It allows Menu Node Edit to override any
91	other node access permissions for the approved content types. You should assign
92	this permission only if you want users to be able to edit certain types of
93	content if and only if they are also assigned to one of his sections.
94
95	----
96	4.1 Security Considerations
97
98	By design, the Menu Node Edit module gives select users permission to view and edit
99	content that might normally be denied to them. This may include the ability to
100	see and edit content that is 'unpblished' and not visibile to normal users.
101
102	Only trusted users and roles should be given any Menu Node Edit permissions.
103
104	The module allows users with the 'administer menu node edit' permission the right
105	to view the 'My sections' content lists of other users. You should use this
106	permission to ensure that you are comfortable with the data that the module
107	exposes to these users.
108
109	----
110	5. Using the Module
111
112	The Menu Node Edit module is not designed for all use cases. Please read this
113	document before using the module.
114
115	----
116	5.1 Terminology
117
118	The following terms are used consistently in the documentation and user
119	interfaces.
120
121	-- Item
122	A unique menu item, defined in Drupal's menu system. Typically this is
123	a single row from the {menu_links} table.
124	-- Node
125	A unique piece of site content.
126	-- Section
127	A menu item (and its children) defined as a content group for editing.
128	-- Editor
129	A user assigned to one or more sections, with the appropriate permissions.
130
131	----
132	5.2 Menu Node Edit Settings
133
134	There are two settings available for the module. To adjust these settings, you
135	must have the 'administer menu node edit' permission.
136
137	-- Add menu node edit tab to user account page
138	Enabling this setting adds a 'My Sections' tab to the user page of
139	any user who is assigned to a section and is given the 'view my sections'
140	permission. Default: TRUE
141
142	-- Allow the following content types to be assigned to a section
143	These settings control how content created by editors will be handled. For
144	each node type, you may allow section editors to assign new or existing
145	content to one of their sections. If a node type is not selected here, Then
146	the section editor will not be able to assign the content to her section.
147	Default: TRUE for all content types
148
149	Normally, you will not need to adjust these settings.
150
151	----
152	5.3 Creating Sections
153
154	To begin using Menu Node Edit, you must first create some sections. To do so,
155	you must have the 'administer menus' permission. To create a section, go to
156	the Menu administration page, select a menu, and look at the menu overview
157	form.
158
159	You should see a column marked 'Sections', with a checkbox for each menu item.
160	You can crate sections in a batch by using this form. Simply select each menu
161	item that you wish to make a section.
162
163	Optionally, you can edit the menu item and select the 'Menu node edit section'
164	checkbox on the editing form.
165
166	Once you have created some sections, you may assign users to be editors of those
167	sections.
168
169	----
170	5.4 Assigning Users as Section Editors
171
172	Now that you have created some sections, you can assign users to be section
173	editors. A user may be assigned to one or more sections.
174
175	To assign section editors, you must have the 'assign menu node edit' permission.
176
177	-- Navigate to a user's account page and click the edit tab.
178	-- On the user account form, find the fieldset labelled 'Section editing'.
179	-- Check the sections that you wish to allow this user to edit.
180	-- Submit the form to save the changes.
181
182	This form is also available when creating new users through the Add User admin
183	interface.
184
185	----
186	6. My Sections
187
188	The My Sections tab is a simple overview of content asigned to a user's
189	sections. This tab is enabled by default, but may be turned off.
190
191	If a user is assigned as a section editor and has the 'view my sections'
192	permission, the My Sections tab will appear on his or her account page.
193
194	----
195	6.1. About the My Sections Tab
196
197	My Sections displays a paginated overview of all content assigned within each
198	section that a user can edit. For example, if a user is assigned to edit the
199	sections Foo and Bar, this page will show two sub-tabs.
200
201	By clicking on a sub-tab, the user can see a list of all content within that
202	section, according to the following rules:
203
204	-- The user must have one of the following permissions:
205	-- 'administer nodes'
206	-- 'edit any TYPE content in assigned sections'
207	-- 'edit any TYPE content'
208	-- The content must be assigned to the menu section being displayed.
209
210	Note that content not assigned to the menu system will never be displayed.
211
212	----
213	6.2 Content Lists
214
215	Each My Section tab shows a list of content. The list shows the following
216	information:
217
218	-- Title
219	-- Author name
220	-- Content type
221	-- Status (published / unpublished)
222	-- Edit link
223
224	Two critical notes here, both related to site security.
225
226	1) It is possible for users to view the information for unpublished content.
227	For some sites, this may be a concern. Those sites should be very careful
228	about who is given editor access to specific sections.
229
230	2) It is possible that a user may not be allowed to edit some content on
231	this list _if_ access control permissions are not set correctly, or if a node
232	access module trumps the permission 'edit any TYPE content'. If a user has
233	the 'edit any TYPE content in assigned sections' permission, all content of
234	that type should be editable.
235
236	----
237	6.3 Creating Content in a Section
238
239	The module can also help users without the 'administer menu' permission to
240	post content in the appropriate section.
241
242	When viewing a My Sections tab, the user is given a list of all content types
243	that he is allowed to create. Clicking on these links will automatically
244	populate the content creation form with the proper section information.
245
246	Note that this only applies to users with the 'publish to my sections'
247	permission.
248
249	----
250	7. Content Creation and Editing
251
252	For users with the 'publish to my sections' permission but not the 'administer
253	menu' permission, the 'Section' form element is available when editing
254	content.
255
256	The Section form element presents a select list that shows all the section that
257	a user can edit. This dropdown shows all child items of the assigned section,
258	allowing the editor to assign the node a place in the menu hierarchy.
259
260	The title for the menu item will be created automatically, using the title of
261	the content node.
262
263	There are a handful of circumstances under which the Sections option will
264	not be visible to an editor. Those are as follows:
265
266	1) If the content type cannot be set to a section (see 5.2)
267	2) If the editor is not assigned to any sections.
268	3) If the node is already assigned to a menu item that is outside
269	any of the editor's sections.
270
271	Note that editors are not required to assign content to a section.
272
273	When content is assigned to a section, a new menu item with weight of zero
274	(0) will be created at the depth indicated by the selection form.
275
276	---
277	8. Developer Notes
278
279	This section is for general notes.
280
281	----
282	8.1 Database Tables
283
284	The module creates two tables to store its data:
285
286	{menu_node_edit}
287	Stores the menu link ids (mlids) identified as sections for your site.
288	This table has one column, mlid (int), and it is a foreign key to
289	{menu_links}.mlid.
290
291	{menu_node_edit_user}
292	Stores the relationship between sections and editors. This table has
293	two columns, uid (int) is a foreign key to the {users}.uid, and {mlid}
294	(int), which is a foreign key to {menu_node_edit}.mlid and {menu_links}.mlid.