Page 1: Localstore: How Workbooks (and Webpages) Save Information

The goal of this page is to explain the web browser’s localstore mechanism and how it is used by the workbooks. This is important because it will help you understand how the workbooks operate, and why certain things will “break” sometimes - which will help you avoid losing your work. You won’t actually use the localstore yourself - but you should be aware of it in order to use the workbooks effectively.

When you see an html form element like:

or or

the workbook will usually save the information for when you come back to the page. This also allows you to upload this information when you checkpoint or submit your work.

Completing the type-in boxes is a required part of the workbooks (and, therefore, class). They are less directly a part of “grading” because they are experimental: we may check what you turn in with them, but we understand that they are an imperfect record of your work.

What you “Need” to know (short version)

1. Web form elements in workbooks (like checkboxes, selectors, and type-ins) are set to save their content to the browser’s internal storage mechanism.
2. Because of web browser security, this storage is tied to the specific domain. For example, https://localhost:5500 (Live Server’s default) is different from https://localhost:8080 (Node’s default). If you store answers for one site, you won’t see them for a different one. Even a different port number (e.g., https://localhost:5501) is different.
3. To get it “out” of the web browser, we have added buttons that save the contents of the local store to a file wb_localstore_save.json. The workbook expects this file to be in the root of the workbook. If you save, the browser might put it someplace else (like the Downloads directory) - you need to manually copy it into place.
4. We have also included buttons that write this content to a web server so that we have another mechanism to know what students are doing. This only happens when you use a Checkpoint or Submit button (which exist on some pages).
5. We provide various buttons that help you see what is in the local store and what will be uploaded to the server.
6. We require you to provide the wb_localstore_save.json file in your workbook (when you commit and push it to GitHub) for grading as well as to upload copies as Checkpoints and for the final Submit.
7. It is essential that you have your NetID in the type-in box so it is included in your information. Otherwise, we have no way to match you to your data.
8. The main “graded work” of the workbook is in the files that get pushed to GitHub.
9. The interface for the localstore is on different pages throughout the workbook. But you can always find a link to a Local Storage Interface (Local Storage Interface) at the bottom of the sidebar (on the right).

Try it now to start with…

First, make sure that your NetID is correct. This is essential! This is the only way we know who you are (and we need to do that in order to give you credit).

Notice that these copied the values that you put in on the previous page (if you did that). And that they persist (they come back if you restart the web browser).

Here are two other form elements to testing things with:

You should see that if you navigate away from this page and come back, things are put back for you (there is magic behind the scenes).

Since you just changed those (and haven’t updated the file in the workbook), the contents of the browser localstore and the file will be different. We have a handy widget that can help with this.

Start with “show differences” - this will create a table in the console (so you will need to open up the browser console to see it). If you aren’t familiar with the browser’s console, now is a good time to find it. Look for “View/Developer/JavaScript Console” in Chrome - it’s CMD-Option-J on a Mac, or Ctrl-Shift-J on Windows. It’s different in Firefox.

To write this data to the json file, press the “Write JSON” button. When pressed, this button puts a json file named wb_localstore_save.json somewhere - just probably not where you wanted it. Copy it to your workbook directory (over-writing the version of the file that is already there).

Now, if you press “Check Again” you should see that “The JSON is up to date.”

This “File Status” widget will appear in strategic places in the workbook. I recommend saving the contents regularly, just in case something goes wrong. And you will need to write it out before submitting your workbook.

If you want to know what information is put into the file you can press:

Workbook LocalStore to Console

Now, you want to send us a “checkpoint” of this information (you will need to do this from time to time).

You can do this more than once for each work book.

At the end of the workbook there is a very similar Submit button. This works the same, except that it writes it in a different way that tells us that your workbook is ready to be graded. You should only use that button once, when you are done with the workbook and want to hand it in for grading. Before pressing that button, you should: save the JSON file (and put it in the workbook), commit the repository, and push the repository to GitHub. We’ll remind you about that when the time comes.

Moving Servers

If you move to a different computer, or a different webbrowser, or a different local web server (even on the same computer), your localstore does not move with you.

The only way to “move it” is to save it (from the first place you were working) and load it (using the load button in a file status block).

This is one of the things that can go wrong. For this reason, we recommend that you save your work periodically.

What can go wrong…

The use of local storage in the browser is somewhat fragile.

The biggest potential problem: for security reasons, the web pages of the workbook only have access to the local store for the same “domain”. This means that if you change the URL in any way, the browser will think you are in a different domain and will not allow the page in the “new” domain to access the old information.

Live server (for example) usually uses http://127.0.0.1:5500/. Note that this is http protocol (not https), that the host is 127.0.0.1 (not localhost), and that the port is 5500 (not some other number). If you have two live servers running, it might pick a different number. If you switch to a different server it will pick a different number.

Some symptoms:

1. You get a warning “No previous visit to this page. Either you haven’t been here, you’ve changed server, or you’ve erased your local store.”
2. Form elements that you filled in aren’t filled in any more.
3. You submitted a checkpoint, but it still says “not submitted (according to local storage)”

If these things happen to you, you can go back to the server that you had used and everything should still be there.

If you want to (or are forced to) switch servers, you can write the storage to a file using the old server and “load from file” on the new server. But you can only do this if you have saved while you still had access to the old server.

So… we recommend that you save your JSON work periodically, that way if something goes wrong you can recover.

If you want to understand how this works you can read the next section, otherwise, go to Next: Page  2 - How Workbooks Work

Local Server Check

You should always “run” the web pages served by a local server. See the Tools for 559 page for more information. Using a local server requires both running the server and having the web browser look at the server. If you don’t use a local server (and instead you just open the file in the web browser), problems can happen.

We have no way to check if you are using a local server. Some of the web pages will break in weird ways. Look at the URL bar in your browser: if this page says “http://127.0.0.1:5500/” or “http://localhost:5500/” or something similar, you are using a local server. If the URL starts with “file:” or something like that, you are not using a local server. The workbook should give you a warning if you try to run from a file.

Make sure that you know how to use a local server. Re-read the Tools for 559 page, and ask for help, if you need it.

Optional Section: Under the hood (why this happens)

When a web page is loaded, the browser sometimes resets the form elements. It almost always does this if you restart the browser, or navigate to a different page. If you simply reload the page, sometimes it recovers them, and sometimes it doesn’t

Here’s an example. This is just a plain type-in box.

In contrast, being able to remember something after a hard reload (or going away and coming back) is generally a feature. This box will do that…

Fill in those boxes, and then either hard reload the page, or go to another page and come back. The memory works even if you quit the web browser and then return to the page later.

How we implement this

To save the value of something on a web page, we can write a value into the browser’s persistent database, called the localstore. The localstore is a key/value storage that the browser keeps. Web pages can write to it.

For the form elements, workbook webpages add a little bit of “magic” such that every time the value in a form element changes, the value is saved into the local storage. A different piece of magic happens when the web page is loaded - it copies the values from the local store to the corresponding form elements.

If you’re curious, you can see the code in js/localstore.js . When the web page is loaded the browser looks at all form elements. It checks to see if there is a value for that element in the localstore. It also sets up a handler so that whenever the element changes, its value gets written to the store.

Now on to Next: Page  2 - How Workbooks Work.