README.txt

Version 1.5 (checked in on 2009/10/28 at 18:33:15 by agentken)

// $Id: README.txt,v 1.5 2009/10/28 18:33:15 agentken Exp $

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 4.2 Access Check Process 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 7.1 Hiding Menu Links 8. Developer Information 8.1 Database Tables 8.2 Tokens

---- 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. -- 'set menu visibility' Allows users to set a menu item to 'hidden'. Doing so prevents the link from appearing in site navigation, but keeps the node as part of an editing section. Users with the 'administer menu' permission also have this ability. -- '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 extend 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 the content is also assigned to one of her 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.

---- 4.2 Access Check Process

When editing access to a node is requested, the following checks take place:

-- Check for active menu sections. -- Check for the user's active sections. -- If either are empty, return Node Access rules. -- If Node Access returns TRUE, return TRUE. -- Check to see if the user can edit the node's content type in her section(s). -- If not, return FALSE. -- Check the user's allowed sections against this node. -- If allowed, return TRUE. -- Otherwise, return FALSE.

---- 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 creating content. However, once content has been assigned to a section, it may only be re-assigned. Only users with the 'administer menu' permission may delete section items.

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.

---- 7.1 Hiding Menu Links

In versions 6.x.1.6 and higher, users with the 'set menu visibility' permission will also be shown a 'Hidden' checkbox when editing content.

Check this box if you wish to add the content to an editing section but do not want it displayed in site navigation. A menu item may be made visible or invisible as needed. Hidden menu items still appear in a user's 'My sections' content lists.

See http://drupal.org/node/517732 for background on this feature.

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

---- 8.2 Tokens

The module supports menu-based tokens. It provides a token for the path to the parent menu item of the node. If there is no parent item, the token defaults to use the string 'content'.

There are two tokens:

-- 'menu-parent-path-alias' Path alias of parent menu item. This is a raw path, and has not been sanitized. However, using it with pathauto will force the '/' characters to be stripped. -- 'menu-parent-path-alias-path' Path-safe alias of parent menu item. Use this token with pathauto to preserve / characters.