Contents:
Why?
Features
Install
Tags
Templates
Links
Multi Lingual
Permissions
Why:
Why should I take the time to learn the ins and outs of Post-Schedule when there are other feature replete calendar programs out there that are easier to use? While it is true that you could use a different calendar application, Post-Schedule gives you an unprecedented degree of user customization. Virtually every aspect of the visual display can be changed to fit your mood just by making simple changes to the relevant templates. As a matter of fact Post-Schedule does not contain any html code at all except for a few simple dropdown boxes used in the form. And even these can be done away with if desired. Even the submit form is done entirely through a template. This makes it possible to add javascript code for pre and post submit functions. In this way the calendar can be expanded without changing a single line of program code.
Features:
- All aspects of the user interface are template driven using simple tags (ie {DATE})
- First day of week can be any of the 7 days (Who says you can't start a week on a Wednesday)
- Special effects such as popups can be added to the template making it easy to change the behavior of your calendar
- Hours can be shown in 12 hour or 24 hour formats
- Easy admin makes it possible to easily add, modify and delete topics
- Lists can be shown within separate topics
- Month views can be shown as Calendar or lists of events or anything else that you can imagine
- Any type of image can be added to display topic etc...
- style sheets are fully supported. Each topic can be in it's own color and font.
- styles can be in their own files or included as part of a themes styles
- admins can change from one template to another using simple drop down menus
- templates can be changed on the fly for interesting effects. Offer your visitors a choice of calendar or list views
- In month view any number of weeks can be shown (ie. 1 or 2 week views)
- In year view any number of months can be displayed (ie 2 month or 6 month views)
- Full permission support for ADD, EDIT, DELETE, MODERATE and OVERVIEW different groups can have different privileges
- Users with MODERATE permission can post events directly to calendar other events must be approved
- Events are censored according to PostNukes censor list.
- Events are easily approved by anyone with ADD permissions or better using simple admin interface
- Separate templates for Year, Month, Day, Event, Submit, Messages, Headers and Footers make it easy to customize
- Unlimited number of templates for each type can be made and called on the fly
- bgcolor1, bgcolor2, bgcolor3 and bgcolor4 from themes are made available as tags to your templates
- Default templates are included so you can get started right away
- alternate hover and list views are included in month templates
- Submit, Approve, Edit and Delete function all use the same form making some cool opportunities for javascript programmers to make use of pre submit and post submit functions. (This is strictly do it yourself)
- Multi lingual enabled
Install:
The install is quite easy thanks to the new module initialize function. Just follow these few easy steps.
- Move the PostSchedule files into your modules directory.
- Goto the admin/modules menu item and regenerate the modules list
- The PostSchedule module should show up in the modules list. Click on the initialize link to set up the database.
- Activate the module
- Goto your menu block and insert a 'Calendar' link to 'index.php?module=PostSchedule'
You should be all set to start adding events today!
Tags:
Access to the database of events is accomplished through the use of tags. A tag looks something like this (ie. {MONTH}/{DAY}/{YEAR} would return 03/09/1959) A tag is replaced by actual data at compile time which happens before the page is actually displayed. Following is a list of tags that are available to the various templates.
- Common to all Templates:BGCOLOR1, BGCOLOR2, BGCOLOR3, BGCOLOR4, TEXTCOLOR1, TEXTCOLOR2, ACCESSLEVEL, DAYLONG1, DAYSHORT1, DAYLONG2, DAYSHORT2, DAYLONG3, DAYLONG4, DAYSHORT4, DAYLONG5, DAYSHORT5, DAYLONG6, DAYSHORT6, DAYLONG7, DAYSHORT7, DAYLONG, DAYSHORT, MODNAME, MONTH, MONTHSHORT, MONTHLONG, DAY, YEAR, SUBMITLINK, DAYLINK, MONTHLINK, YEARLINK, ddJUMPMONTH, ,ddJUMPDAY, ddJUMPYEAR, ddVIEW, HEADER, FOOTER
- Notes:Accesslevel will return a number between '0' and '8' which corresponds to '0' no permissions to '8' admin permissions. In this way you can check your users current permission level. Daylong1-7 and Dayshort1-7 correspond to the long and short names of the weekdays as defined by PostNukes current language settings. Modname returns the current name of your module which should normally be PostSchedule. Most of these tags are used in the header and footer templates though they could also be used in any of your other templates as well.
- Displayed Events:SUBJECT, EID, UID, SUBMITTEDBY, APPROVEDBY, AID, SUBMITMONTH, SUBMITMONTHLONG, SUBMITMONTHSHORT, SUBMITDAY, SUBMITYEAR, SUBMITHOUR, SUBMITAMPM, SUBMITMIN, SUBMITSEC, APPROVEDMONTH, APPROVEDMONTHLONG, APPROVEDMONTHSHORT, APPROVEDDAY, APPROVEDYEAR, APPROVEDHOUR, APPROVEDAMPM, APPROVEDMIN, APPROVEDSEC, STARTMONTH, STARTMONTHLONG, STARTMONTHSHORT, STARTDAY, STARTYEAR, STARTHOUR, STARTAMPM, STARTMIN, ENDMONTH, ENDMONTHLONG, ENDMONTHSHORT, ENDDAY, ENDYEAR, ENDHOUR, ENDAMPM, ENDMIN, ALLDAYEVENT, REPEATTYPE, BODY, ebBODY, ebSUBJECT, STARTDAYLINK, ENDDAYLINK, EVENTLINK, TOPICIMAGE, TOPICNAME, TOPICTEXT, EDITLINK, escBODY, escSUBJECT
- Notes:These events are not currently available to the year view but should be fine almost anywhere else. ebBODY and ebSUBJECT are for use in forms such as the submit form. escBODY and escSUBJECT are the same as BODY and SUBJECT but special characters are escaped for javascript usage.
-
- Submit Form:SUBJECT, ddOPTION, ddTOPICS, ddREPEAT, ddSTARTMONTH, ddSTARTDAY, ddSTARTYEAR, ddENDMONTH, ddENDDAY, ddENDYEAR, ddSTARTMIN, ddENDMIN, ddENDAMPM, ddSTARTAMPM, ddSTARTHOUR, ddENDHOUR, ddSTARTHOUR, ddENDHOUR, BODY, EID, PREVIEW
- Notes:Most of these tags are used in the submit form to provide up to the date information when editing, previewing and deleting. The PREVIEW tag should be placed where you want the example event displayed when previewing.
- Month View:NEXTLINK, PREVLINK, CURRENTMONTH, CURRENTMONTHSHORT, CURRENTMONTHLONG, CURRENTDAY, CURRENTYEAR, CURRENTDATELINK, NUMEVENTS, NUMDAYEVENTS
- Notes:Nextlink and prevlink will contain links to the previous and next months. Currentdatelink points to the day view for the current date. Numevents contain the number of events for the current month while NUMDAYEVENTS shows the number of events for the current day in the month.
- Year View:NEXTLINK, PREVLINK, THISYEAR, THISMONTH, THISMONTHSHORT, THISMONTHLONG, MONTHTYPE, DAYTYPE, CURRENTMONTH, CURRENTMONTHSHORT, CURRENTMONTHLONG, CURRENTDAY, CURRENTYEAR, CURRENTDATELINK, EVENTCOUNT
- Notes:Nextlink and prevlink are links to the previous and next years. Monthtype will either return 'currentmonth' or 'othermonth'. Daytype will return either 'today' or 'otherday' these can be used to highlight current day and month different from the others. Eventcount returns the total number of events for the current day.
- Day View:NEXTLINK, PREVLINK, NUMEVENTS, NUMALLDAYEVENTS, NUMTIMEDEVENTS
- Notes:Nextlink and prevlink show next and previous days. Numevents shows total events for the day. Numalldayevents show number of all day events only. Numtimedevents show the number of timed events only.
Templates:
The easiest way to get started with the Post-Schedule templates is to modify one of the existing default templates. I've tried to incorporate a little of everything from javascript to stylesheets. The default implementation is not necessarily the best possible solution. Remember the default templates are meant to be nothing more than examples. Start with the header, footer, preview, message and event templates as these tend to be the easiest. I'll give a few thoughts on the others here to get you going. At first the templates can seem overwhelming. Just remember while there are a lot of tags that can be used, you are not required to use all of them. Your templates can be as simple of complex as you want.
- Header, Footer, Event, Preview, Message:These are pretty easy. Just fill in the HTML using tags from the appropriate areas. Pretty much whatever you ask for is displayed as is.
- Day View:There are 4 blocks defined in this template. You probably won't use all 3 blocks at once but who knows.
- DAYBLOCK:Place the begin and end block tags around the code that defines the day template. This will be repeated for each day that is requested.
- Timed events:Shows timed events only. Place code for the topics inside the TIMETOPICBLOCK loop. Each topic will generate a call to this block. The TIMEEVENTLIST block holds the code for each event within the topic list.
- All Day Events:Shows all day events only. Place code for the topics inside the DAYTOPICBLOCK loop. Each topic will generate a call to this block. The DAYEVENTLIST block holds the code for each event within the topic list.
- All Events:This block will show all events together. Place code for the topics inside the ALLTOPICBLOCK loop. Each topic will generate a call to this block. The ALLEVENTLIST block holds the code for each event within the topic list.
- Month:There are 4 blocks of code that can be defined for the month
- The WEEKBLOCK is where you place the code to open and close a week. In a typical calendar this would just start a new row for the week.
- The DAYBLOCK is where you place the code for each individual day.
- The TOPICBLOCK is where code for each group of events belonging to the same topic goes.
- The EVENTLIST is code for each individual event in the list.
- Submit:The submit template is a pretty straight forward form. You can do pretty much whatever you want here just make sure you return all the required variables or Post-Schedule will choke (Ack). Even if you don't want to use all the fields; for instance maybe you don't want to use topics. You can still include a default topic for Post-Schedule and modify your other templates to not display them. Following are the required submit variables:
- eid
- subject
- alldayevent
- body
- op2
- month
- day
- year
- tid (topic id)
- alldayevent
- starthour
- startmin
- startampm
- endhour
- endmin
- endampm
- repeat
- endmonth
- endday
- endyear
- option (what to do with it: submit, preview, etc.
- Year:Pretty easy stuff. There are 3 blocks here MONTHBLOCK, WEEKBLOCK, DAYBLOCK. Each contains code to create the appropriate sections of the year. This view takes a while to generate as it looks up the number of events available for each day of the year.
- Init:The init template is a special case. No matter how many times it is called it will only generate output once per page. This makes it ideal for including javascript libraries, setting variables etc. This template is called whenever a PostSchedule component is being displayed. If you find it necessary to include this code as part of the tag on your PostNuke web page you can also call this template from within your PostNuke theme. Do a quick search for the </head> tag in your theme and just above this line place this piece of code: include ("modules/PostSchedule/init.php");
Links:
Knowing how to call the various functions of the calendar make it possible to generate some nice displays. Following is an explanation of the links used. Some parameters are required and some are optional. Let's start with the most basic of links:
- http://yoursite.com/index.php?module=PostSchedule This will display the month view for the current month.
- view=month|day|year|submit|event The view selects from a list of views including the month, day, year, submit and event views
- num=x The num parameter will show x weeks or months in the month and year views.
- date=mm/dd/yyyy The date parameter displays the current day, month, submit or year depending on the view
- eid=xx with view=submit will put you into edit/delete mode. This only works if you have the proper permissions though so don't get excited.
- http://yoursite.com/index.php?module=PostSchedule&type=admin Throws you into admin mode but only if you have admin permissions. You can also access the admin menu by going through PostNuke's Administration link
Here are a few examples:
- http://yoursite.com/index.php?module=PostSchedule&view=day Will display the day view for the current date
- http://yoursite.com/index.php?module=PostSchedule&view=day&date=03/09/2002 Will display the events in day view for march 9th 2002
- http://yoursite.com/index.php?module=PostSchedule&view=month&num=2 displays 2 weeks of the current month starting at the current date
- http://yoursite.com/index.php?module=PostSchedule&view=month&num=2&date=03/09/2002 displays 2 weeks in month view starting with the week in which the date march 9th 2002 occurs.
- http://yoursite.com/index.php?module=PostSchedule&view=year&date=03/09/2010&num=6 displays year view starting with the month in which 'date' occurs and showing 6 months worth
- http://yoursite.com/index.php?module=PostSchedule&view=submit&eid=3 Will load up the submit view with data from event #3. You can then edit or delete the event.
Multi Lingual:
In the pnlang directory you'll find language directories for each of the supported languages. Currently this is english only (eng). Post-Schedule will look in the current languages directory as defined by PostNuke or english as the default. Inside this directory will be a file called template.php. This file contains Post-Schedule's main language constructs. Feel free to add as many new strings as you might like or change the ones that are already there. The default templates use this method to create a multi lingual calendar. If you don't want to be multi lingual then feel free to hardcode these lines right into your templates.
Permissions:
A quick guide to Post-Schedules implementation of permissions
- None:Cannot access the calendar at all
- Overview:Can't do much (still who knows about the future)
- Read:Can see events but can't add new events.
- Comment:Can submit events but they are not auto approved.
- Moderate:Can submit. Events are auto approved.
- Edit:Can edit events but cannot approve or delete events
- Add:Can approve events and edit but not delete
- Delete:Can delete events as well as approve and edit
- AdminCan do it all.
As you can see this gives you lots of options over who can do what on your site. Experiment with different settings and if you come up with some cool scenarios let me know so we can share them with all our users. And now a few of my own scenarios.
- You want to have a private calendar that none of your users can see. Try this:
- Group:All Users
- Component:PostSchedule::
- Instance:::
- Permission:none
Place this above any of your generic permissions but below your admin permissions
- You want anonymous users to be able to submit new events but only registered users are auto approved.
- Group:Unregistered
- Component:PostSchedule::
- Instance:::
- Permission:Comment
This allows unregistered users to submit new events
- Group:Users
- Component:PostSchedule::
- Instance:::
- Permission:Moderate
This allows auto post for registered users
There are of course several ways you could accomplish these scenarios but these should start you thinking.
Note:As of this writing postnuke's permission system is still under development. I find that sometimes I'm better off setting a user permission rather than a group permission. Most of the same settings can be found under user permissions. After you set a permission make sure you thoroughly test your system as the wrong permissions could open up your site to attack.