/* 
 * Installation Instructions
 * Author: Michael Haggerty, mhaggerty@trellon.com
 *
 * TABLE OF CONTENTS
 * -----------------
 * I. Overview
 * II. Installation
 * III. Permissions
 * IV. Settings
 *   1) Search Settings
 *   2) Display Settings
 *   3) Registration Settings
 *   4) Mailer Options
 *   5) Saved Search Options
 * V. EventFinder Controls
 * VI. Configuration Issues
 * 
 */

I. Overview
--------------------------------------------------
EventFinder has the same basic technical requirements as drupal and 
requires a number of additional modules in order to operate. At a 
minimum, eventfinder requires event.module and location.module 
for drupal 4.6. These modules should be installed prior to installing 
eventfinder. Additionally, several optional features depend upon the 
contact_manager module, built by CivicSpace Labs. At the time of this 
writing, contact_manager can be downloaded from the following address:

http://drumm.drupaldevs.org/contact_manager.tgz

EventFinder also has a number of settings which must be configured 
prior to use on a drupal site. These will be covered in detail below.

This document assumes a basic familiarity with the event module and the 
location module.

Installation issues should be sent to mhaggerty@trellon.com.

II. Installation
---------------------------------------------------
1) Install event.module and location.module on your drupal site.
   OPTIONAL: Install contact_manager module.

2) Download the EventFinder module and copy the files 
   under your drupal modules/ directory.

3) Navigate to the EventFinder installation directory and
   install the database defintions for EventFinder. The syntax
   for the mysql command is as follows:
 
   mysql -u [username] -p [drupal db name] < eventfinder.mysql

   Where 'username' is the name of a user on your installation of 
   mysql who has CREATE access on your drupal database, and 'drupal 
   db name] is the name of your drupal database.

4) Login to your drupal site using an administrative account. Navigate 
   to admin/modules and enable EventFinder.

5) Navigate to admin/settings/eventfinder and enable / disable options
   to your liking. EventFinder settings are covered in detail below.
   OPTIONAL: Within contact_manager, define a source for contacts
   generated as a result of EventFinder registrations.

6) Navigate to admin/access control and enable / disable EventFinder 
   permissions to your liking. Permissions are covered in detail below.

7) OPTIONAL: Enable cron on your drupal site to support sending saved
   searches via email. 

III. Permissions
-----------------------------------------------------
There are 4 permissions in EventFinder

1) Search Events - User has the ability to search for events within eventfinder. 
   Without this permission, EventFinder is effectively useless to a given 
   user group. 

2) Saved Searches - User has the ability to create saved searches and 
   receive saved search emails.

3) Host Event - User has the ability to view the bost event page. Permissions 
   at this point are a little complicated - essentially, the host event page 
   will display all node types which the user has permission to create. User 
   groups without permission to create event-enabled node types will find this
   permission to be useless.

   EventFinder has no native node type, nor does it grant users permissions to 
   other node types.

4) admin eventfinder - User has the ability to administer EventFinder. This 
   permission currently does nothing but will be useful when other modules 
   are integrated into EventFinder.

IV. Settings
-----------------------------------------------------
EventFinder has a number of settings which must be enabled in order
for the module to work. Additonally, these settings affect the functionality
of the module itself. Administrators are urged to take care to understand 
these settings prior to implementing the module.

1) Search Settings
------------------
There are 5 basic types of searches that EventFinder supports. Each seach type 
can be turned on and off using these features. Checking off the checkbox next to 
a search type will remove that search criteria from both the main search form and 
the saved search form.

a) Enable Event Taxonomy Searches - Displays event taxonomy search controls on the 
   search interface.

b) Enable Event Type Searches - Displays event type search controls on the search 
   screen.

c) Enable Location Proximity Searches - Displays search controls for searching by 
   zip code radius.

d) Enable State Searches - Displays search controls for searching by state.

e) Enable Major Metropolitan Area Searches - Displays search controls for searching 
   by Major Metropolitan Area.

2) Display Settings
-------------------
These settings control several elements of the search interface including placement 
of controls and instructions to users.

a) Display EventFinder Options: Controls whether the event subscription controls 
   appear above or beneath the main body of event-enabled nodes within the system.

b) Search Description: Descriptive text to display to users doing a search. Leaving 
   this field blank supresses the description.

c) MyEvents Description: Descriptive text to display to users visiting their MyEvents 
   page. Leaving this field blank supresses the description.

d) Host an Event Description: Descriptive text to display to users on the Host an Event 
   page. Leaving this field blank supresses the description.

e) Send Message to Registered Users Description: Descriptive text to display to users 
   on the Send Message to Registered Users page.

3) Registration Settings
------------------------
These settings control how and when users can register for events in the system. 

a) Registration List Description: A description to appear at the top of the event
   registration screen.

b) Registration Workflow: Controls how users are able to register for events. Changing
   this setting once EventFinder is installed and users have begun registering for 
   events is NOT suggested.

   One Click: Users with an account on your drupal site can register for an event 
   simply by clicking on a link. Users must have an account on your site in order 
   to register for an event.

   Registration Page: Users are taken to a registration page in order to register 
   for an event. In this way, anonymous users can register for an event.

c) Storage Options: Controls where user contact information is kept under 'Registration
   Page' style registration. Currently, the only repository supported is the 
   contact_manager module.

d) Contact Source Group: The source group within the contact_manager module to use
   for EventFinder registrations.

4) Mailer Options
-----------------
These settings control the behavior of the EventFinder mailer sub-system.

a) Enable EventFinder to send a confirmation mail to people who enter events - Basically, 
   since EventFinder works on top of the event system, it may or may not be a good idea to 
   have emails going out every time someone enters an event-enabled node type within the 
   system. Unchecking this box turns entry emails off.

b) Enable registration confirmation email - Similar to the previous item, EventFinder sends 
   an email when someone registers to attend an event. Unchecking this box stops this behavior.

c) Email Name: The name you want to appear in email clients for emails from EventFinder. Applies
   to all emails sent from the system.

d) Email Address: The email address you want to appear in email clients for emails from 
   EventFinder. This setting applies to all emails generated by the system.

e) Host Email Subject Line - The subject line for the host email. When a user enters an 
   event-enabled node type into the system, EventFinder checks to see whether host emails are 
   enabled and sends out a thank you message. Wildcards can be included here corresponding to 
   the event type in the system.

f) Host Email Body - The body of the email to be sent to users once they have entered an 
   event-enabled node type. Wildcards here include any field that is part of the event-enabled 
   node type, prefixed by a percentage (%) sign. For example, %title. While it would be nice to 
   offer a standard set of fields that covers all node types, this is not possible given the 
   fact there can be any number of fields associated with a node.

g) Register Email Subject Line - The subject line for the register email. When a user registers 
   for an event through EventFinder, the system checks to see whether register emails are enabled 
   then sends out a thank you message. Wildcards can be included here corresponding to the 
   event type in the system.

h) Register Email Body - The body of the email to be sent to users once they have registered for 
   an event through EventFinder. Wildcards here include any field that is part of the event-enabled 
   node type, prefixed by a percentage (%) sign. For example, %title. While it would be nice to 
   offer a standard set of fields that covers all node types, this is not possible given the fact 
   there can be any number of fields associated with a node.

5) Saved Search Options
-----------------------
These settings affect saved searches throughout the system. Saved searches are a way of 'pushing' 
events into people's mailboxes using an opt-in subscription system. While they are cool, there could 
be a performance hit on a high-volume site. Controls are presented for turning saved searches on and 
off in the system.

a) Enable Saved Searches - Enable / disable saved searches. Overrides all other options.

b) Maximum Saved Searches per User - The maximum number of saved searches a single user can create. 
Not implmemented at the time of this writing.

c) Saved Search Description - Descriptive text to present to users at the main saved search page.

d) Create Saved Search Instructions - Descriptive text presented to users at the create saved search 
page.

e) Saved Search Email Subject Line - The subject line of messages to be sent through the saved search. 

f) Saved Search Email Body - The body of the messages to be sent through the saved search system. 
Because the number of search results will vary for each user, this is really just a container for 
descriptions of specific nodes in the email.

g) Saved Search Event Description - This field controls how a saved search result is presented within 
the email.

V. EventFinder Controls
------------------------------------------------------
When creating a node that is event-enabled (users familiar with the event module understand 
this concept), a form group will appear labelled 'EventFinder Options'. There are 2 fields 
here: 'Enable Online Registration for this Event' and 'Maximum Number of Online Registrants'.

Clicking the 'Online Registration' checkbox will allow users to register for an event.

Setting the 'Maximum Number of Online Registrants' will limit the number of people who can
register for an event.

VI. Configuration Issues
------------------------------------------------------
Out of the box, EventFinder is not extremely pretty. Part of this is a result of how the module 
was developed, relying on information from other modules (i.e. the date and time of an event
is separated on the node description from the placement of location information). The authors
of these modules have been contacted and are working on a solution at the time of this writing. 

Part of the issue of appearance is a result just of how EventFinder is, and steps have been 
taken in development to ensure easy configuration of the module for production environments. 
All of the themes within EventFinder are kept within the eventfinder_themes.inc file, which can 
(should) be edited. Also, the css controlling EventFinder themes is located in the file 
eventfinder.css. Each of these files can be located under the eventfinder installation directory.

 


