The site uses cookies that you may not want. Continued use means acceptance. For more information see our privacy policy.

JSON Schemas and Making a Versatile Application.

Please excuse the big wad of JSON in the middle of the post.

Things have come a long way from the previous post (diehealthy.org: 27 October 2022: “Working on a Local Single Page Application.”) about working on a local file that provides a whole data tracking. While I originally wanted it to be used for games, I’d seen other JSON-schema-based stuff online and decided it could be fully schema driven. While it doesn’t yet edit its own schemas, that’s probably feasible in the long run (if not something I’ll necessarily do).

In order to further refine it toward that schema system, I forked it and made a version to track the movies I’ve watch. The post image is of that version, though they are currently at parity aside from the schema differences.

To give an idea what I mean by schema, here’s some excerpts from the film version:

{
    "name": "filmtracker",
    "defaults": {
        "filters": {
            "recorded": 1,
            "watched": 0
        }
    },
    "props": [
        {
            "name": "name",
            "title": "Name",
            "type": "string",
            "display": "headertext",
            "displaystyle": "italics",
            "sortOn": true,
            "req": true,
            "def": null
        },
        {
            "name": "recorddata",
            "title": "Record data",
            "type": "group",
            "props": [
                {
                    "name": "added",
                    "title": "Added",
                    "hidden": true,
                    "display": "fulldate",
                    "displayprefix": "Added on",
                    "type": "date",
                    "sortOn": true
                },
                {
                    "name": "modified",
                    "title": "Modified",
                    "hidden": true,
                    "display": "fulldate",
                    "displayprefix": "Updated on",
                    "type": "date",
                    "sortOn": true
                }
            ]
        },
        {
            "name": "watchdata",
            "title": "Watch info",
            "type": "group",
            "props": [
                {
                    "name": "recorded",
                    "title": "Recorded",
                    "type": "bool",
                    "display": "iffalse",
                    "displayvalue": "Unrecorded.",
                    "summaryvalue": "📅",
                    "filter": true,
                    "def": 0
                },
                {
                    "name": "watched",
                    "title": "Watched",
                    "type": "bool",
                    "display": "text",
                    "displaydepends": [
                        "recorded"
                    ],
                    "displayvalues": [
                        "Unseen",
                        "Seen"
                    ],
                    "summaryvalues": [
                        "💾",
                        "🍿"
                    ],
                    "filter": true,
                    "def": 0
                },
                {
                    "name": "watchdate",
                    "title": "Date of watch",
                    "type": "date",
                    "display": "monthdate",
                    "displaydepends": [
                        "watched"
                    ],
                    "displayprefix": "Watched",
                    "sortOn": true,
                    "sortDep": "bought",
                    "def": ""
                }
            ]
        },
        {
            "name": "filmdata",
            "title": "Film info",
            "type": "group",
            "props": [
                {
                    "name": "releaseyear",
                    "title": "Year of Release",
                    "type": "num",
                    "display": "text",
                    "displayprefix": "Year:",
                    "sortOn": true,
                    "minv": 1900,
                    "def": 2022
                },
                {
                    "name": "score",
                    "title": "Review score",
                    "type": "range",
                    "display": "stars",
                    "displaydepends": [
                        "watched"
                    ],
                    "displayprefix": "Score:",
                    "summaryvalue": "stars",
                    "sortOn": true,
                    "sortDep": "watched",
                    "minv": 0,
                    "maxv": 5,
                    "step": 1,
                    "def": 0
                }
            ]
        },
        {
            "name": "categories",
            "title": "Tags",
            "type": "strarray",
            "display": "ulist",
            "def": null
        },
        {
            "name": "notes",
            "title": "Notes",
            "type": "text",
            "display": "longtext",
            "summary": "📓",
            "def": null
        }
    ]
}

It’s quite a lot, and messy (as is the rest of the application so far), and it mixes data definitions with their presentation, but it’s mostly serviceable. But it lets me define, with the current version:

  • groups
  • numeric inputs
  • string inputs
  • url inputs (unvalidated at the moment)
  • date inputs (though I’d prefer to move to month/year or such)
  • boolean inputs (implemented as radio buttons)
  • tri inputs (radio buttons)
  • range inputs (radio buttons)
  • text inputs (text boxes)
  • string array inputs (for tags, with autocomplete!)

I’d originally gone with checkboxes and three-state checkboxes for booleans and tris, but decided it was too much trouble and having separate buttons looked nicer. The basic checkboxes were reused instead for toggling off or on the listing filters for boolean and tri fields.

It can also search in and sort the listing.


One of the nicer parts of all this is the ability to export and import from JSON, as well as being able to use the browser console to loop through and batch-modify the data. I’m not sure how feasible it would be to implement that through UI, which would be more useful to nontechnical users. But for now this is just a little project to handle my own data.

If I can get it cleaned up, I’ll probably throw a copy up here at some point, though so far I’m still iterating on it a good bit as I go through my old list of movies I watched and fill in their details. I started keeping a list at some point last year, and that was title-only, so it’s been a lot of searching, figuring out which was the movie I actually watched, trying to remember enough to give it a rating.

But the main goal is that if I decide I need a list of something, I can copy the file over, throw a schema together, and start making the list in a way that lets me update it or review it better than a text file and not requiring the ugliness of a spreadsheet. Like when I kept a list of the legislators who objected on 6 January 2021, that’s just a text file. Next time it could be a nice little application that makes the task not necessarily easier, but more useful:

  1. Get a text list of the things
  2. Some light massaging to turn it into JSON
  3. Write a quick schema
  4. Import the data
  5. Fill in any details, be able to filter, sort, search easily.

I can only imagine what data wrangling looks like in 100 years. I hope by then it’s all AI user interfaces that look pretty are functional no friction. Until then, this project has reminded me how powerful, how versatile, and above all how fairly simple, HTML plus Javascript has gotten.

It Came…From the Internet! MutationObserver

A brief overview of the DOM4 MutationObserver.

[Fade in Louis Armstrong singing On the Sunny Side of the Street.]

Grab your lab coat // Put on your hazmat, baby
Leave your worries on the doorstep
Life can be so sweet
On the sunny side of the street
[…]

Okay, MutationObserver isn’t really that scary. It’s part of the DOM4 specification as a replacement for Mutation Events. MDN: DOM: MutationObserver documents it.

What are Mutation Events? A DOM3 specification to allow you to watch the DOM change using the well worn events API. You know, the old

node.addEventListener('click', onNodeClick, false);

style events.

But Mutation Events made things slow. A lot of sites mutate or change the DOM quite often, and depending where you attach the listener and how frequent the changes come, it added up to a lot of event traffic. MutationObserver replaces this.

A MutationObserver doesn’t receive a callback for every change. Instead it receives periodic callbacks for a group of changes. That group may contain a single change, depending on the stability the DOM tree (if only a few changes occur at large intervals, they may be announced separately). Think of it like an announced log instead of alerts.

MutationObserver takes a bit more setup than just tagging an event listener on a node. But that setup makes it cleaner and more useful.

var observer = new MutationObserver(function (mutations) {
    mutations.forEach(function (mutation) {
        console.log(mutation.type);
    });
});

That’s a simple MutationObserver. You provide a function that receives an Array of MutationRecord objects. But that just creates the observer, you have to activate it.

var config = { childList: true, attributes: false, characterData: false, subtree: true };

So first you need an object (technically a MutationObserverInit object) specifying what types of mutations you care about (you can also specify some extra options about which data to include in the MutationRecord objects you get back). You really just worry about making this give you what you want and not give you anything else. If you want to know about node added or removed from the DOM tree, you don’t need attributes or characterData, for example.

Once you have your configuration ready, you also need a root node to observe. You can observe document, the true root, but you should attempt to observe the minimal subtree you will need.

Say the page shows a chess game, and you want to add some automatic comments or classes (for styling) to the move log. You only need to observe the part of the tree that contains the log. The page logo, the board itself, the chat, and anything else don’t matter.

var moveLog = document.querySelector('#moveLog');

We can finally turn the MutationObserver on:

observer.observe(moveLog, config);

Now when new changes happen under moveLog, the function we specified when creating the observer will be called back. But we can go a bit further. Let’s say you have two separate subtrees to observe. You could either find their lowest common ancestor and observe that whole subtree, or you can do the smart thing and simply register the observer with the second subtree:

observer.observe(oneNode, config);
observer.observe(twoNode, config);

Note that was, “register the observer with” the node, not the other way around. Although you call on the observer, this tells it to add itself to the list of observers associated with the node in question.

You can also shut the whole thing down:

observer.disconnect();

This kills all the registrations, so unfortunately you cannot easily modify the actively observed subtrees.

Also note:

observer.observe(myTarget, config1);
observer.observe(myTarget, config2);

This replaces the options for observing myTarget.

Anyway, that’s a brief overview of the not-so-scary, highly useful MutationObserver. It’s particularly nice for user scripts that want to cope with dynamic web pages. Instead of being stuck with some modification only for the nodes that were there when the page loaded, you can now easily observe changes and carry your modifications over as new nodes appear.

Learning to Compute

Anyway, this isn’t about whether you should or shouldn’t, can or can’t, will or won’t learn to program. This is about doing the actual bit that’s being discussed abstractly.

Some well-known person in the software community wrote about why, I don’t know, mere mortals?, shouldn’t learn to write software.

To be honest I didn’t read it. Any time someone says that I shouldn’t do something for any non-scientific or non-moral reason, I add another check to the column for “this maybe should be done.”

I skimmed several of the thoughtful rebuttals on other blogs, and think their general consensus is valuable, which is basically, “yes, you should learn to write software, because it’s awesome.”

Anyway, this isn’t about whether you should or shouldn’t, can or can’t, will or won’t. This is about doing the actual bit that’s being discussed abstractly.

Let’s assume for the sake of argument that you are using Firefox and viewing this site in the browser. Let’s assume it’s on a non-mobile Operating System with a keyboard and other fancy stuff like a screen.

Let’s assume you were to press the key combination Ctrl+Shift+K (Hey! Wait a damn minute there. Don’t press stuff without finding out what it does!) or go to the Firefox menu, to Web Developer and then to Web Console (which is what the key command before does).

You should now see some slick little bit of chrome fall out of the sky above the website.

You should see that it has a text input area at the bottom. Click there. Type something like, alert("Boo!"); and press Enter. Stop! Why are you typing stuff in before you know what it does?

Okay, to be fair, I type stuff in without knowing exactly what it will do, and aside from some wizards, most people who write software do this. But we know almost exactly, and we’ve got experience: think of it like cooking. A master chef can imagine how a recipe will taste just by reading it. Experience works like that, though even the experienced can be mistaken.

So before you type something, you should stop and think about what it might do, and what you want it to do. alert, that might make lights flash and buzzers sound. But it has those parentheses around the quoted bit.

Maybe it creates some kind of alert using that quoted part.

Go ahead and try it.

Right! A happy little alert box pops up with the text Boo!.

So why does that work? Think of it like cooking, again. The baker doesn’t just reach into the oven and pull out a pie. Each piece had to be made, including the pie tin (which was beyond the scope of the baker’s activity). In this case, think of the alert() bit as the pie tin. The makers of the browser gave you the pie tin and said, “fill it with what you need to fill it.”

If you think about it, the parentheses almost look like a pie tin. Are you hungry yet?

So let’s do something a bit simpler this time. Just type 1 + 1 and press Enter. Right, good thought, we have to ask what it might do. Well, if I wrote it down on paper and handed it to you, what would you probably say? Yes, you would say, “two.” That’s what the console will say back to you:

[13:25:34.419] 1 + 1
[13:25:34.423] 2

That bit there is taken directly from the console. If you select lines in it and then copy them, it puts the fancy timestamps in front. Those help you understand the behavior of more complex programs by letting you know what times the output corresponded to, how long things took (by seeing the difference in the times), etc.

Okay, one more thing to try for today. Start typing document, but just the d at first. Notice it gives you a handy drop-down of possible matches. You can use the up and down cursor keys to go through that list, or click on one with the mouse. If you keep typing, once it has a plausible match it will ghost-in the rest of the word for you. Once that happens, you can press the Tab button to complete the word.

Once you have document, put a . after it, and then type getElementById. You may have noticed that there were other getElement* bits, and some other things too. I hope you noticed, that’s the main skill to work on as a programmer: seeing all the details and wondering why.

Later on, if you want to keep learning about programming, you might go back to the web console (Ctrl+Shift+K) and just start typing things (don’t press Enter, just type say, c and see what pops up in the list). Ask yourself what they might do, and then use a search engine to ask the web what they actually do.

Okay, back on track: document.getElementById(???) What do we need to replace the ??? with? You’ll see the so-called “CamelCase” names in software a bit, so get used to mentally putting spaces in: get Element By Id. Right, if we hand it the Id, it will hand us the Element.

Let’s use one I know: site-title. That’s the id for the HTML element containing the blog title up top. So let’s do something with that.

We can do this two different ways. One way is to store the element we get back, and then speak about that, the other way is to do it directly.

The first way is to give the Element a name. To do this we can type var titleElement = document.getElementById('site-title'); and press Enter. We type var first, because we want it to be a regular variable. This has to do with scoping rules, which I won’t discuss here, but you will learn about if you keep growing your skill.

Once we have it as a variable named titleElement (you could name it something else if you prefer), we can use the name to reference that Element.

Now we can type titleElement.style.backgroundColor = "black"; and press Enter. The style part means that you want to access the Element‘s style properties. The style.backgroundColor means you want to access the background color of the Element. And we’re setting it to the named color black.

Scroll up to the top and look at the result. The background around the blog title is now black!

It doesn’t look right, of course. The background was more of a white, so let’s try changing it back.

Press the up arrow, and it will show you the last thing you typed. You can navigate the input history in the console using the up and down keys.

Change black to white and press enter again. Oops, it’s not quite white, either. What do we type to get it back the way it was?!

Let’s set it back the way it was, but let’s do it the other way I mentioned before: type document.getElementById('site-title').style.backgroundColor = "inherit"; and press Enter. Here we aren’t bothering to store the Element in a variable. We’re using it directly from the return of getElementById(). And we’re setting the color to inherit, which means “whatever the parent value is.”

The rules for Cascading Style Sheets are something you can learn about later, but you can think of it like cooking again. By default, a BLT sandwich has bacon, lettuce, and tomato. If someone wants a special one, then maybe its bltSandwich.style.bread = "pita", but normally it’s just whole-wheat. inherit just means, “whatever it would be for the environment it’s in.” (It means inherit the value from the parent, because elements in HTML are in a tree structure).

The main thing is that the color is back to normal!

That’s enough for now. You can close the console by clicking the x in the corner of it, or by pressing Ctrl+Shift+K again. If you make a live change while learning (live changes are those that you make to a webpage directly, such as by the Web Console), and you don’t know how to undo it, simply reloading the page should get you back to the default state.