public:calcms:parameters
Defining Usecases
  • A usecase like „coming soon events“ is defined by building a URL.
  • It contains
    • a controller like events.cgi, which processes the request (e.g. to process a event query)
    • a set of parameters to specify the request (e.g. next 3 events from now ⇒ &from=today&time=now&limit=3 )
    • how to display the output by setting a template (e.g. a html page showing a simple list of events ⇒ &template=event_list.html ).
  • Below you find the controllers, its request parameters and usecases which are already predefined for them. You can define your own usecases as described below.

pretty URLs

Rewrite rules map URLs containing parameters to simple pretty URLs. This is to be configured at your apache configuration at <Directory> section (recommended) or at a .htaccess file in the controller directory (slower) For common used controller requests there are predefined rewrite-rules, e.g.

events.cgi?&from=today&time=now&template=event_list.html => /coming_soon/

You are free to define additional rewrite rules to built pretty URLs for your own usecases or modify the existing ones. Your own templates should always link to pretty URLs. Request results contain of nested sets of variables which can be used in the template views.

Event Controller

Request Parameters

Variable Description Example
date show single date, yyyy-mm-dd or [today, tomorrow, yesterday] 2009-09-03
from_date show from start date, yyyy-mm-dd or [today, tomorrow, yesterday] 2009-09-01
till_date show till stop stop, yyyy-mm-dd or [today, tomorrow, yesterday] 2009-11-30
time select time, hh:mm or [now] 18:00
time_of_day select time span, predefined at configuration_file,
values: [night, morning, noon, afternoon, evening]
noon
weekday set number of day of week, starting with monday=1,
values: [1,2,3,4,5,6,7]
1
event_id show event by internal database id of the event 7399
category filter by category Archiv
location filter by location Pi Radio
tag filter by tag
template specify output view be setting template view overview
search search for a string Berlin
limit limit number of results, e.g. for current playlist 5

pretty URLs

show all broadcasts from 2009-09-03

show all broadcasts september 2009

show all broadcasts september 2009, mondays

show details of a selected broadcast

show playlist (next 3 broadcasts)

export todays iCalendar entries

Calendar Controller

Request Parameters

Variable Description Example
date show date 2009-09-03
from_date set start date 2009-09-01
till_date set end date 2009-11-30

pretty URLs

Rewrite Rule Configuration

With help of rewrite rules you can access controllers with usecase names like /playlist/ instead of /events.cgi?template=playlist&from_date=today&from_time=now&limit=3$1

Hint: see your apache rewrite log for checking rewrite messages:

tail -f /var/log/apache2/rewrite.log | grep "rewrite\|pass"| grep -v "init rewrite"

Aggregator

The aggregator can be used to embed the controllers described above into your website/CMS. You can define <div> blocks in your CMS to put the controller output at a certain place in your layout. For example the aggregator replaces a block <div id=„calcms_calendar“/> with the result of the calendar controller request. Embedding of many controllers using AJAX takes some time and makes it hard for search machines to crawl your site. Generally the aggregator will process faster and might put the output to the cache. From outside access behaves like receiving a single HTML file.

These 4 rules define requests to your site to show all events in a given datetime range or a single event by its id. <Directory /static>

#direct access for all files (includes cached files)
  RewriteCond  %{REQUEST_FILENAME} -f
  RewriteRule (.*) $1 [L]
  RewriteCond  %{REQUEST_FILENAME} -d
  RewriteRule (.*) $1 [L]

#controller
  RewriteRule ^kalender/(\d{4}-\d{2}-\d{2})_(\d{4}-\d{2}-\d{2})\.html[\?]?(.*)$	/agenda/aggregate.cgi?from_date=$1&till_date=$2$3 [L]
  RewriteRule ^kalender/(\d{4}-\d{2}-\d{2})\.html[\?]?(.*)$          		/agenda/aggregate.cgi?date=$1$2 [L]
  RewriteRule ^sendungen/(\d{4}-\d{2}-\d{2})\.html[\?]?(.*)$         		/agenda/aggregate.cgi?date=$1$2 [L]
  RewriteRule ^sendung/(\d+)\.html[\?]?(.*)$                                 	/agenda/aggregate.cgi?event_id=$1$2 [L]

Other controllers

These URL rewrites define the basic usecases.

<Directory /agenda>

  RewriteEngine on

  #direct access for all files (includes cached files)
  RewriteCond  %{REQUEST_FILENAME} -f
  RewriteRule (.*) $1 [L]
  RewriteCond  %{REQUEST_FILENAME} -d   
  RewriteRule (.*) $1 [L]

  #controller

RewriteRule ^kommentare/(\d+)/(\d{4}-\d{2}-\d{2}[T\+]\d{2}\:\d{2})(\:\d{2})?/(.*)$ comments.cgi?template=comments.html&event_id=$1&event_start=$2$4 [L]
RewriteRule ^neueste_kommentare/(.*)$ 					comments.cgi?template=comments_newest.html&limit=3&type=list$1 [L]
RewriteRule ^feed_kommentare/(.*)$ 					comments.cgi?template=comments.xml&limit=20$1 [L]
RewriteRule ^kommentar_neu/(.*)$ 					add_comment.cgi$1 [L]

RewriteRule ^sendung/(\d+)/[^&]*(&.*)?$ 				events.cgi?template=event_details.html&event_id=$1$2 [L]
RewriteRule ^sendung/(.*)$ 						events.cgi?$1 [L]

RewriteRule ^sendungen/(\d{4}-\d{2}-\d{2})/(\d{4}-\d{2}-\d{2})/(\d)/(.*)$ events.cgi?template=event_list.html&from_date=$1&till_date=$2&weekday=$3$4 [L]
RewriteRule ^sendungen/(\d{4}-\d{2}-\d{2})/(\d{4}-\d{2}-\d{2})/(.*)$ 	events.cgi?template=event_list.html&from_date=$1&till_date=$2$3 [L]
RewriteRule ^sendungen/(\d{4}-\d{2}-\d{2})/(.*)$ 			events.cgi?template=event_list.html&date=$1$2 [L]
RewriteRule ^sendungen/heute/(.*)$ 					events.cgi?template=event_list.html&date=today$1 [L]
RewriteRule ^sendungen/(.*)$ 						events.cgi?$1 [L]

RewriteRule ^menu/(\d{4}-\d{2}-\d{2})/(\d{4}-\d{2}-\d{2})/(\d)/(.*)$	events.cgi?template=event_menu.html&from_date=$1&till_date=$2&weekday=$3$4 [L]
RewriteRule ^menu/(\d{4}-\d{2}-\d{2})/(\d{4}-\d{2}-\d{2})/(.*)$ 	events.cgi?template=event_menu.html&from_date=$1&till_date=$2$3 [L]
RewriteRule ^menu/(\d{4}-\d{2}-\d{2})/(.*)$ 				events.cgi?template=event_menu.html&date=$1$2 [L]
RewriteRule ^menu/heute/(.*)$ 						events.cgi?template=event_menu.html&date=today$1 [L]
RewriteRule ^menu/(.*)$ 						events.cgi?$1 [L]

RewriteRule ^kalender/(\d{4}-\d{2}-\d{2})/$ 				cal.cgi?date=$1 [L]
RewriteRule ^kalender/(\d{4}-\d{2}-\d{2})/(\d{4}-\d{2}-\d{2})/$ 	cal.cgi?from_date=$1&till_date=$2 [L]
RewriteRule ^kalender/(.*)$ 						cal.cgi?$1 [L]

RewriteRule ^kategorien/(.*)$ 						category.cgi?$1 [L]
RewriteRule ^sendereihen/(.*)$ 						series_names.cgi?$1 [L]

RewriteRule ^playlist/(.*)$ 						events.cgi?template=event_playlist.html&time=now&limit=3$1 [L]
RewriteRule ^running_event/(.*)$ 					events.cgi?template=event_running.html&time=now&limit=1$1 [L]
RewriteRule ^feed/(.*)$ 						events.cgi?template=event.xml&time=now&limit=15$1 [L]
RewriteRule ^feed.xml[\?]?(.*)$                				events.cgi?template=event.xml&time=now&limit=15$1 [L]

RewriteRule ^ical/(\d{4}-\d{2}-\d{2})/(\d{4}-\d{2}-\d{2})/(\d)/(.*)$ 	events.cgi?template=event.ics&from_date=$1&till_date=$2&weekday=$3$4 [L]
RewriteRule ^ical/(\d{4}-\d{2}-\d{2})/(\d{4}-\d{2}-\d{2})/(.*)$ 	events.cgi?template=event.ics&from_date=$1&till_date=$2$3 [L]
RewriteRule ^ical/(\d{4}-\d{2}-\d{2})/(.*)$ 				events.cgi?template=event.ics&date=$1$2 [L]
RewriteRule ^ical/(.*)$ 						events.cgi?template=event.ics$1 [L]
RewriteRule ^ical.ics[\?]?(.*)$                                         events.cgi?template=event.ics$1 [L]

RewriteRule ^suche/(.*?)/(.*)/(.*)$					events.cgi?template=event_list.html&project=$1&search=$2$3 [L]
RewriteRule ^suche/(.*?)/(.*)$ 						events.cgi?template=event_list.html&search=$1$2 [L]
RewriteRule ^kategorie/(.*?)/(.*)/(.*)$					events.cgi?template=event_list.html&project=$1&category=$2$3 [L]
RewriteRule ^kategorie/(.*?)/(.*)$ 					events.cgi?template=event_list.html&category=$1$2 [L]
RewriteRule ^playlist.txt/(.*)$ 					events.cgi?template=event_playlist.txt&time=now&limit=1$1 [L]
RewriteRule ^playlist_show/(.*)$ 					events.cgi?template=event_playlist_show.html&time=now&limit=3$1 [L]
RewriteRule ^json/(.*)$ 						events.cgi?template=event.json&time=now&limit=15$1 [L]
RewriteRule ^sendereihe/(.*?)/(.*)/(.*)$				events.cgi?template=event_list.html&project=$1&series_name=$2$3 [L]
RewriteRule ^sendereihe/(.*?)/(.*)$ 					events.cgi?template=event_list.html&series_name=$1$2 [L]

Cache

All external and internal pretty URLs should target the directory where the cache is located. If the file is not found in this directory:

  • the aggregator or any other controller processes the request
  • returns the result to the client and
  • creates the file at the cache directory.

When the same request comes in again, the file be delivered directly without starting any controller instance.

Debugging
  • To enable debugging output
    • set debug⇒'1' at configuration_file
    • add 'debug' parameter to URL: &debug=value
    • debug output will be written to the calcms application log file
    • example:
      http://localhost/agenda/sendungen/2009-09-03/&debug=sql

Debug Parameters

All controllers:

Variable Description
&debug=cache_files show mapping from url to cache file names
&debug=template show available template variables and their values
&debug=sql show SLQ request
&debug=db_results show results from database
&debug=final_results show modified results from database

Calendar controller only:

Variable Description
&debug=day_results show day results of the selected calendar
&debug=year show selected calendar: years, months and days

Impressum Datenschutz