phpRecEvent Manual

Table of Contents

• 1 Introduction
  • 1.1 What is it?
  • 1.2 Features
  • 1.3 Requirements
  • 1.4 Installation
• 2 Setting up an event
  • 2.1 Accessing the setup page
  • 2.2 Naming the event
  • 2.3 Setting the maximum and minimum number of participants
  • 2.4 Setting the event passwords
  • 2.5 Choosing the event language
  • 2.6 Setting up when the event will take place
  • 2.7 Adding user data to the event
  • 2.8 Creating the event data
• 3 Using phpRecEvent
  • 3.1 Logging in to an event
  • 3.2 The main page
    • 3.2.1 The participants list
    • 3.2.2 The mail messenger
    • 3.2.3 The account management
    • 3.2.4 The event management
    • 3.2.5 The exit
• 4 Technical details
  • 4.1 Files
    • 4.1.1 Program files
      • 4.1.1.1 The defaults/ directory
      • 4.1.1.2 The defaults.inc file
      • 4.1.1.3 The events directory
      • 4.1.1.4 The images/ directory
      • 4.1.1.5 The include/ directory
      • 4.1.1.6 The *.php files
    • 4.1.2 Event files
      • 4.1.2.1 The data/ directory
      • 4.1.2.2 The event.css file
      • 4.1.2.3 The event.inc file
      • 4.1.2.4 The templates/ directory
  • 4.2 Placeholders
    • 4.2.1 main.html and main.admin.html
    • 4.2.2 confirm.html
    • 4.2.3 login.html (generic)
    • 4.2.4 login.html (event)
    • 4.2.5 logout.html

1 Introduction

1.1 What is it?

phpRecEvent is a web-based application to help you schedule and execute weekly recurring events. It consists of some php-scripts to create the user interface to set up and manage events plus an cron-script written in perl to mail users the new event informations once a week.

1.2 Features

• multi-user application (incl. grouping of users and administrator accounts)

• priority-based access to the events

• per-event templates for the web pages and email texts, editable via browser

• mail-messenger on the web pages to communicate with fellow event participants

1.3 Requirements

• Apache 1.3.x or better, although any HTTP-daemon that can serve php-scripts should work

• PHP 4.0 or better

• Perl 5.xxx or better, plus a couple of Perl modules

1.4 Installation

See the README file for details on how to install the software.

2 Setting up an event

2.1 Accessing the setup page

After the installation, point your favorite browser to the setup page, eg. http://www.yourdomain.tld/events/setup.php. You will be prompted to enter the setup password which you set during installation.

Once you've been successfully authenticated, you will get to the setup page.

2.2 Naming the event

An event in phpRecEvent has two names, a long one called title which is used on the web pages and in the body of the email, and a short one which is used in the email subjects, ie. the subject per default looks like

[shortname] Here's the subject

and for identifying the event in the URL. Important: No two events can have the same short name. The setup page will return an error if you try to create an event with the same short name as an already existing event.

Example:

Possible values:

2.3 Setting the maximum and minimum number of participants

For every event you have to set up both a minimum and maximum of participants.

The minimum number of participants is important in deciding whether the event takes place or not. If at the deadline the number of enrolled participants is less than this value then an email stating that the event will not take place will be sent to all the participants, otherwise the email will tell the participants that the event will take place.

The maximum number of participants is the maximum number of people which can be enrolled at the same time for this event. If someone tries to enroll for an event where this limit was reached already, they will receive an error message.

Example:

Possible values:

2.4 Setting the event passwords

Every event has two passwords, one for normal user access and one to access the event with administrator permissions. These passwords must not be the same.

Enter both passwords twice to ensure that you didn't misspell either of them. The entered text will be masked with * characters.

Example:

Possible values:

2.5 Choosing the event language

You can choose the language in which the event pages and emails will be written. At the moment, phpRecEvent is available in English, Finnish and German.

Note: You can not change the language of the event later on without manually editing the template files.

Example:

2.6 Setting up when the event will take place

Every event has two important times that you need to supply.

First, the time when the event actually takes place, ie. the day of the week and time when the event starts.

Second, the time of the deadline. Until then participants can enroll to the event, after that the event is closed and no more changes can be made to the enrollment data. It is also the time at which the emails will be sent out stating whether the event will take place or not.

Example:

Possible values for both the event time and the deadline:

Also of importance is the calendar field. Here you can enter time ranges, one per line, during which the event will take place. By using multiple lines you can also set up the event for 'gaps' like holidays etc.

The format for the calendar lines is briefly described below the text box. You need to enter at least one time period.

Example:

Possible values for the dates:

The date supplied must be valid, eg. the 31st of February will not work.

2.7 Adding user data to the event

Last but not least you also have to supply a list of users for the event.

Each line represents one participant, the format of the lines is briefly described below the text box.

The fields username, fullname and email should be obvious, but it is important to know that these have to be unique, no doubles are allowed.

The other fields need some explanation:

• Priority: this field is an integer value which decides a) whether a user is an administrator (priority = 0) and b) when people will have access to the event. Higher priority value means that the user will be allowed to access the event later, eg. a user with priority 20 will be allowed access 10 hours later than a user with priority 10. Note: at least one administrator account is needed for an event.

• Group: this field is for arranging users in groups. To do this, put the same string identifying the group into this field for all group members. Members of a group can enroll all group members.

  If you don't want to put the users into groups but want them to be able to enroll themselves and no one else, put every user in their own group, eg. by assigning a group name which equals the user name.

• Automatically enrolled: this field decides whether a user will be automatically enrolled for the event every week or not, using the values 1 or 0 respectively.

Example:

Possible values:

2.8 Creating the event data

Once your happy with the data, press the button on the bottom of the page. This will create all needed files for the event and return a link to the login page of the event.

3 Using phpRecEvent

3.1 Logging in to an event

The easiest way to log in is to go directly to the login page for an event which URL should look similar to http://www.yourdomain.tld/events/login.php?event=shortname. There you have to supply user name and password to log in.

Another way is to go to the generic login page (http://www.yourdomain.tld/events/login.php) and there select the event that you'd like to log in for from the drop-down list which will take you to the login page of the event shown above.

3.2 The main page

After you have authenticated yourself successfully you'll be seeing the main page of phpRecEvent.

At the top you can see some information about the event plus a status line which will show any messages from phpRecEvent.

The following sections describe the different parts of the main page.

3.2.1 The participants list

This list is the main tool of phpRecEvent. By using it you can enroll or sign off yourself and your group members from the event, as administrator you can even change the enrollment data for everyone on the list as shown below.

To change whether a participant is enrolled or not, just click the button.

At the bottom of the list there are printed the minimum and maximum participants that are needed for the event to happen. If someone tries to enroll when the maximum is reached already they will receive an error message in the status line.

If you're logged in as administrator you'll see another column in which you can see the time for every participant at which that person gets the invitation email and can log in to the event.

3.2.2 The mail messenger

This part is pretty much straight forward. To send an email to all event participants, just enter a subject and your message and click the button to send it on its way.

3.2.3 The account management

Note: This is only available for normal users.

In the account management you can delete your user data, ie. sign off from the event for good. Since only an administrator can put you back into the participants list, you have to answer the question following the click on the button with yes. This should avoid accidental deleting.

3.2.4 The event management

Note: This is only available for administrators.

In the event management you can do either of the following:

• Edit event: By clicking on this button you'll be send to the setup page for the event. There you can change all the things you like, including passwords, event times, calendar entries or the participants list. See the chapter about setting up an event for details.

• Edit template file: By selecting one of the template files in the drop-down section and clicking the button below it you'll be send to a page where you can edit that template inside your browser. Once you're done with the editing, be sure to say yes to the 'Save file?' question before clicking on OK, otherwise your changes will be discarded.

  

• Delete event: This, surprisingly, will delete the whole event including all the files belonging to it. To avoid accidental deletion of the event you'll have to answer the answer following the click on the button with yes to really delete the event.

3.2.5 The exit

Basically there are two different ways of exiting from an event:

• Logout: In this case the cookie that associates you with this event will be deleted and you'll have to authenticate yourself again the next time you want to log in. This is preferable in situations where another person might gain access to your cookies, eg. if your using a computer in an internet cafe.

• Exit: When choosing this way of leaving you'll be sent to the phpRecEvent login page with your cookie intact. For the same effect you can also just exit by going to some other website or closing the browser window.

4 Technical details

4.1 Files

An installation of phpRecEvent which is being used consists of two different kinds of files.

• Program files: these are the files that come with the distribution of phpRecEvent, eg. all the template files, the program scripts, etc.

• Event files: these are files that are created while using phpRecEvent. All of them are found in subdirectories of the events/ directory, each subdirectory's name being the event's short name.

Following is a description of both types of files.

4.1.1 Program files

The directory to which you installed phpRecEvent has the following entries.

events/
|-- defaults/
|-- defaults.inc
|-- events/
|-- images/
|-- include/
|-- login.php
|-- logout.php
|-- main.php
`-- setup.php

4.1.1.1 The defaults/ directory

This directory holds the following files:

Also, this directory has one subdirectory per language which holds all the template files for this language. These files will be copied to newly created events as well.

4.1.1.2 The defaults.inc file

This is the main configuration file. In here you can tune phpRecEvent to a very high degree using configuration variables.

4.1.1.3 The events/ directory

This directory holds all the files and directories for all the events that had been created, one subdirectory per event.

4.1.1.4 The images/ directory

The few needed image files can be found in this directory.

4.1.1.5 The include/ directory

This directory holds a couple of php scripts which are included at run time by phpRecEvent and are needed for phpRecEvent to work correctly but which can not be used all by themselves.

4.1.1.6 The *.php files

These are the actual script files which can be called up with the browser.

4.1.2 Event files

For each event there exists a directory which is holds all the data of that event.

events/beach/
|-- data/
|-- event.css
|-- event.inc
`-- templates/

All files apart from the ones in the data/ directory can be edited as administrator via the main page of phpRecEvent.

4.1.2.1 The data/ directory

In this directory there are two XML files that hold all the data associated with the event, event.xml holds all the general information about the event while participants.xml consists of all the information about the participants.

Note: Do not edit those files by hand unless you know what you're doing.

4.1.2.2 The event.css file

This file is the cascading style sheets file for the event, you can use it to customize the looks of the pages on a per-event basis.

4.1.2.3 The event.inc file

This file is the configuration file for the event. In here you can change things like date formats, status messages etc. on a per-event basis.

Note: this file has to be a properly formatted php script which consists mainly of lines looking like the following:

define("VARIABLE", "value");

Be sure only to change the value part of the line, ie. the text between the 3rd and 4th quote.

4.1.2.4 The templates/ directory

This directory holds all the templates associated with the event.

4.2 Placeholders

Placeholders are strings which will be replaced in the different templates at run time with the actual values of the event. All of the have the following syntax:

<!--KEYWORD-->

Following is a description of the different keywords for the placeholders which can be used in the different files. Note: all keywords have to be typed in uppercase letters.

4.2.1 main.html and main.admin.html

4.2.2 confirm.html

4.2.3 login.html (generic)

4.2.4 login.html (event)

4.2.5 logout.html