JSON (JavaScript Object Notation) and local storage are two powerful tools for any web developer. JSON is a way to represent objects as strings. JSON is widely implemented accros many programming languages and protocols, so it is extremely useful to learn how to convert objects to JSON and back. Local storage is a feature in browsers that allows a website to store data directly within a user's browser. Local storage accepts data in the format of a string, so using JSON with local storage is a great way to store user-specific data without taking up any space on your own web server. It's also a great option if you want to serve web pages that remember data without having a server-side database. This tutorial will walk you through creating a basic web page that stores, retrieves, and displays some very simple JSON objects.
Create a file, and name it something like localStorage.html. This file will contain a simple web page layout/user interface. This webpage only needs to contain a couple forms through which you can enter some basic data. Copy this HTML content into your file:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>local storage</title>
</head>
<body>
<h3>Enter something to save to local storage</h3>
<form onsubmit="storeItem(event)">
<label for="name">Name</label>
<input id="name" type="text" name="name"/> <br/>
<label for="content">Content</label>
<input id="content" type="text" name="content"/> <br/>
<button type="submit">save</button>
</form>
<h3>Retrieve something from local storage</h3>
<form onsubmit="getItem(event)">
<label for="get">Name of content to retrieve</label> <br/>
<input id="get" type="text" name="name"/> <br/>
<button type="submit">get content</button>
</form>
<p id="storage_item"></p>
<script src="script.js"></script>
</body>
</html>
This page contains 2 forms. The first form is to store something in local storage. It has inputs for the name of what you want to store, and the content to store. The second form has an input for a name, to then retrieve an item from local storage of that name. Open this file in your browser (in your file explorer, right click->open with then select your regular browser like Chrome, Firefox, etc.).
Create another file in the same folder as the html file you just created. Name it script.js. This is the file we will use to write functions that interact with local storage, and convert objects to JSON and back.
Create Functions named storeItem and getItem in your script.js file. Each of these functions should take in one parameter. This parameter is called the 'event' and is passed automatically by HTML forms when they call a JavaScript function on submission. This event parameter is how we can get the data that was entered into the forms in our HTML page and use them in our JavaScript functions.
Your functions should look like this: function storeItem(event) {} (with another function for getItem). These functions are called by the forms in our HTML page, and as you can probably tell are used to store and get an item in local storage.
Add code to the storeItem function. This function will receive the data entered into the fields of the first form in the HTML page, turn that form data into an object, convert that object into a JSON string, and store it in local storage. Here is some code you can copy into your function. Take time to read through it and understand what each line is doing.
// Prevents the page from reloading itself upon submission of the form
event.preventDefault();
// Gets the data the user entered into the form
let formData = new FormData(event.currentTarget);
// Converts the form data into a JavaScript object
let data = Object.fromEntries(formData);
// Takes the object and turns it into a JSON string
let jsonData = JSON.stringify(data);
// Creates or updates an entry in local storage using the object name as the key and JSON string as the value
localStorage.setItem(data.name, jsonData);
Note: JavaScript provides many built in functions and classes (object types) that do a lot of work for us. Here we are using the built in features of FormData, Object.fromEntries, JSON.stringify, and localStorage.setItem. It is important to understand what these classes and functions do, but don't worry too much right now about how they function behind the scenes.
Test the code by opening your HTML page in your browser. Enter something into the Name and Content fields of the first form, and click the save button. Then, open up developer tools by right clicking on your page to bring up the options menu, and clicking "Inspect". Find the Application tab and open it. On the left side of the Application tab, under Storage, expand Local storage and click on the first option (it should say file://). You should be able to see the name and content that you entered into your form there.
Debugging: If this doesn't seem to be working, double check that the file containing your JavaScript functions is named exactly script.js and is in the same folder as your HTML file. The <script src="script.js"> tag in your HTML tells the browser to look for a file named script.js in the same folder and load it. If your file is named even something like scripts.js (plural) then your browser won't load it, because the HTML told it to look for script.js.
An object stored in local storage
Add code to the getItem function. This function essentially needs to do in reverse what the storeItem function did. Instead of taking an object and turning it into a string to store in local storage, it will get a string from local storage, and turn it into an object. From there, we can do whatever we want with it. Here's an example function that displays the name and contents of an item back onto the HTML page. Paste this into your getItem function. As before, take some time to read through and understand what each line of code is doing.
// Prevents the page from reloading itself upon submission of the form
event.preventDefault();
// Gets the item name the user is trying to retrieve
let formData = new FormData(event.currentTarget);
// Converts form data into an object
let data = Object.fromEntries(formData);
// retrieves the local storage item of the given name
let jsonData = localStorage.getItem(data.name);
// Turns the entry back from a string into an object
let item = JSON.parse(jsonData);
// Outputs the object as an element on the page
let element = document.getElementById("storage_item");
element.innerText = "Name: " + item.name + "\nContent: " + item.content;
Note: this function is very basic. It doesn't contain any checks for whether the item you're looking for actually exists before trying to get and display it, so it will just throw an error and stop if you try to get something from local storage that doesn't exist. After you finish this walkthrough, consider learning how to improve this code to display an error message on the web page if the item you're looking for doesn't exist.
Test the code by refreshing your HTML page in your browser. Enter the name of something you previously stored in local storage into the Name field and click "get content" (note that the name you enter is case sensitive). You should see the name and content of the item that was stored in local storage appear underneath the form.
An object retrieved from local storage
Experiment a little by closing your HTML page and reopening it in your browser (right click on the file->open with). Navigate back to the local storage (Inspect->Application tab->Storage->file://). Note that everything you already put in local storage remained even after you closed the page and opened it again.
Now try opening your HTML page in a different browser if you have one. In the new browser, take another look at the local storage. Note that it is empty. This is because each instance of local storage is browser specific. Chrome can't see items stored in local storage on Edge or Firefox, and vice versa. This is an important limitation to understand. Local storage can be very useful to quickly store user specific data without any need to involve a web server, but it should not be relied upon for important data that a user should always be able to access.
Here are some links to resources that will help you dive a little deeper into the topics of JSON and local storage
- What is JSON? - W3 Schools article covering syntax and usage of JSON. Does a great job at showing how a string can be converted into an object in JavaScript.
- History of JSON - This article gives a history of JSON. It illustrates how important this format is because of its extremely widespread implementation.
- Local Storage: Everything You Need to Know - Gives an easy to read summary of local storage, including details like size and performance, and comparisons to other browser-based storage like cookies. This article is framed from the perspective of assessing a candidate's skills, which gave me some good ideas on what I need to know to be a strong web developer.
- JavaScript localStorage - This is a more in depth, but still very beginner friendly article from GeeksForGeeks about how to interract with a browser's local storage using JavaScript. Highly recommend reading if you plan to implement local storage into your own website, as it also coverse some security considerations and best practices.