- Cd to the course web calendar subdirectory (e.g.: cd /cse/web/courses/cse401/18sp/calendar)
- Run the command: createcal
- Find output (html and ics files) in the current (calendar) directory.
- Edit files ./inputFiles/*.ini to indicate your actual course calendar content, then repeat step 2.
Calendarscreatecal produces html and ical calendars. Students can view the html calendar as part of the course web. Students can subscribe to the ical calendar to add course events to their personal calendars, for example, in Google calendar.
createcal uses university web services to obtain lecture, section, and lab meeting times and locations, and (in most cases) final exam schedule. The initial calendars, created as part of quarterly course web setup, contain this information. The instructional staff can then augment them with lecture topics, links to lecture materials, reading, assignments, office hours, and the like.
The html version of a sample course calendar looks like this (or view it live):
ListsIn addition to calendars, createcal also produces html lists of lecture, section, and lab meetings, in case you prefer that format. They look like this:
HTML customizationscreatecal's HTML output pages can be customized in two ways:
- by editing calstyle.css. Nearly all output elements can be controlled by the style sheet.
- by embedding them in other pages. createcal produces the body of HTML calendars and lists as files that can then be included into whatever HTML wrapper you want.
Single Event Information: lectures.ini, sections.ini, etc.The instructor-supplied information for an event is expressed using blocks. The first three lectures in the sample course are described in file lectures.ini by these three blocks:
# [Auto DateHint] 2011-03-28 [lecture] Description Introduction Materials M1: <a href="../lectures/1-intro.pdf">Slides</a> # [Auto DateHint] 2011-03-30 [lecture] Description More Intro Reading Text: Chapter 1 # [Auto DateHint] 2011-04-01 [lecture] Description Arch Support for OS Reading Text: Chapter 2 Materials M2: <a href="../lectures/2-arch.pdf">Slides</a>The [Auto DateHint] lines are comments, automatically produced by createcal, to make it easier to locate the block that corresponds to a particular lecture. They are updated each time createcal is run.
It's important to note that a content description file does not contain date information used as input by createcal - the comment lines are comments, to be read by humans, and are hints, in the sense that they go out of date if you insert or delete events, until they are updated the next time you run createcal. The absence of dates in the content file means that you can add or delete lecture topics in the content file without having to edit the dates of all following lectures. It also means that the content file for an earlier offering of the course can simply be copied to a new offering's web to create a complete, initial list of topics, with no editing required.
There is a file of information blocks for each type of event, with self-explanatory names like lectures.ini, sections.ini, exams.ini, and so on. Like all files that are inputs to createcal, they are located in subdirectory inputFiles.
Date Information: schedule.iniSingle event information blocks don't contain dates. Instead, dates are obtained from a course schedule file, schedule.ini. The start of that file for the example course is:
[schedule] # Week 1 2011-03-28 lecture hw 2011-03-30 lecture hw 2011-03-31 section 2011-04-01 lecture # Week 2 2011-04-04 lecture hw hw 2011-04-06 lecture 2011-04-07 section 2011-04-08 lecture hwThis means there is a lecture and a homework event on 2011-03-28, the same on 2011-03-30, a section on 2011-03-31, etc. The instructional staff has added the homework tags, but the rest of the file was generated automatically as part of course web setup.
Much of the calendar is created by stepping through the schedule file. Each tag that is encountered is associated with the next successive block in the tag-specific data file. The schedule file excerpt above consumes the first six blocks from lectures.ini, the first two blocks from sections.ini, and the first five blocks from hws.ini.
Regular Meetings: Lectures, Sections, Labs, and config.iniAn event time and location can be specified in the information block for an event. For example, the automatically generated entry in exams.ini describing the final exam for the sample course specifies its time:
[exam] Date 2011-06-08 Lectureid A Summary Final exam Time 14:30 16:20Some event types, like lectures and sections, occur at a regular time in a fixed location. Rather than repeating that information in every event information block, it can be listed once, in file config.ini. config.ini contains blocks. The block name indicates the type of event the information pertains to. For instance:
[lecture] Days Monday Wednesday Friday Lectureid A Location JHN 111 Summary Lecture Time 11:30 12:20This means that lecture section A generally meets in JHN 111 from 11:30-12:20. Exceptions for individual events can be made by declaring new values for these properties in the event-specific information block (e.g., in lectures.ini). This would allow a single lecture to be in a distinct room from the rest, for instance.
(Warning: the Days property is not used to generate event dates. The lecture event dates are determined by the entries in schedule.ini.)
Multiple Regular Meetings: Lectures, Sections, Labs, and config.iniIt is common for a course to have more than one section meeting. In addition, some courses have more than one lecture meeting. createcal is designed to optimize the case where these multiple meetings have the same content by generating an event instance for each lecture/section mentioned in config.ini each time a (single) corresponding tag is found in schedule.ini
For instance, config.ini for the sample course contains this:
[section] Days Thursday Location EEB 054 Sectionid AA Summary Section Time 12:30 13:20 [section] Days Thursday Location EEB 054 Sectionid AB Summary Section Time 13:30 14:20This line in schedule.ini:
2011-03-31 sectiongenerates two events, one for section AA and one for section AB. The event information is taken from a single information block in sections.ini, but the event times and locations differ.
How to deal with multiple, identical meetings that take place on distinct days is addressed in the How Do I... document.
Office Hours: [every]All office hour information must be entered by the instructional staff, since there is no information about them in university databases. To make that as simple as possible in the common case, there is an optimization: the [every] block.
The office hours in the example course were specified by putting this in file ohs.ini:
[every] Days Monday Time 14:00 15:00 Summary OH (jz) Location CSE 534 [every] Days Wednesday Time 13:30 14:30 Summary OH (owen) [every] Days Thursday Except 2011-04-21 Time 11:30 12:30 Summary OH (ethan)If the event occurs at the same time and location on multiple days, you can give those days as a space separated list in a single [every] block. If the time or location varies depending on the day, use distinct [every] blocks.
[every] is self-contained: there are no tags required in the schedule.ini file for the events. Similarly, no information blocks are consumed (from ohs.ini). [every] can be mixed with the mechanisms explained earlier, though: there can be oh tags in schedule.ini and corresponding information blocks in ohs.ini, for office hours beyond the regularly scheduled ones.
Finally, note that there is an exception mechanism for [every]: the Except property shown in the example above prevents the Thursday office hour from being generated on 2011-04-21. If there is more than one exception, the days are given as a space separated vector:
Except 2011-04-21 2011-04-28 2011-05-05
How Do I...
How and when do I run createcal?To run createcal, login to a department Linux machine that has your course web files mounted, navigate to the calendar subdirectory of your course web, and issue the commandBut I want to run it on my Mac. Now what?$ createcalThat command generates the html and ical calendar files. You need to run it each time you modify some input file (e.g., after modifying the description of a lecture).createcal is a Perl program, and can run on anything that has Perl and the required packages installed. Probably the easiest way to get it is to simply copy the files from a standard department Linux machine. If you're running in a directory that has not been initialized by the quarterly web setup process, you have to issue a single createcal command to do the initialization. I'm not typing that command here, because it's generally a mistake to issue it, but createcal -man explains what to do.I taught CSE XXX last year. How do I reuse the lecture syllabus from that offering as a starting point for this year's course?Simply copy the lectures.ini file from the old course web to the new one (overwriting the skeletal lectures.ini created as part of the new course web setup procedure). If the two offerings have the same number of lectures, you're done. If the new offering has more lectures, you'll need to add [lecture] blocks to lectures.ini. If the new offering has fewer lectures, createcal will simply ignore the extra [lecture] blocks.How do I add midterms to the schedule?File schedule.ini will have a lecture tag on the midterm date. Replace that tag with exam. Now create an [exam] information block in file exams.ini, before the block for the final exam, and re-run createcal.My class isn't actually meeting at the time or place the university thinks it is. What should I do?What to do depends:My course has multiple lecture sections. How do I deal with that?
- You've changed only the location and/or meeting time, but not the meeting days
Edit inputFiles/config.ini to update the affected Location and/or Time fields. then run createcal.
- You've changed the meeting days, and...
- You haven't already edited any of the calendar content files
- Edit the (hidden) file .initconfig.ini to correct the information about your meetings.
- Then run createcal -init -gencals to create new basic input files and an initial calendar.html output file. View the output file in your browser to verify the calendar reflects the new meeting days.
- At this point you can begin editing inputFiles/lecture.ini and other content files following the usual directions.
- You have already edited calendar content files
Edit inputFiles/schedule.ini, changing the dates to the ones you're actually meeting on. Then run createcal.The files produced by the setup procedure will have registered all the lecture sections. Assuming the lectures meet on the same days and have the same content, everything should be fine as is. (If not, see the question about multiple labs on differing days.)The calendars list events as "Lecture" but I want them to say "Meeting" instead. How do I do that?Calendar event summary text is taken first from the Summary property of the information block (e.g., in lectures.ini), then from the Summary property of the corresponding block in file config.ini, and then set to the type of the event if neither of those exist. To change all "Lecture"s to "Meeting"s, change the appropriate Summary property in config.ini. To change it for one particular lecture, introduce a Summary property to its information block.How do I improve the look of the html calendar?Nearly all html elements in the calendar have a distinct class. The appearance of those elements is controlled by file calstyle.css, located in the same directory as the calendar itself. You're encouraged to change the style, and share your improvements.Barbara's html calendars look a lot better than mine. What can I do?Copy the calstyle.css file from one of her course webs to yours.My html calendar has gone haywire. What should I do?You have an html error in some content block (probably one used near where the calendar goes wrong). Find it and fix it.My html formatting and links aren't showing up in the ical calendar. How can I get them to show up there?You can't. The ical specification forbids html elements. createcal automatically strips them before generating the ical calendar.My course has two sections on Thursdays, but the html calendar is showing only a single "Section" entry, with no times listed. How can I get two sections, with times?You can't. A design goal of createcal is to avoid cluttering the html calendar. When there is more than one identical event instance on a given date, it is listed just once, without a time.My course has two labs with identical content, but one meets on Tuesdays and one meets on Thursdays. How do I deal with that?
(Note that there is a distinct ical calendar for each section, allowing students to subscribe to the one they're in. Those calendars have complete time information.)The initial schedule.ini will include a lab tag on each Tuesday and Thursday. Each will consume a single [lab] information block from file labs.ini, so you will need to have two successive copies of the lab information there for each distinct lab content.I want to create an event that isn't any of the standard types. How do I do that?
Note that the event generation mechanism in createcal will generate only a single lab on each Tuesday and each Thursday, despite there being two [lab] instances in config.ini. This happens because the Days property of each config.ini block is used as a filter - an event for that block is generated only if the event date falls on a day of the week listed in the Days tag.There is a single, catch-all event type for this use, 'other'. Add other tags to the dates of the events in schedule.ini, and [other] information blocks for the events in file others.init.I want to create an event that will show up in the Section AA ical calendar, but not in the section AB ical calendar. How do I do that?AddI accidentally ran createcal with the -fetch or -init switch, and it overwrote my data files. How can I get them back?SectionID AAto the information block for the event. (To restrict events to only a certain lecture, use a LectureID tag. For labs, use LabID.)If you didn't repeat your mistake, you'll find them in (hidden) directory .inputFilesBackup. createcal makes a single backup copy of files before overwriting.I don't want to use these calendars. What should I do?Simply delete the calendar subdirectory from your course web.
Event Scheduling Details
The figure above shows how event scheduling works. There are four distinct situations:
- [every] blocks
All information is taken from the [every] block itself. Dates are determined by applying the Days property to the course quarter.
- Event type doesn't appear in config.ini.
In this case all information is taken from the information block in the type-specific .ini file.
- Event type appears in config.ini and the information block does not have a Time property.
Each instance in config.ini generates a copy of the event instance. The event information is created by taking the union of the information block (in bar.ini in the figure) and the config.ini instance. The former has precedence over the latter. For example, if a Location tag appears in both, the one from the information block is used.
- Event type appears in config.ini but the information block does have a Time property.
In this case the config.ini file is by-passed, and only a single event instance is produced, using only the information in the information block.
HTML Output Details
HTML Pagescreatecal produces two kinds of HTML pages. The first is the calendar page, which has all course events. The second is a page that lists the dates and descriptions of only a subset of the course events. List-style pages are produced for lectures, sections, labs, and hws, so long as the course has those things.
All HTML files are produced in the main directory, calendar. The file names are:
Customizing the Output
Overviewcreatecal's design is intended to let you customize its output in two ways:
- Make changes to formatting, by editing a style sheet.
- Make changes to the basic HTML page content, e.g., changing the title or adding a line of text before the calendar.
Page FormattingThe appearance of all pages is determined by a style sheet, calstyle.css, that also resides in the main calendar directory. Most formating is based on class attributes. A look at the style sheet and the HTML page source should be enough to identify how to change an element's style. A little experimentation might help as well.
You can change all the usual things: font size and family, background colors, borders (or not), cell sizes and spacing, etc.
Page contentWhen you run createcal, the calendar or list it produces is combined with a template file to create the final HTML page. The template files are in subdirectory htmlTemplates. Default template files are created as part of the course web setup process, and are not subsequently modified by createcal.
Each template file contains the HTML that surrounds the main output of createcal. That means you are free to change what surrounds the main content. For example, you can change the page title, or you can add a line of explanatory text before the main content. That is, if you want some lines of explanatory text above the calendar, add the appropriate html just above the line %%BODY%%.
Here's an example template file for the calendar page:
<html> <!-- DO NOT EDIT THIS FILE. It was automatically created by a program (createcal.pl). Edit the input files (in subdirectory inputFiles/) and re-run createcal instead. --> <head> <LINK REL="stylesheet" HREF="calstyle.css" TYPE="text/css"> <title>CSE 451 Spring 2011 Course Calendar</title> </head> <body> <div class='title'>CSE 451 Spring 2011<br>Course Calendar</div> <p> <center><a href='subscribe.html'>Subscribe to this calendar (Google, iCal, etc.)</a></center> <p> %%BODY%% </body></html>The line "%%BODY%%" is replaced by the calendar when createcal is run, and the result written to calendar.html. (So, if you change the template file, you have to run createcal to make those changes visible.)
Other Placeholders: In addition to %%BODY%%, these additional placeholders are supported:
- %%COURSE_NUM%% Replaced by a string identifying the course, such as "CSE 403"
- %%QTR_YEAR%% Replaced by a string indicating the quarter and year, such as "Autumn 2018"
createcal generates a single HTML calendar, and so all events are placed in that calendar. For convenience, it generates multiple ical calendars - one for each lecture section, one for each section or lab, and one for office hours. (This allows students to subscribe to just the events they are interested in.) An individual event may appear in one or more of these calendars. The rules governing which calendar is chosen depend on the type of the event.
- Lecture, section, and lab events
These are inserted into a single calendar, the one corresponding to the lecture, section, or lab. The event information must specify a LectureID, SectionID, or LabID. The setup procedure arranges this, putting that information in config.ini, so things should work as expected out of the box.
- Exam and homework events
These are always placed in one or more lecture calendars. If no LectureID property is associated with the event, it is placed in all lecture calendars. Otherwise, it is placed in the lecture calendar(s) whose IDs are specified by the LectureID property, which may be a space separated list.
In most cases you will want to either omit the LectureID or else specify exactly one ID.
The only event of these types created by the setup procedure is the final exam. An exam information block is created for the final exam for each lecture section. Things should work as expected out of the box.
- Office hour events
All office hours are put in the (single) office hour calendar.
- 'Other' events
The event information must specify at least one LectureID, SectionID, or LabID. The values of those properties can be space separated lists. The event is put in each calendar corresponding to the specified IDs.
createcal SysAdmin Details
Overviewcreatecal operation is implemented as three distinct phases. The phases are connected via files, as shown in this figure:Initialization of a course web is typically done by issuing a command that runs all three phases:$ createcal -course cse451 -quarter 11au -fetch -init -gencals /www/htdocs/courses/cse451/11au/calendar/The directory argument is optional, and defaults to the current working directory if not given. A configuration file, .fetchconfig.ini, can be used in place of command line options, but is not required. The ordering of command line options is not significant. See $ createcal -man for full information on available options.
Once initialized, users can modify the .ini files and re-run the final processing phase. In the usual case, they issue this command while the current working directory is, for our example, /www/htdocs/courses/cse451/11au/calendar/. Operation defaults to the final processing stage if no processing stage argument is given:$ createcal
-fetch PhaseNote: The fetch phase implementation is UW specific, but not CSE specific.This phase collects the information available from online sources about the course schedule. It doesn't normally make sense to run this phase without running -init as well, or vice versa. The two are separated, though, to try to isolate the portion of the code base that is UW specific. The fact that the two phases communicate via a file allows later phases to be used when the file is generated in some other way - manually, say, or by a program built for data sources other than UW web services.
The output of this phase is a hidden file, because there is no reason for users to edit it, or even notice it is there.
Here is a sample .initconfig.ini file:[config] Timezone America/Los_Angeles Urlprefix http://www.cs.washington.edu/education/courses/cse451/11sp/calendar [course] Number 451 Prefix cse [quarter] EndDate 2011-06-03 FullQuarterName spring FullYear 2011 ShortQuarter sp StartDate 2011-03-28 Summary 11sp Year 11 [lecture] Days Monday Wednesday Friday LectureID A Location JHN 111 ShortDays MWF Summary Lecture Time 11:30 12:20 [exam] Date 2011-06-08 LectureID A Summary Final exam Time 14:30 16:20 [section] Days Thursday Location EEB 054 SectionID AA ShortDays Th Summary Section Time 12:30 13:20 [section] Days Thursday Location EEB 054 SectionID AB ShortDays Th Summary Section Time 13:30 14:20 [holiday] Date 2011-05-30 Summary Memorial DayThe first two blocks of information come directly from the invocation - either command line arguments or the .fetchconfig.ini file. The URL is the name of the file system directory as accessed through the web server. It defaults to the UW CSE-specific form shown if no explicit information is given. (Similarly, the time zone defaults to the one shown if no explicit information is given.)
The [quarter] block contains information obtained obtained from the invocation and from web services: the dates are from web services, the remainder from invocation arguments (and parsing of those arguments into pieces useful in the next phase of processing).
The remainder of the contents are obtained from web services. There can be multiple instances of each kind of these blocks.
In addition to the block types shown, the [lab] block is also recognized. Its syntax and semantics are identical to the [section] block, except for labeling of calendar events in the final output phase.
-init PhaseThis phase reads the .initconfig.ini file and produces initial versions of the files the user is intended to see and edit. Those files include both the .ini files in subdirectory inputFiles and .template files in subdirectory htmlTemplates.
-gencals PhaseThis phase produces the HTML and ical output files. As a side-effect, it also updates "date hints" in the .ini files. Those hints are useful to users, and so it's recommended that this phase be run as part of initial web setup.
.fetchconfig.iniThis file is used only by -fetch stage processing, and is optional. If it exists, it must be located in the target directory. Command line options take precedence over information contained in this file.
Here's an example file, showing everything that can be specified:TimeZone America/Los_Angeles URLPrefix http://www.cs.washington.edu/education/courses/cse451/11sp/calendar Course cse451 Quarter 11spNote that the time zone and url prefix properties default to the UW CSE-appropriate values shown (and so are not required inputs to -fetch processing for UW CSE).
File BackupWhenever a stage of processing is invoked that might write some file, createcal first makes copies of existing files. Because all stages write files, a backup is always made.
The backup copy is put in directory .inputFilesBackup. Copies are made of all .ini files in inputFiles/, all .template files in htmlTemplates/, and style.css.
[comments to support at cs.washington.edu]