But first, I'd like to separate the overall discipline of "building GUIs" from the tools and frameworks used to build them. While the tools can make the building process enjoyable, I don't want to discuss them in this post. Instead, I want to focus on what the core of building UIs is.
The thing is, the more I work on and with GUIs, the more I’m convinced that the opposite is true — GUIs are inherently hard to build. Let me explain why.
GUIs are graphical user interfaces. They’re the primary point of contact with an actual person. And the thing about people is that they’re way more complicated than computers.
To demonstrate, take another kind of interface — Application Programming Interfaces. You could say that APIs are also written for people and that computers don’t care. While this is true, it’s also true that APIs operate in a very constrained problem space:
In contrast, GUIs present surfaces for people to interact with. Theoretically, you don’t need much training to interact with GUIs thanks to familiar metaphors from the real world — buttons, knobs, sliders, forms, etc. Beyond that, nothing is really defined.
So actually, when you’re about to build a GUI, you really have a blank canvas in front of you that is supposed to eventually help people (who maybe don’t know what they’re doing) achieve their goals without getting lost.
That doesn’t sound easy, right?
To solve hard problems, you have to scope them down. And that’s another thing that makes it non-obvious — the sheer number of decisions you have to make.
Who’s your audience? In what situations are they going to use your thing? What about first-time users — do they interact with it differently than experienced users? How much effort do you want to put into this? What are the limitations of your platform?
Answers to those questions aren’t really specific to GUIs, really. They only draw a rough outline and influence further, more specific decisions. For example: Should your UI work on mobile devices? Does someone have to be online to use it? What if somebody is, say, colorblind — is it hard for them to use your thing? Do you want it to blend into the operating system well?
The rabbit hole of decisions can become pretty deep.
I feel like I spent much more time working on this blog’s layout and its post editor than on the underlying library to use use Matrix as a blog, so I think they’re a good example. But first, to set the stage, let’s start with the library and the decisions that shaped it.
matrix-blog is a library written in TypeScript to talk with a Matrix server as if it was a backend for a blog. It only has one dependency, node-fetch, and that’s mostly for convenience. It’s made of two layers — its own Matrix client and an API to interact with blogs and their posts. There are a few decisions I had to make to make this happen:
login method because I didn’t want to think about session storage.That’s pretty much it. Let’s contrast this with the decisions that shaped this website:
That’s a much longer list for something that just displays content! And there's still a lot to improve!
Of course, you could argue that if you want to build things well, then it’s always going to take more time, energy, and decisions. That’s true. You could also decide that you don’t care about the looks and not do any of the things I've done. That’s fine.
The point I tried to express in this blog post is that, on average, GUIs are hard to build because of the number of decisions you have to make. That's just how they are! But that shouldn't discourage anyone from building UIs! On the contrary, I hope people will treat them as any other challenging problem to solve. I also hope that it will lead to better user experiences for everyone.
]]>Another thing about me is that I like to tinker with software and enjoy working on… call it unusual problems. I also like to read about people doing weird cool things with tech, so I figured that maybe it would be cool to have a blog.
Therefore it makes perfect sense that one time during a shower I've got an idea: what if I could combine the two and host a blog on Matrix?
I guess this is likely the first question that comes to mind. It's probably not the best way to host a blog. After all, you can use any hosted blog platform like WordPress or write some Markdown in a Git repository and use a static site generator like Eleventy or Hugo. This would make your life easier.
Well, the true answer is really because I can. It turns out that Matrix is not just a chat protocol. It's more like a decentralized, time-ordered event store that synchronized between federating servers. In other words — if you can shape something as a series of events, you can put it in Matrix.
Of course, Matrix is still used primarily for chat, so I thought that it would be nice to be able to interact with the blog using regular Matrix clients like Element. This way, you could allow people to read the blog posts and comment on them directly in their chat clients. It's just a matter of mapping the blog to a compatible representation.
What do we need to represent a blog? Aside from a list of posts, each post should have:
It turns out that the base protocol already has all the necessary pieces!
First, in Matrix, communication happens in rooms — just like on Slack or IRC. Because I wanted to potentially have discussions on every single blog posts, it makes sense to represent blog posts as rooms.
A room can have a user-friendly name that can represent a post title. It can also have a topic, which usually describes the current conversation topic, but could serve as a summary of the blog post.
Usually, each Matrix room is identified by a server-generated string that looks like this: !xZzBOxfyJgfJbaiEGc:evolved.systems. While this is perfectly fine to be used in an URL, it's not very readable and it's nice to have readable URLs. Fortunately, rooms can have aliases (called addresses in Element) that solve the readability problem. They look like this: #matrix:matrix.org. A room can have multiple aliases (e.g. on multiple servers), but there's only one canonical alias — and that's what I use to represent the slug. However, there's one caveat: because I also want to use rooms for other things than a blog, I add a prefix in front of the slug to prevent name clashes. This means that, for example, this blog post would have a canonical alias of #blog.hosting-a-blog-on-matrix:evolved.systems. Using aliases has a nice bonus of controlling if a post is visible — if there's no alias, it's not "published" and therefore not visible.
Finally, representing the post content sounds pretty easy — just write a message! We can say that the first message in a room will be the post content. Matrix supports plain text and HTML-formatted messages. Both types can be set side-by-side, so you can put Markdown in the plain text part and the rendered HTML in the formatted part, which is pretty convenient.
So far it's all pretty simple, so I think this is a good time to add some color. It's easy to say "just write a message" or "set a name", but what does this mean?
Well, as I mentioned before, Matrix is really a time-ordered event store. You could say that rooms actually are timelines of events. Furthermore, there are two kinds of events — message events and state events.
Message events are pretty self-explanatory — some content sent by somebody at a given time. On the other hand, state events are quite interesting, as they also allow to influence the state of the room itself. You could think of them as being building blocks of a key-value store that represents the room state (where "key" is "event type" + optional "state key"). The server has dedicated APIs to read individual state values and also to retrieve the entire state by fetching the most recent events for each "key".
For example, the name of the room is really represented by the m.room.name event. To read the current name, you can ask for the value by sending a GET request for that specific event type. You can also retrieve the entire state and search for the m.room.name there. To change the name, you just send a new state event.
This is how we find the timestamps we need for the post — since each event has a timestamp, we can pick the meaningful ones. I've decided that the moment I set a slug for a post is the moment when I consider the post "published" — so the publishing date is the time of the latest canonical alias event that actually sets (not clears) an alias.
Edit: I mentioned above how the first message would be representing the post content. Turns out that getting the first message of a room statelessly is tricky. The endpoint used for retrieving room messages requires specifying a token that indicates where events should be returned from. We don't have one without calling /sync before. To work around this, I introduced a custom state event named co.hirsz.blog.post_content that holds the event ID of the post message, e.g. {"event_id": "$something"}. This makes it easy to fetch the event along with the rest of the state.
So far, everything I described is part of the stable Matrix Client-Server API (r0.6.1). However, to have a functional blog we need more: we still can't edit messages and don't know how to get a list of posts, which is pretty basic functionality. Fortunately, the Matrix protocol is constantly evolving through Matrix Spec Changes (MSCs), some of which are already implemented in servers.
Editing messages is already implemented in Synapse, the reference server implementation, and is specified in MSC2676. Basically, editing works by sending a new message marking that it replaces the old one. The nice thing about the implementation is that you can still reference the event ID of the old message — it will automatically have the new content.
To represent a list of rooms, I've decided to use Spaces — the newest, shiniest feature of Matrix. Spaces are special kinds of rooms — they can contain other rooms. You can probably see how it's useful: since blog posts are rooms, we can have a single parent room that contains all the rooms for posts. Since rooms are linked to spaces using state events, we could just use that. However, I went with the dedicated Spaces Summary API, mostly to see how it works.
Since it's not exactly fun to write blog posts by sending HTTP requests with cURL (although you could do that!), of course, I had to build the entire stack:
matrix-js-sdk exists)All in all, this was a fun, if a bit lengthy journey in rediscovering modern front-end development. It took me about a month to get here, but it's finally more or less done. Of course, there's always work to do — for instance, image uploads would be nice — but that can be done in further iterations. Maybe I'll write about them in future posts.
If you want to take a look at the ugly code I've written that implements the above — check out the GitHub repo. For an example of how this works in practice, check out matrix-blog-admin on GitHub, the post editor app I wrote.
]]>