Course Outliner Documentation (Version 0.4)
Introduction
outline.txt
preferences.php
index.php
content.php
calendar.txt
feedback
Making changes
Introduction
Course Outliner is designed to:
- read an outline.txt file that defines the topics for the course.
- create a hyperlinked table showing the outline of topics for the course.
- display the content of each topic in the outline and create the navigation links to go to the previous or next topics in the outline.
There are six essential files used by Course Outliner. They are:
- outline.txt
- This is a tab-delimited text file that defines the outline of topics. Each topic is a separate line in the file. Tabs are used to indent the topic as desired.
- preferences.php
- This preferences file is used to specify the course name, professor's name, etc.
- index.php
- This is the introductory page.
- content.php
- This page serves the content pages.
- calendar.txt
- This is a tab-delimited text file that defines dates and topics to be covered (or events).
- cal.php
- This page displays the dates and events defined in calendar.txt on a navigable calendar.
The first four files should be in the same directory. Also in this directory is a calendar directory that has cal.php and calendar.txt. Also in this directory are the content folders. In each content folder is its associated content file. Content files are html files with no <html>, <head>, or <body> tags.
Many PHP functions are contained in the file outliner.php. PHP functions for the feedback form are in feedback.php. Style classes are defined in outliner.css.
outline.txt
The outline.txt file defines the outline for the course. Each line corresponds to a topic; each topic corresponds to an associated content page. Topics are indented in the outline using tabs. Consider the following example outline.txt file.
motion
velocity
position
displacement
average velocity
instantaneous velocity
momentum
relativistic momentum
non-relativistic momentum
momentum principle
change in momentum
predicting momentum
motion applications
uniform circular motion
gravitational interactions
circular orbit
elliptical orbit
projectile motion
coulomb interactions
simple systems
preferences.php
The preferences.php file specifies variable names such as the course prefix, course name, professor's name, etc.
index.php
The index.php file is the starting page for the course. It generates the outline table and provides an introduction to the course. For the outline above, the table generated by the index.php file would look something like this (Note that the links will not work in this example.):
content.php
The content.php file can be thought of as the content server. It takes the content for a single topic (this is stored in a content page) and puts it into the page template. It formats the outline table to indicate the topic from the outline that is being shown. It also creates navigation links to go to the previous and next topics.
Its big benefit is that the content pages only contain the content being shown. Thus, you can modify the look of all content pages by merely modifying the content.php file.
Please note the following formatting rules:
- One content page should be created for each topic in the outline.
- A content page should have the same name (with same capitalization) as the topic, but with an underscore (_) in place of each space ( ) that is in the topic.
- Each content page should end with the extension ".php".
- Each content page should be in its own folder with the same name, without the ".php" extension.
- The root of the content folders should be the same as the course outline.
The screen capture below shows one content file within the folder hierarchy that corresponds to the topics listed in the outline above.
calendar.txt
In ./calendar/, there is a file calendar.txt that defines dates and topics to be covered (or events). The file is tab delimited and is in the format date event.
For example, the calendar.txt file in the example is
1/10/2006 Course Introduction
1/11/2006 Math Review
Modify this file to add events and dates.
Feedback
A feedback form can be displayed at the bottom of each content page. Feedback is stored in a folder called feedback. When feedback is first submitted on a particular content page, a feedback file called feedback.txt is created in the feedback folder in a subfolder corresponding to the topic.
The folder tree used in the feedback folder corresponds to the course outline, just like the content files.
Be default, a feedback form will be shown for each content page. To modify the default behavior, change the following line to TRUE in the file outliner.php.
$repressFeedback=FALSE;
You can repress the feedback on any content page by including the following line in the content page.
<? $repressFeedback=TRUE; ?>
Making changes
You can modify the style of the pages by editing index.php and content.php. It will be easiest to simply modify the css definitions. However, you can also modify the HTML. You can also very easily change the location of things like the navigation links and the topic heading.
To help you understand the files, here's a brief overview of some of the parts.
PHP functions
The main body of PHP functions are between the <? and ?> tags. The functions include:
- section2Filename
- This function takes a section (i.e. topic) name and converts it to a filename by replacing spaces with underscores and appending a .html extension.
- section2Folder
- This function takes a section (i.e. topic) name and converts it to a folder name by replacing spaces with underscores.
- section2Path
- This function converts a section name (i.e. topic) and converts it to a full path name, including the filename.
- filename2Section
- This function takes a filename (of a content file) and converts it to a section (i.e. topic) name by replacing underscores with spaces, removing the file's path, and removing the .html extension.
- getPath
- This function takes a section name, determines the path to the file, including the filename, and returns the filename.
- getPath
- This function takes a section name, determines the path to the feedback file.
- relPath
- This function takes a section name, determines the path to the file, and returns the path. It's useful for easily creating relative links within content files.
- readOutline
- This function reads the outline.txt file and returns a two-dimensional array. Each element of the array is a 3-dimensional array storing [0] the level of the topic (1 is highest level, then 2, or 3 for lower levels), [1] the name of the topic, and [2] the parent's name of the topic (null string for top-level topic).
- Outline2Str
- This function takes the 2-D array created by readOutline, converts it HTML code, and returns the HTML as a string. It's best to leave this function as it is and simply modify the css classes that are used by this HTML code.
- navLinks
- This function takes the outline array as created by readOutline and the current section. It returns the HTML code for the navigation links to the previous and next topics in the outline.
In version 0.4, functions to convert the content number (which is an index for a content file in outline.txt) to a filename and a section number to a content number were added so that the content number rather than filename would be displayed in the URL.
If you edit the HTML of the page, you should know that the outline is displayed in the page at the location of:
<?
echo Outline2Str($outline,$section);
?>
The navigation links are displayed at the location of
<?
echo navLinks($outline,$section);
?>
The topic name is displayed at the location of
<?
echo "$section";
?>
The content of the html file served by content.php is displayed at the location of
<?
include($filename);
?>
JavaScript functions
The JavaScript functions are used to change the div class upon rollovers in the outline table as well as to make the entire cell of the table a hyperlink. These should probably not be edited. There is also a function to open a new browser window.
|