Page 2: How Workbooks Work

This page will explain a bit about how the workbooks are organized so you will have a better sense of what to do.

As you’ve probably already figured out, a Workbook is a miniature web site that is a mixture of assignments, tutorials, demonstrations, and reading material. Most of the work in class is within these workbooks. We’ll have a workbook for each module.

If you’re seeing this page, you’ve been able to start a web server on your own computer to serve the workbook pages, and have gotten through at least a few pages.

The workbook process (you’ve already done steps 1-3):

1. You use the special GitHub classroom link to make yourself a respository on GitHub that is your own personal copy of the workbook.
2. You clone this repository to your computer.
3. You open the workbook in Visual Studio Code We recommend Visual Studio Code. If you are experienced enough to have a different opinion, that’s OK. and start Live Server We strongly recommend Live Server. . (orsomething else If you use a different web server, you need to make sure you are consistent in the domain it uses so that the localstore works to save your form elements.) )
4. You do the “work” of the workbook. That means reading, experimenting with demonstrations, filling in web form elements (type-in boxes, checkboxes, etc.), and completing “boxes” by editing files in the for_students directory.
5. Periodically, while doing the work (#4), you should “checkpoint” it. For the web forms, you should write out the JSON file and Submit the checkpoint (see Page  1  (Localstore: How Workbooks (and Webpages) Save Information) for details). For the changes to files, you should use GIT to commit and push the repository back to GitHub.
6. When you are done, you go to the Page  25  (Last Page (rubric)) where you are instructed on how to finalize the workbook and submit it. This is similar to making a checkpoint. There’s a check

Working on Workbooks

Workbooks consist of a series of pages. There is always an “index” page. This is where you start. Then there is a series of “regular” pages for you to read. These will be numbered, and they will be linked together (so each one will lead to the next). You can see the list of pages in the “navigation” sidebar (which should be in the upper right corner). These pages will be in the docs directory of the workbook. You are welcome to look at the html for these files, but you generally don’t have to.

The workbook pages will contain “boxes”. These boxes contain examples that you should look at. Some of them you will just need to read (you will read code in order to learn how it works). Often, you will be asked to change the contents of these boxes. The contents of the boxes will be in the for_students directory. You should avoid changing files that are outside of the for_students directory. If you change a file (in the for_students directory) you need to commit these changes and push them back to GitHub for us to see the changes (see the Git and GitHub in CS559 page if you don’t understand commit and push).

Sometimes, we will ask you to add files to a workbook. When you add a file, put it into the for_students directory (or a subdirectory of it). Don’t forget to use git add to add the file to the repository so you can commit and push it to GitHub. You will need to add files for this workbook for one of the boxes.

You should work through the pages and their boxes in order.

And when you’re done, don’t forget to commit your work and push it back to the GitHub repo that GitHub classroom made for you!

Repository Organization

All workbooks have the same structure.

• The repository directory (root) is where you should start the web server. Use this directory for “Open Folder” in Visual Studio Code.
• The index.html file in the root is the main starting point. It’s where you should start your web browser.
• The docs directory has the pages of the workbook. Students shouldn’t need to edit these files. Students can look at things in this directory, but shouldn’t need to. These pages access other, easier to read pages in the for_students directory.
• The for_students directory is the place where the files students work on go. Students should avoid editing files outside of this directory, and should only add files in this directory. The docs pages will provide pointers and instructions.
• The libs directory contains libraries that the various programs use. Students shouldn’t need to change anything in this directory, but might need to look at it to learn how to use it from their programs (which will go into for_students).
• The css and js folders have files used to make the workbook pages work - nothing students need to look at.

Boxes

The actual web page you are looking at is the file index.html in the 02 directory inside of the docs directory in the workbook. You might want to try to find the file to see where it is. The reason for the funny naming is that this page was automatically generated using a static web site generator (it’s Hugo if you’re curious). After this page, it won’t matter since you will rarely have to look in the docs directory.

The docs directory has the workbook pages that you read. When you actually need to look at the html all of the text gets in the way - you want to get rid to a simple web page that you can work on. For this reason, we make super-simple web pages for the actual things you will work on and then “embed” them within these more complex pages. Here is an example:

What you see is a box with some very simple HTML in it. It’s a small web page we’ve made and then placed on this bigger web page ( 02/index.html). You can open it by itself directly with this link: 01-02-01.html.

We call these little web pages that are inside boxes on bigger web pages “boxes” on workbooks. Boxes are where you do your work. All boxes are named with 3 numbers: the workbook, the page, and the box on the page. So this first box is 01-02-01.html - the first workbook, the page number, the number of the box on the page.

The boxes, and other files that you will want to look at are in the for_students directory. If you look in the workbook, you’ll see that directory. If you look in that directory you see the file 01-02-01.html.

If you want a quick way to find the file, use the “Go To File” command in Visual Studio Code (it’s CMD-P on a Mac).

Note that you can’t see the HTML for the contents of the box if you use the “view source” command in your web browser (it’s CTRL-U for Firefox and Chrome on windows) while viewing the web page with the instructional text. Viewing the source will show you this web page (what you are reading outside the box). What you’ll see on this web page is an iframe (which is the web element that embeds another web page). If you look you’ll also see some funny looking JavaScript code that resizes the iframe (so that Firefox and Chrome behave the same way). This is another reason why we don’t recommend looking at the sources to the docs pages. You can open the box web page directly, in which case view source looks just fine. This will be important later for when you want to debug your work - since you want to look at one box at a time.

In addition to the web page, the box as a few other “features” that are important:

• The name of the box (in bold)
• A checkbox - so you can mark that you’ve completed the box
• The type of the box - which says what you should do with it. This one says rubric - which means there are specific things listed.
• A list (of links) to the files used in the box. The html link can be particularly useful as it opens the page in a tab by itself so you can focus on it (for example, to view source or run the debugger).
• The box content (the web page itself)
• Below the black box with the web page is a box with a rubric. This is a list of things that you need to do in the box. Each one has a checkbox so you can check it off when you finished it. Note: there might be things to do in the box (described in the text) that are not rubric elements.

Speaking of work, now we actually try to have you do something. To confirm that you are able to find the right file to edit, please:

• Change the line that says “The student should change this line” to “NAME has changed this line” (where NAME is your name).
• Also change the NetID line to have your actual University NetID rather than “Change This”. This isn’t rocket science, but it’s the thing you do with workbooks: edit the files in the for_students directory.

You should know that there is work to do in the box from the rubric. Some boxes may be of type view (which means we want you to look at what is in them, and maybe experiment with them if they are interactive). Other boxes might be of type examine if we want you to look at the code for the box. Edit boxes are ones that we expect you to change based on the instructions in the text, while rubric boxes have specific instructions in the rubric below the box.

After you change 01-02-01.html, you may need to reload the page in order to see your changes. If you are using the Visual Studio Code Live Server (which we strongly recommend, see Visual Studio Code (VSCode) for CS559), this should be automatically reloaded for you.

Congratulations! You’ve completed your first workbook task. If you look at the site rubric on the last page of the workbook, you would have seen that you completed an item for changing box 01-02-01 - but only if you checked the checkbox. Similarly, if you check the checkbox for the box, you’ll see the box is marked complete on the box list on the last page.

Keeping Track of Your Work

Notice that the checkboxes for boxes and rubric items are manual. They are a useful for you to keep track of what you have, and have not yet, done. You can check what has been checked off on the last page. These checks are part of localstorage - so they are part of the JSON that gets written to a file (so they can be restored if you save and re-load into a different browser).

If you want to look at what has happened, you can go to the Local Storage Interface (Local Storage Interface) (link is always on the sidebar). You can see the list of boxes and rubric items and it shows what has been checked off.

The checks are also uploaded when you make a checkpoint or submission of your JSON. This means we know what you think you’ve done. Usually, we’ll look at your actual work in the boxes (not just whether you checked the check marks). But, sometimes, we might use this to see if you think you’ve done it.

Please check the checkboxes for what you do, and not for what you don’t do. It will make things easier for everyone.

Form Elements

We use the term box for something specific: an embedded web page that is an activity on a workbook page. This term is historical: when we first started making workbooks (in 2019), boxes were the only mechanism for putting things on the page. All demonstrations and questions were done this way.

Now, boxes are easier to identify: they have the rounded rectangle with the information at top - and the rubric (if they have one) at the bottom.

Workbook pages also can have form elements - these are “type-in boxes” (yes, I see that we have a name collision here). These are not boxes, but are still things you need to fill in.

We will use boxes to ask you smaller questions. They are still required (so it is important that you make sure they are filled correctly and saved/checkpointed/submitted).

The most essential (and special) boxes are the NetID, GitHub and Attribution boxes - these are all shown on the last page near the submission button. You cannot submit your workbook if these are not filled in (since we can’t grade things without this information).

Other boxes are required - you should fill them in, and take them seriously (since they are usually important). Unfortunately, we have no way to help you track what form elements you’ve completed. (like checking off checkboxes for boxes and rubrics)

We do not expect to use the form elements as a major part of grading. We would like you to checkpoint, save, and submit your localstore so we can see what you do on these boxes. The main parts of grading are the code boxes.

Live Code Boxes

In some case, we may have type-in boxes that actually show JavaScript code. For example…

Note that you can edit this one (try changing the “#F00” to “#0F0” to make the square green). We’ll explain this code (including the hex codes for colors) later in the workbook.

We only use this for very simple demonstrations to let you tinker. We much prefer to put demos into boxes so you can edit the files in your IDE and use Git to track your changes. This is why for the real “grading” we will have you write programs as separate files.

OK, enough about workbook mechanics. Let’s talk about making web pages…

Next: Page  3 - HTML and CS559