INTRODUCTION
------------

Using this plugin, a phpBB instance can be slaved to a CWIS instance.
This means that user creation, deletion, login, and logout are all
handled using the usernames and passwords created through CWIS. There
is also a CWIS-like theme for phpBB which will give users more
consistent navigation and smoother single-sign-on between the two
sites.

This plugin was tested with phpBB 3.0.11, and should work with any 3.x
version.

You will need enough access to the target phpBB installation to copy
a file into includes/auth and modify administrative settings.

It's recommended to use a fresh phpBB installation for this task, as
previously created phpBB users without a corresponding CWIS user of
the same name will cease to function.


PART ONE: Configuring user login/logout.
---------

To set this up:

* Install phpBB

* Create a user in phpBB with the same name and password as your CWIS
  user, and be sure that user has administrative privileges.  If you
  created this user during the phpBB installation, they will already
  have admin rights automatically.

* Copy auth_cwis.php into the includes/auth folder of your phpBB
  installation.

* Copy lib/AxisPHP/Axis--Database.php from your CWIS site into the
  includes/auth folder of your phpBB installation.

* Log in as your phpBB admin user, go to the administrative control
  panel, and click "Authentication" in the menu at left.  It's in the
  "Client Communication" section.

* Select the "CWIS" authentication method, and enter the Server, User,
  Password, and Database information for your CWIS installation.  For
  the CWIS base URL, enter the url of your cwis install up to but not
  including the 'index.php'.  If your url is
  http://mysite.com/data/cwis/index.php, then you would enter
  http://mysite.com/data/cwis/ .

* Under CWIS, enable the phpBBSync plugin.

DONE.

The login and logout buttons on phpBB will no longer work.  If you
install the CWIS phpBB theme, the default buttons will be replaced
with buttons that automatically redirect to CWIS. When you log in to
CWIS, you'll be automatically logged into phpBB.  Similarly for
logouts. phpBB tracks some additional data (user pictures, phpBB
rights, &c) for each user. This data is created when a user first
visits the phpBB site.

To make another CWIS user a phpBB admin, have them log into CWIS and
visit phpBB (to create the phpBB additional data), and then you can
promote their phpBB user using the administrative control panel.


PART TWO: Installing the CWIS phpBB theme
--------

* Copy the 'cwis' directory from the phpBBSync plugin directory into
  the 'styles' directory of your phpBB installation

* Log in to phpBB as an administrator go to the 'Administration
  control panel' by clicking the link at the bottom of the page.
  You'll need to re-authenticate and then the panel will be
  displayed.

* Across the top of the page is a horizontal navigation.  Third in
  from the right side is 'styles'.  Click that tab.

* CWIS will be listed as an unistalled style, click 'install'.

* Click the 'general' tab on the top navigation, then the 'security
  settings' entry on the left hand menu (fourth from the bottom).

* Set 'Allow PHP in templates' (third setting from the bottom) to
  'Yes', and hit 'Submit'.

DONE.


On Customization
----------------

Inside the 'cwis' directory that you copied are two subdirectories,
'template' and 'theme'.  The former of these contains phpBB template
files which affect the generation of HTML and the latter contains CSS
and image elements.

By default, phpBB will cache templates and stylesheets in its
database.  In order to edit the files and have your changes shown,
this needs to be disabled.  In the 'administration control panel',
'general' tab, the 'load settings' left-menu option (third from the
bottom), enable 'recompile stale style components' (the last element
of 'general options'), and hit 'submit'.

The HTML generated by phpBB is quite good in terms of attaching CSS
classes and identifiers to most if not all of the elements.  The
Firebug extension for firefox can be *very* helpful for determining
what CSS selectors are being applied to a given visual element.  Once
you have that, editing the css in 'theme' can modify fonts/colors and
images.

To add new page elements, you'll need to edit the template files,
which is a bit more complex.  phpBB uses their own syntax for template
files based on conditional execution of code in HTML comments. The
phpBB coding guidelines (linked below) are the best reference we've
been able to find so far for how their template language works. Jakob
Persson's template design guide (also linked below) gives a good
overview of how the phpBB2 template system worked.  Much of this is
transferable to phpBB3, but there are some differences.

For tweaking page headers/footers and fonts/colors, you're probably
going to be most interested in template/overall_header.html,
template/overall_footer.html, theme/common.css, and theme/colours.css.

Some useful links:
* http://www.phpbb.com/kb/article/how-to-create-a-style-basics/
* http://area51.phpbb.com/docs/coding-guidelines.html#templating
* http://www.jakob-persson.com/articles/tutorials/phpbb/templatedesignguide
* http://getfirebug.com/