Please realize that much of the documentation for CS Roo is in the form of slides presented in slide-decks, shows, just like the one you are currently viewing.
One key feature of using slides in the show display format provided with CS Roo is the ability for any site registered user to enter additional information in the form of a note under each slide.
Once you establish working site logins you can try this out for yourself.
This session covers quickly a number of basic things that you must do to install or update a copy of a course website based upon CS Roo. The next session after this, called the overview, will fill in more detail about how pages are structured, etc.
As a very basic bit of pragmatics, note the last slide in this session discusses how to change the course logo to something other than the CS Roo default. Do not underestimate the importance of a clear logo to anchor the look and feel of a page.
No matter what, when moving to a new semester the templates will require editing. One of the critical questions is when to simply make an in-place copy of the site from the previous semester versus when to go and get new and updated versions of the original templates?
It is probably a good idea to ask how much has changed since the original download of the templates.
Here is a useful trick. If you are in a browser looking at the current site, ask the browser to show you the source for the page. The second line will be something like: ‘Version 2.2 January 20 2014’. This will tell you which release of CS Roo was the basis for the current site.
As of CS Roo Version 3 there is a change log that can be viewed to learn about major changes.
While there are several conventions in place for house and name semester specific folders associated with course websites, it was agreed upon by the faculty that best practices mandate that sites be established a new for each semester and maintained as an archive after that particular semester is concluded. It is essentially a terrible idea to simply keep a single top-level public_html folder that gets modified continuously semester after semester after semester.
Before downloading a clean copy of the templates, it would be a very good idea to familiarize yourself with the online posted version of templates. In all likelihood, that's where you're reading this note at the moment. Become familiar with what's available for doing the download.
If you're feeling brave, jump right in and grab the most recent version from the subversion repository. This has the huge advantage that it will be the most up-to-date version including minor bug fixes that are often made during the course of a given semester. That said, you may want to ask before pulling from the repository as there are certainly moments and you might get something that's half-baked.
The very careful and safer alternative is to grab the zip file. However, you can look at the date which will be encoded in the actual name of the file to get some specific idea of when the file was created engage how much may have changed.
Notice that no matter what else you do, it is a really good idea first to download a fresh copy of the complete set of templates. Further, put these somewhere safe and off to the side before you contemplate what to do to the course website itself. Then, if this is a brand-new installation or major update it makes sense to bring over all the files (there aren't that many of them) that live at the very root of CS Roo as well as the term specific site folder. Conversely, if the public_html root directory is considered to be in good shape, you may simply want to bring over the term specific folders contents.
Here's a bit of a hint, it is easy in modern browsers to display the source for pages. Therefore, even if one is starting with a new set of templates in a new semester, often grabbing the actual contents of the page, for example the syllabus page, and simply doing a copy from the source and paste into the new syllabus page source from the CS Roo templates is straightforward. This in fact the approach I usually take.
Here's a truly terrible idea. Do not try to mix and match files from one version of CS Roo with those of a previous version. the chances of introducing some kind of a conflict due to changes in the PHP superstructure for the course are very high and I, for one, would never want to try to disentangle the resulting mess.
The order of the items shown here is not entirely critical. What is essential is that the configuration page be customized as well as the course description and the other items summarized on the slide. Keep in mind that the show after this one goes through the structure of individual pages in some detail and is well worth reviewing before you start to edit individual pages. Also, the progress page, which is arguably the most complex and most important of the major pages provided by the site, has an entire session of its own devoted to explaining how it works and ways of editing the corresponding spreadsheet that drives the progress page. What you will learn from this particular show is simply how to create initial default page with proper dates based on your specifying the date of the Sunday of the first week of the term in which the course is being taught.
Keep in mind that the remainder of this particular show provides additional detail on the items summarized here.
There are very few exceptions to the general rule that actual content is entered as plain HTML inside each particular page that is supported by the templates. Similarly, as will be discussed more in the next session, you can always create a new page and begin inserting HTML into the contents area of that page.The course description is one of the two exceptions to this rule. The description so important that it is typically repeated both on the course homepage and at the start course syllabus. This convention was showing up so often that it has been enshrined in the structure of CS Roo. Therefore, the actual description of the course lives in an external file that should be edited to fit the needs of each particular course. That description will then automatically appear on both the homepage for the course as well as at the top of the syllabus.
The configuration page is absolutely designed to be edited and customized for each new course. You can learn a little bit about how objects are defined and instantiated in the language PHP by simply seeing the two examples present in this file. The structure is essentially self evident, and you will notice that there are two objects globally available to every page that is loaded that contain much of the basic information required to customize a site.
This includes basic information about who is teaching the course, when and where lectures meet, etc. Notice also that this basic information is used to generate the presentation of the course logistics on both the course homepage and also at the top of the course syllabus. Entering this information once the configuration file means it will appear consistently on both of those two pages.
It's a good idea to simply familiarize yourself with this file and every entry in the two objects to find there. For the most part, each and every item is accompanied by a small bit of documentation and that hopefully will enlighten as to the purpose of that particular bit of information.
One of the most common additional customizations that instructors have to make involves adding additional GTA's and recitations. All this is somewhat more involved, since it requires the writing of additional code, the task can be relatively easily performed by modeling new entries on the ones already present and then doing likewise with the code that generates the output. If this seems daunting, this is one of those areas where it's wise to ask someone in working with CS Roo for a semester or two.
Being essentially the heart of the public course website, the progress page draws on a great deal of data that must be kept coordinated with individual days on which the course meets and organized by week. Further, one of the first things that spurred the development of CS Roo was a need to rapidly shift entire blocks of planned instruction either forward or backward in time. Doing this in a traditional calendar is essentially impossible and hence every time the schedule changes the process of adjusting traditional calendars meant great pain and suffering.
Therefore, the, separated variable spreadsheet that is the very basis for all of the information presented on the progress page is the backbone of course organization. The first couple of columns should not be edited by hand. They include such wonderful things as the date of each session as measured by UNIX. What is easy to do in a program such as Microsoft Excel, is to grab blocks of cells after these initial key columns and shift them en masse up or down. This is how real-time adjustments can be made to the course plan during the semester.
Because the software that reads the spreadsheet is not terribly patient with mistakes such as missing columns. It is best to let CS Roo auto generate an initial spreadsheet in which all of the correct dates etc. will be filled in. All that is required of you is to modify the configuration file in such a way that CS Roo can determine the dates and also whether the class meets three times a week (WMF) or twice a week (TueThur).
And here's something that you may notice as you use CS Roo. The PHP code that displays the progress page actually pays attention to the current date and color codes future weeks in green, past weeks in red, and the current week in yellow.
Up until the release of version 3 in January 2016, it was necessary to first establish usernames and logins and even more so to be able to login as an administrator before this auto generation capability could be invoked. Few aspects of the design of CS Roo caused more problems. While establishing a set of designated users is important, so important that there's an entire section devoted to explaining how to do it, it should not be required to establish the first spreadsheet. Now, all that's required, is that the administrators special key be entered. This key is nothing more than text that can be found by looking into the config.php file. Before you worry excessively about the risk of people pushing this button and messing up the site. All that can happen is a new blank spreadsheet will be created in the directory ztools. The only way this spreadsheet will become the master that drives the website is when someone with direct access to the file system on which the site is being served moves the spreadsheet up one level into the semester root for the course.
And starting with version 3, there are also more helpful little warning messages if the progress page is unable to find the spreadsheet. Last but not least, it is highly recommended that you customize the name of the spreadsheet to reflect the course and the semester: this is also done in the config.php file.
As just mentioned, with Version 3 CS Roo will give some helpful warnings when the spreadsheet is not found.
A truly disproportionate amount of time maintaining websites directly through filesystems involves mistakes in file permissions. Here are a couple of really basic things to keep in mind. On almost all Apache servers, the server itself runs either as root - somewhat scary - or as its own process. What is very rare, is for the server to run as the user who owns the directory in which the materials being maintained. Therefore, it becomes almost reflex to make all files world readable that live under public_html.
At almost the opposite extreme, some instructors make very careful use of limited file access to "protect" pages that otherwise live on the public Web server. Indeed, there are many situations where this makes a great deal of sense. You will read later on that some care is taken to make sure that no one can read the list of designated users for a site from a browser.
Just in case you thought this matter of file permissions wasn't tricky enough, remember that in the computer science department we have an arcane convention of storing web files on a wonderfully global shared file system in which there are hundreds of users including all of our undergraduate students. Were we starting from scratch, we would never ever come up with an architecture that placed our web files in a common filesystem is all our students - but that is what we have today and the cost of altering it is extreme at this point.
In part because of the shared file system, our computer science department runs a rather marvelous little plug-in on top of its PHP processor that runs PHP pages as the owner of the website root directory instead of as the server. As a consequence, it is totally fine and indeed good practice within the department to restrict read permission on PHP files to only the user. Alas, when that site gets moved to a development server such as your laptop, this plug-in is not operative and it will become necessary to make files world readable.
Also, there is functionality associated with CS Roo that creates and writes files. You already seen one of these when it was explained that a brand-new progress spreadsheet could be written into the ztools folder. Perhaps the most critical thing to keep in mind is that you will want to pay close attention to UNIX file permissions and if you're having trouble it is likely the trouble is related to permission settings and you may want to ask for help.
Many of the CS courses already have established and distinctive logos. When this is the case, there isn't much to do, just customize the site to use the existing logo image.
More generally, do not underestimate the importance of logos. We've all experienced the confusion that quickly arises when we are moving between websites and we unable to instantly and without thought keep our place and be assured that the site where visiting is indeed the site we intended to visit. That is why we have logos. Branding is a nice side effect.
There is an entire folder of pre-made logos for essentially any computer science course offered by CSU. One can always fall back on using these. That said, there are talented people in most computer science departments - perhaps including yourself - who could with an hour to draw up a very pleasing logo. And if you think that does not apply to you, ask around the department to see if someone else might be willing to offer a hand.
The PHP code that generates the banner at the top of every webpage is somewhat involved. More will be said about this banner and in particular the navigation bar in the next overview section of CS Roo. For the moment, there's a very specific tiny but critical detail. When you select a logo image you need to keep in mind what size that logo image should be. The logo used by CS Roo up until January 2016 was 250 pixels wide and 130 pixels high. The new logo created in January 2016 is the same width but 140 pixels high. You might think that such a change is accidental, it is not. The extra 10 pixels gives just a little bit more height to the banner and a little more space for the title and subtitles.
Either size would be an excellent choice for a different course logo. Do keep in mind that whatever size you select, the height must be sufficient to fill the space - or at least it will look somewhat odd if it is not - and further as you make the logo taller you will end up stretching the height of the entire banner.