USING THE CALENDAR PLUG-IN for PHPWEBSITE
by Matthew McNaney
-------------------------------------------------------------------------------------------------------------------------------------

Thank you using this calendar plug-in for phpWebSite. This plug-in REPLACES the
calendar functionality in phpWebSite in versions 7.6 and lower. Most of the program
is the same but there are some changes and improvements.

-> Features
More views in the side menu. Month, week, day, and searches by section are possible.
Events can be associated with Categories, Subcategories, Locations, or a combination of the above.
Almost everything can have an image associated with it even months.
Events have a popout window feature.
Language translation can be performed just by editing one file.
Uses the session admin feature of phpWebSite 7.7 allowing secure logons.
The date and time format can be altered by the user.
The time and date can be set to be earlier or later than the server time.
You control what features are active to users in the sidebar.
An event can have a start and ending time, just a start time, or no time at all.
You can set an event to automatically post an article to phpWebSite on a certain date.
Set an event to repeat daily, weekly, monthly, or yearly.
Images stay on the server to be used again and again. They can also be previewed before use.
Error checking points out your corrections without destroying your data.
Cleaner interface and less GET statement clutter.
Allows you to set style classes so your calendar works with your default theme.
Uses themes to create pages.
Admin edit ability when looking at events.
Multiple event purge.


-> Getting Started
Please read your INSTALL for directions in setting up the program for basic operation.

***Administration***

Get started by going into you administration menu. There should be a Calendar icon. Click
on it to go to the Calendar administration page.

You will start off with three buttons on top. The top section is for creating events. We'll get back to that.

Below these buttons are three panels with date, user view, and time format. These effect the appearance of your site.

Let's start with the Date format.
The first option is the order of the date. Change this to the order you wish the month, day, and year to appear. Below that is the appearance of the date. You can choose to show the month name in long form, short form, or not at all. You may also choose to show the date digits with a preceding zero or not and whether you want the year with four digits or two. Pick the format you like and continue down.
The next option down lets you pick a separator. This will ONLY appear if you are not using the long or short month name format. Finish with your choices and click the Go! button to set them in motion.

You can also Edit the Month Image. Pick a month you want to add an image to and click "Go!". Pick or upload an image you want to appear at the top of the month view and click "Change Month View". For more information on selecting an Image, see the section below.

Next is the Change User View. You may choose to use any combination of these. 

-Month View - displays a small calendar. Clicking on the month name brings up the month view. Clicking on the '>' sign brings up the week view. Clicking on a day brings up the day view. Note that the day view will only appear if there is an event on that day. Also note that Netscape has problems with month view. Netscape does not like tables much. If month view is not chosen, a small link line appears at the bottom of the plug-in box that lets the user choose the different views regardless.

-Week View - displays the events coming up in the next 7 days. If a certain day does not appear, that means there is not an event for that day.

-Category, subcategory, location view - brings up a page showing all the events within these criteria for the coming month.

-Today's Events - Good ole Today's View. For those of you nostolgic for the old calendar, today's view shows you just the events for today.

-Small Month View - Again because of Netscape, you can disable the small calendars that appear in the month view.


Change Time Format
Not everyone uses AM / PM format. If you prefer 24 hour clock settings, choose military time. otherwise, stick with standard.

Change Time Difference
Are you in Norway but your web site is housed in Texas, USA? Just set how far ahead (or behind) you are from you web server and volia! your calendar is now on your time.
---------------------------------------------------------------------------------------------------------
***Creating Events***

Events are the meat of the program. You can create an event immediately just by clicking on the 'Create Event' button. However, let's go a little slower.

-> Selecting an Image
Here is a good spot to introduce images. Images can be included with categories, subcategories, locations, and the events themselves. You, need to supply them however. A couple of rules about images. 
1. Always save images as 72 dpi. That is the maximum a monitor can display. Anymore is overkill and takes a long time to load.
2. Keep the images small enough so they accent the information and not overpower it. Be very careful not to admin your site with a huge monitor and forget that some people may be looking at your site with a resolution of 800X600 or less (eek).
3. Save images as jp, png, or gif mode. No tiff, wmp, etc.

The plug-in will refuse images if they are too large but in most cases will let you post most anything. 

Once you know which image you want to use, click the browse button. Go to the directory that your image is on and select it. Once you select it, the path to that image will be copied into the text bar. DO NOT change this. Once you enter the rest of your information and save it, the system will upload your image and associate it with what option you are under.

If there is an image already save to the server you want to use, click on the down arrow. A list will show what files you can access. Pick one and click on 'Preview Image'. The image will appear plus three options.
Use Image - Click this to return back to the form with this image as your selection.
Don't Use - Useful when editing an item, this returns you back to the form with the previous image selected.
Delete Image - Takes you to a deletion option for that image. The page will show all the places that the image is currently being used. If you choose to delete it anyway, it will no longer be selected as the image for those selections and it will be deleted permanently from the server. Be careful.

-> Categories and Subcategories
Before we continue, note that the words Category and subcategory are just generic words the system used to describe their hierarchy. If you would prefer to name them something else, look in your language.php file to change it. For example, Category could be renamed 'Holiday' and Subcategory could be entitled 'Activity'. Then you could have an 'Holiday' Groundhog Day with the 'Activity' Pie-Eating Contests. Whatever you name them, they will be referred to as Category and Subcategory from here on out.
Categories and subcategories are optional. You may create an event without associating it to either. However, they assist in helping your users find certain events and they can lead to them seeing similar events within that category/subcategory.

Create a category by clicking the 'Create Category'. You will see the image selection discussed earlier. Next you can put in the name of the category. This is the minimum requirement. You may also enter a description of the category and an email address of someone who can be contacts specifically about that category. Either may be left blank. Click the Add button to continue. If there are any errors (name missing) the page will come back highlighted for you to fix it. Do so and click the Add button again.

You will be returned to the admin page. A reminder of what action you just performed should appear at the top. You will now also notice some new choices. You may now edit a category, remove it, or create a subcategory. Click on Edit Category to make any changes. Click update when you are finished.

Subcategories have to be associated with a category. The category just created should be selected. Go ahead and click Create Subcategory. This screen should appear familiar. It is just like the category screen. Enter some information here and click the Add button to continue.

Even more options appear! Now you may edit that subcategory or remove it.

You may also notice that if you have category and/or subcategory view enabled, they appear on the sidebar.

Moving on is the location. Your events have to happen somewhere don't they? They don't? well it is not required to post an event. For now let's enter one. Click on the Add Location button.
I know, looks just like the other two. Go ahead and enter some information and click the Add button.

Just like the last two times, you may now edit or remove the location.

Now that we have some options set up, let's make an event. Click the Create Event button.

First we have our image selection back. Enter one if you wish.
Next is the Associate option. Here you can associate an event with a category, subcategory, or neither. Click the radio button to select how you want to associate it, then choose what you want to associate it to.

Next enter the title of the event. This is mandatory. Now enter a description if you wish. Select the location of the event (or not). Pick the date of the event. Finally pick the time of the event. You may also click on the radio button to choose the time schedule. Choose 'Timed Event' if it has a definite start and end time. Choose 'All day event' to have it run all that day (good for holidays or general events). And lastly, choose 'No ending time' if you know when the event will start but not necessarily when it will end (eg, sporting events, picnic, etc).
Now click Create Event and you are finished. The only two mandatory options are the title and the time.

You should now see many new changes. First, the option to edit the event appears on the admin menu. You may also purge events. Look to the sidebar and the event will cause the various views to react.

-> Purging Events
Events should be able to occupy your database for as long as you want. However, occasionally you may wish to purge them.
Calendar will pull events created before the date you search from. Click on the Purge Events button in the Calendar Admin section.
If there are repeats still active or if the event has post activity, you will be warned.
Click on the checkbox of the events you want to delete from the database. Click on "Check All" to check all the events for removal. Click on "Uncheck All" to uncheck all the events. When you are finished making your choices, click the "Delete all checked events" button. BE CAREFUL! Once you click this button, they are removed PERMANENTLY!

-------------------------------------------------------------------------------------------------------
Questions?? Comments?? Bugs??

You may email mcnaneym@tux.appstate.edu for questions, comments, or suggestions on the calendar. I will eventually develop the FAQ for the program.  I have tried to make this plug-in as intuitive as possible. If I have failed in that, let me know so I can correct it. As for bugs, they should Calendar specific, not phpwebsite related.

-------------------------------------------------------------------------------------------------------
The future of Calendar

I will now give more attention to the rewrite of phpWebSite as well as maintaining this plug-in. Suggestions on improvements have already been made from the demo site. I would like to implement:
-Flexible repeat editing - currently you can't remove a component of a repeat schedule. I'm looking into ways of changing this.
-Theme changing - I would like the admin to chose what color scheme to use depending on the theme view. This will take a little work but in the long run would be some good functionality for other plug-ins to use.
-Multiple Admin access - MAY (doubt it though because of the current structure of phpws) change in current form. More likely to be written for rewrite of phpWS.
