zForum in Plone
===============

zForum in plone is a unique combination in a sense that zForum does not require its own "content types" since
all of them are provided by the SQL/Python back-end and API, this allows zForum to be somewhat "autonomous" and
in some ways not too "plone-aware". On the other hand, with just a few hooks (emulating zForum's "right nav"
as one portlet or slot, or whatever name the plone devs give to the navigational regions in the UI), zForum can be
talking to Plone seamlessly.

This Document has been revised to support version 2.5 of Plone

Here are the steps to allow a Plone site to contain a zForum instance and play nicely and adapt accordingly:

zForum Set-Up;

- Add the zForum instance (Must select Plone option when adding zForum in plone)

Plone Set-Up:

- Creating zForum's roles in plone context:
  + NOTE: The roles below may already exist in your plone context, if this is the case, you can safely skip this step.
  + From the ZMI, click on your Plone instance (Not zForum's)
  + Click on the "Security" tab
  + At the bottom of the page, you'll see a section called "User Defined Roles" along with an "Add Role" button:
    - Add the role zAdministrator
    - Add the role zAdministratorStaff
    - Add the role zMember
    - Add the role zMemberPremiere
- "Enable" Plone assigning of zForum-specific roles to users (plain-vanilla plone installation)
  + From the Zope Management interface (ZMI) Click on the "acl_users" object
  + Click on the "portal_role_manager" object (Group Aware Role Manager)
  + Click "Add a role" link, and create the following roles: (You may leave the title and description empty)
    - zAdministrator
    - zAdministratorStaff
    - zMember
    - zMemberPremiere
  + The above will allow any Plone administrator to assign these roles to any user in the system.
- Adding a test user (Optional)
  + Add a regular user as you would normally do, give the user zMember or zAdministrator additional role(s)
- Edit (Customize) ploneCustom.css and add <dtml-var "zforum.zUI['zforum_plone_stylesheet.css'](_.None, _)"> in its appropriate place:
  + Click portal_skins|plone_styles|ploneCustom.css
  + From the (read-only) ploneCustom, click the button: Customize
  + Locate the message "/* DELETE THIS LINE AND PUT YOUR CUSTOM STUFF HERE */"
  + Right After the message add the following line (Only what is between the square brackets:
    - [<dtml-var "zforum.zUI['zforum_plone_stylesheet.css'](_.None, _)">]
    - NOTE: if your zforum instance is named differently, you need to change
      the above name accordingly, e.g. if your zforum instance in plone is
      called "forum",you'll add <dtml-var "forum.zUI['zforum_plone_stylesheet.css'](_.None, _)">] 
- Enabling zForum in the tab section:
  + Click on portal_actions
  + Add new action, Give it a title (Forums), id (zforum), the URL will be something like "string:${portal_url}/zforum",
    permission: View and Category: "portal_tabs"
- Add "here/zforum/zf_macros/macros/rightnav" to Plone's right_slots property
  (Again, if your zForum instance is named differently, you'll need to change
  its ID accordingly, e.g. "here/myforuminstance/zf_macros/macros/rightnav" if
  yout forum instance's ID is "myforuminstance"


----------------------------------------------------------------------------
Hide/Dispay zForum right nav locally (when in the forums only) or globally
(anywhere in the site (depends on Plone's policies in some cases)):
----------------------------------------------------------------------------
By Default, zForum's right navigation macro (portlet-ized) will show anywhere
in the site, if you want to modify this behavior, and display the zForum's
right navigation portlet *only* when inside the forum system, you need to make
a small change to zforum's zf_macros page template page:

- Open [zforum]/zf_macros document (page template)
- Locate the line of code that reads: <div metal:define-macro="rightnav"
- insert the following AT THE END OF THAT LINE: tal:condition="python:hasattr(here, 'zf_macros')"
  + The whole line of code will then become (without the BRACKETS):
    - [<div metal:define-macro="rightnav" tal:condition="python:hasattr(here, 'zf_macros')"]
- Voila, your zForum's right nav portlet will only appear when the user is
  inside the forum system.


External Product Dependencies:
- Either ZMySQLDA (MySQL DA) or ZPsycopgDA (Postgres DA)
- CookieCrumbler (Although zForum will not add it since Plone already provides it)

NOTES:
- zForum's plone-enabled stylesheet grabs the color and UI properties from Plone's "base_properties".