Add context tests. Forgotten in last commit.
[project/og.git] / README.txt
CommitLineData
76718bc0 1DESCRIPTION
2--------------------------
cf945459 3Enable users to create and manage their own 'groups'. Each group can have members, and maintains a group home page where members can post into. Posts may be placed into multiple groups (i.e. cross-posting) and individual posts may be shared with non-members or not. Membership to groups may be open, closed, moderated, or invitation only. Add-on modules are available for group image galleries, group calendars, group vocabulary, group stores, and so on.
76718bc0 4
9f362feb 5Groups may choose their own theme and language. Groups have RSS feeds and email notifications and so on. Group admins may customize the layout and contents of their group home page and add additional custom pages (requires the included OG Panels module).
1b117cad 6
76718bc0 7INSTALLATION
8---------------
7c2b4410 9- Enable the Organic groups and Organic groups Views integration modules. If you want to protect some posts so that only certain users may view them, enable the 'Organic Groups access control' module as well. Please make sure og is working well on its own before enabling other OG related modules.
10- On the Administer > Organic groups configuration page, see the content types table at the top. Click edit beside each type to set its 'usage'. Disable comments and attachments for node types which are designated as group nodes. You usually want to create a new node type via admin/content/types page and then designate that content type as a group node. See the first item in NOTES below.
0b710630 11- Set other preferences on admin/og/og as desired. It may take some experimenting before you arrive at a configuration well suited to your needs.
7c2b4410 12- On the Administer › Site building > Blocks page, enable the 'Group details' and drag it toward the top of your list. Optionally enable the other 'Group' blocks.
cf945459 13- Grant permissions as needed on the admin/user/permission page
7594d4da 14- Begin creating groups (visit the node/add page), joining those groups, and posting into those groups. The join link appears in the Group details block, for non invite-only groups.
7c2b4410 15- Consider enabling the following modules which work well with OG: Pathauto, Locale, Notifications. After your install is working nicely, consider enabling more og add-on modules like og_mandatory_group, og_vocab, and og_panels. Those are known to work well with OG. Some of the others on drupal.org are uite poorly integrated and will cause problems. See http://drupal.org/project/Modules/category/90.
76718bc0 16
17NOTES
18----------------
7c2b4410 19- This module supports designating any contnt type to act as a group. This content type should be defined by a custom module or via the admin/content/types page. When defining your type, you usually want the title label to be 'Group name' and the body label to be 'Welcome message'. Since all nodes of this type are treated as groups, you will usually not want to designate the standard page, story, or book node types as groups. The feature where custom content types may act as groups enables you to have custom fields for your groups and even different fields for different kinds of groups (i.e. content types).
cf945459 20- There are a few handy tabs at the path 'group'. You might want to add a link in your Navigation to that url. Each tab also provides a useful RSS feed.
0b710630 21- 'Administer nodes' permission is required for changing the Manager of a group (do so by changing the posts' Author.)
22- 'Administer nodes' permission enables viewing of all nodes regardless of private/public status.
cf945459 23- All membership management happens on the 'membership list' page which is linked from the group details Block (while viewing a group page). This includes approving membership requests (for selective groups), adding/removing users and promoting users into group admins.
7c2b4410 24- If you decide to stop using Organic groups, just disable it as usual. If you ever decide to re-enable, all your prior group access control information will be restored. If you want to start fresh, uninstall og, og_views and og_access modules.
27ff8d1d 25
26DEVELOPERS & SITE BUILDERS
27------------------
feb0f520 28- You may craft your own URLs which produce useful behavior. For example, user/register?gids[]=4 will add a checked checkbox for to the user's registration page for subscribing to group nid=4. This feature overrides the usual preference for groups to always appear during registration.
7c2b4410 29- You alter the links in the group details block using hook_og_link_alter($links, $group_node). See og_block_details().
c8e984be 30- The current group context is available to javascript code at Drupal.settings.og. This is useful for enriching ad tags and analytics calls with group information.
76718bc0 31
76718bc0 32THEMES
33------------------
34You may wish to stylize nodes which have properties assigned by this module.
cf945459 35--- public vs. private posts are denoted by $node->og_public (og_access provides private posts)
7c2b4410 36--- provided in this package are two template files for the phptemplate engine. One stylizes group nodes and the other stylizes all other stylizes group posts. These can be starting points for your customization of look and feel of your group. Just copy them to your theme directory and edit as desired. Or you might use the included og_panels module to achieve custom group homepages (and other group pages) that group admins can design themselves.
76718bc0 37
779c9947 38INTEGRATION
39---------------------
7c2b4410 40- I recommend enabling the cron features of Notifications/Messaging modules. When you do, group email notifications are sent during cron runs, instead of immediately after a post is submitted. This speeds up posting a lot, for big groups. The delay also helps authors fix typos in their posts before the mail is sent.
7594d4da 41- This module exposes an API for retrieving and managing membership via direct PHP functions [og_save_subscription()] and via XMLRPC.
779c9947 42
43UNIT TESTING
44----------------------
cf945459 45This module comes with a few unit tests. Please help update and build more of them. See http://drupal.org/simpletest
779c9947 46
68b823a9 47TODO/BUGS/FEATURE REQUESTS
76718bc0 48----------------
cf945459 49- See http://drupal.org/project/issues/og. Please search before filing issues in order to prevent duplicates.
68b823a9 50
c739b1b3 51UPGRADING FROM 5.0 TO 6.x
ef6c4d6b 52-----------------
7c2b4410 53- The upgrade auto-enables the new og_views module. This is needed to get the same functionality that was present in D5.
b4df17fc 54- There is no support for migrating custom Views. Please redo those in Views2. You might need to use a Relationship.
25494e75 55- Group members block (og/2) block is now served by Views: views/og_members_block-block_1
7c2b4410 56- Group search is now in its own block which must be enabled manually. It used to be integrated into the Group details block.
ef6c4d6b 57
c739b1b3 58UPGRADING FROM 4.7 TO 5.x
9f362feb 59-----------------
c739b1b3 60- You must update to 5.x before updating to 6.
9f362feb 61
68b823a9 62CREDITS
63----------------------------
81013a75 64Authored and maintained by Moshe Weitzman <weitzman AT tejasa DOT com>
feb0f520 65Contributors: Gerhard Killesreiter, Angie Byron, Derek Wright, Thomas Ilsche, Ted Serbinski, damien_vancouver
8cbc9e66 66Sponsored by Bryght - http://www.bryght.com
68b823a9 67Sponsored by Broadband Mechanics - http://www.broadbandmechanics.com/
68Sponsored by Finnish Broadcasting Company - http://www.yle.fi/fbc/
6adfdb61 69Sponsored by Post Carbon Institute - http://www.postcarbon.org/