This presentation is new for 2016 and fills a major hole. Touching first on a bit of the philosophy behind CS Roo being a template system rather than a full on CMS, the majority of this session works through an example ‘hello world’ page in order to introduce the major components that underlie a CS Roo page and how it functions.
The punchline is that someone simply using the templates should be able to treat all of the include files and other material at the top and bottom of a page template as black magic and simply make sure that a few critical values are changed if moving a page up or down a directory hierarchy. Of course, that simplified model will never really stand up to the needs of someone who wants to begin baking more serious adjustments to the look and feel of the site.
Generally speaking, the web has already transitioned almost entirely to idiosyncratic and complex content management systems (CMS). At the moment, one of the most widely used is WordPress. These tools are fantastic if they accomplish what you want and you can afford the cost of learning how their specifics behave. Going one step further, if one is not comfortable reading code and somewhat familiar with HTML, CSS, and PHP then probably a CMS is the only real option.
However, designing public facing websites for computer scientists and by computer scientists represents a somewhat unusual situation. I would argue that we as a group are somewhat less patient with repeatedly entering information by clicking buttons in web interfaces. And on the flipside, we are probably a lot more comfortable using automation and editing tools to create and manipulate digital content. Therefore, CS Roo is tailored to fit the very specific niche that arises when very computer literate individuals seek to create, replicate, and modify web content associated with a course.
Before he fully became a legend, Steve Jobs often came in for criticism by the technically literate with statements such as ”He is more concerned with fashion then function." History for the moment has more or less quieted such criticism, but the broader issue of how a piece of software looks and feels to use remains much more important than some are willing to admit. For example, websites need logos - more on that particular point in a few slides.
More generally, university courses need an online presence and that recognizable, predictable, relatively easy to use, and ultimately able to provide critical functionality is essential. CS Roo is one solid product that embodies a particular view of what a public facing course website ought to be. Whether it is deemed attractive is up to individuals to decide. Fashion, as it relates to appearance on the web, is of course itself a moving target. At a minimum, what can be said about CS Roo is that it establishes about six pages that together represent critical information and functionality needed by students. These are, as you have already seen by scanning this example site: the homepage, the syllabus, the progress page, etc.
Internally for those of us developing websites, one of the great challenges of the past five years has been responsive design in creating sites that don't fall apart when viewed on mobile devices. The current CS Roo templates use the Google bootstrap library to provide a few critical adaptations for mobile displays. Indeed, it's less about mobile displays than it is about the available width to display a page. You can play a simple game on your own browser. If you shrink the width of this page sufficiently you will notice that the top and bottom of the page become greatly simplified with the main navigation menu displayed in a manner now well-recognized on mobile responsive sites.
Everything shown on this page with the exception of the words "hello world" is automatically generated by PHP code that is included at the start and end of every CS Roo page. It would be lovely to suggest that a new user of these templates need never concern themselves with any of this material except for making sure the lines of code are copied dutifully and perfectly into each new page they create. As the following introduction will suggest, that is in the extreme naïve, but in practice relatively little should be tampered with when using the CS Roo templates and those few things that should be edited are explained in this talk.
Here's the complete source for the page displayed in the previous slide. In keeping with the philosophy that computer scientists learn from examples, and learn quickly, notice the red text showing precisely where the PHP interpreter is enabled and disabled. This is actually one of the most appealing aspects of using PHP for web development. A page may turn on and turn off the interpreter as many times as it likes and when the interpreter is turned off what should be written is good old-fashioned HTML.
And one more small thing, most of you are already very familiar with the ‘div’ tag in HTML. Notice that all of the page specific content that should be entered into a new page lies within the scope of the "contents" division.
Notice that the second line is highlighted. This is one of those few places in the code that you may need to make a change. More about that on the next slide.
It is hard to get very far into the design of a consistent website before having to face off squarely with the issue of relative versus absolute addressing in links. Put simply, no well-designed self consistent website should ever use an absolute link to another resource that is supplied as part of the same site. But this creates a problem - what to do when loading common content from libraries into pages that may reside at different directory levels within the site?
CS Roo has a relatively straightforward fix for this problem. There is a variable defined on the second line of the file that indicates the depth of the folder in which this particular page resides. If page resides at the semester root of the site, the folder with the main index.php file, then page level should be zero. One sub-folder down, page level should equal one, etc.
The previous Quickstart session already discussed the config.php file. Here we see that this file is the first of several major files to be included into every CS Roo page.
This is as good a time as any to bring up a nasty little detail about how websites are sent from the server to the client. Namely, first a header is sent and then the body. Why this is even worth mentioning is one of the fastest ways to break features of CS Roo is to mistakenly generate actual text output prior to completion of sending the header information to the client. In a nutshell, recognize that the early PHP files that are loaded must never be edited in such a way as to echo text to the page; if you do this chaos will ensue.
Changing the page level variable is the first example of how a template page must be modified in order to work properly in a subfolder. A more complete example involves the template for the first assignment in the course. Notice the URL at the top of the screen shot and observe that assignment pages live in a subfolder. The next slide will show what accommodations have to be made in order for all of this to work properly.
Once you get the hang of it, correctly modifying a page to operate in a subfolder is trivial. However, most of us forget to add the “../“ in at least one of the relative addresses associated with one of the include files. It is not a hard error to recognize: when you view the resulting page it's going to lack critical information and failed to display perhaps the top banner or perhaps the footer depending on what you failed to modify correctly.
Page titles are an example of information sent from the server to the client in the header and CS Roo expects to have a title established very early on: in this example online four. By convention, it is highly recommended that titles be short and constructed by concatenating the designation of the course with a page specific title. Notice here a little bit more PHP to learn, the period is the string concatenation character in PHP.
Not much to say at this point about the all functions library. One should be fairly far advanced before starting to consider making changes and additions to this library. You will know you've reached that point when you've opened up the library and started to scan it with the intention of changing some aspect of the templates.
As to the terribly bad pun connected with the folder name where basic support for CS Roo resides, yes it is pronounced Z Tools and it is where Z tools are kept.
CS Roo has support for designating a set of users and having those users authenticate with a password and log on to the site. If you stop to think about it for a moment, that means that CS Roo is customizing its session to individual users. That is done in PHP by starting a named session and that operation is the first operation performed in the common headstart file. It may be informative to open up and look at this file. It is in this file that the basic HTML comment defining the version of CS Roo appears. If you seek to introduce additional meta-tags this would be the file to edit.
Prior to introducing support for responsive design the contents of the navigation file were easier to read. Alas, they were also not well suited to the modern web. This caveat is by way of justifying the need to pay attention to several steps that are involved in defining new elements of the navigation. If you seek to make significant changes to the navigation bar you may want to read up on the Bootstrap library and/or talk to someone with more experience.
If, as is likely, you want to do something simpler like perhaps change the text that appears on a particular navigation element, it is probably easy to spot that text in the file that creates that particular element and change the text. Similarly, if one is simply trying to remove something from navigation that two should be straightforward: delete the code that creates that particular element.
In the PHP code used to create the navigation bar, there's a well-defined block of code that sets up variables that represents the relative paths to common destinations as well as common resources. Notice that it is here that the relative path to both the course and CSU logos are defined. Notice also that the PHP variable indicating the relative path is pre-appended to every filename. Just in case you're wondering, this relative path variable is what's established automatically using the page level indicated at the top of the file.
Now the "easy part". If you are planning to modify a class website using CS Roo, the it goes without saying your comfortable writing HTML code. Your code goes in place of the hello world paragraph.
Just a little bit of philosophy to go along with this apparently simplistic statement. While it is all well and good to use complex programming tools to support reused and fairly complicated webpage components, it's often extremely frustrating to see how some semi-automated tools for web development make but should be easy hard. Therefore, notice that the decision to keep page specific content as simple as possible, and whenever possible in vanilla HTML form, is intentional and desirable.
The only page provided by CS Roo that departs from the rule of keeping page content in simple HTML form is the progress page. there are great many reasons for this decision, and they should become clear when reviewing the next session on how the progress page operates.