Boxes

The concept of boxes is fundamental to the design of Onwebed. It's designed to be extensible, yet simple to understand. Boxes are the building blocks of pages.

Introduction

Every single website in Onwebed is composed of pages, which in turn is defined by boxes. Each box can be seen as "piece" of your page, and renders to one or more HTML elements. Boxes are extensible, and can be programmed to do anything - such as inheriting content from another page, overriding other boxes, etc.

There are two types of boxes - solid, and liquid. However, every single box has a label, and some content. As you can guess from the name, boxes are primarily there to hold something - its content. The label gives the box its identity, it defines what it stands for.

Solid boxes are more like pencil holders, they're there to organize things - that is, they hold other boxes. Liquid boxes, on the other side, hold text as their content, and as its name defines - it needs to be stored in a container (solid box), otherwise it'll spill all over the place!

Every page is rendered to HTML to present to the viewer of the web page. Boxes, the building blocks of pages, are converted to HTML based on the label and its contents.

Overview

Empty solid box:

Empty solid box with a label:

Empty solid box with a label, and a liquid box inside:

Empty solid box with a label, a liquid box inside, which in turn has a label inside:

Solid Box

A type of box which holds other boxes as its content. It plays a vital role in developing the structure of your page. The content of a solid box can be set visually, or through a markup language called ODL.

Solid boxes are named so as they are independent - they can exist by themselves, not requiring a container to hold them in. Instead, they act as containers themselves, just like solids in the physical world.

This is how a solid box looks like:

Here, the box has a label hole#message, and it holds a liquid box with content Default Message. As you can see, the solid box just has a plain rounded border, the label of the solid box is just a purplish-blue box, whilst the liquid box is the one with a light-gray background.

Liquid Box

A box which can only hold text as its content.

The text is treated as plain-text by Onwebed's rendering engine; but since the rendered document is later handled by Django, Django's templating language will work just fine.

Liquid boxes cannot exist on their own, but require a container (a solid box) to hold them in.

As the name implies, liquid boxes are meant to be put inside solid boxes, just how water (liquid) is held by glass (solid).

This is how a liquid box looks like:

As you can see, it's just a light-gray box with some text Hello! inside. Not to mention that this liquid box must be placed inside a solid box, and cannot exist on its own.

Label

A label gives a box its identity, especially when the box is rendered to HTML.

A box, based on its label, may be rendered into multiple HTML elements. We'll look more into how a box is rendered into such elements in the following sections.

Simple Labels

A label which is composed of a single word. E.g. h1, div, this-is-a-single-word, div[id='lorem' class='ipsum'].

In the context of a label, a word is a series of characters without any space in between. An exception is when the space[s] is enclosed in square brackets ([ and ]).

Boxes with simple labels always render to a single HTML element.

Example:

Label	HTML (... represents the content of the box)
h1	<h1>...</h1>
div[id='lorem' class='ipsum']	<div id="lorem" class="ipsum">...</div>

Composite Labels

A label which is composed of multiple words. E.g. div h1, first-word second-word third-word, div.first[id='intro'] div.second. In the examples, the first and third labels contain 2 words, whilst the second label contains three words.

A label which has n-words will render to n-elements. So, a label with 5 words will render to 5 HTML elements. The ratio of words to elements is always 1:1.

Examples:

Label	HTML (... represents the content of the box)
div h1	<div><h1>...</h1></div>
body div h1	<body><div><h1>...</h1></div></body>

Attributes

Each word in a label can have one or more attributes. When a word of a label gets rendered as an HTML element, its attributes are put inside the element.

Attributes of words are key-value pairs, separated with spaces, and enclosed in square brackets ([ and ]), just like the attributes of elements in HTML.

Examples:

Label	HTML (... represents the content of the box)
h1[class='title']	<h1 class="title">...</h1>
div[id='header'] div[class='menu']	<div id="header"><div class="menu>...</div></div>
button[id='login' class='button is-primary']	<button id="login" class="button is-primary">...</button>

Shortcuts to adding ID and Class Attributes

Instead of adding id and class attributes from what we've seen in the previous section, we can use shortcuts to do the same thing.

Anything in the word followed by a # is the id attribute, whereas anything followed by . is part of its class attribute.

An HTML element can have multiple classes, but only one ID which must be unique throughout the HTML document - for obvious reasons!

Examples:

Label	HTML (... represents the content of the box)
h1.title	<h1 class="title">...</h1>
div#header div.menu	<div id="header"><div class="menu">...</div></div>
button#login.button.is-primary	<button id="login" class="button is-primary">...</button>

Elements Without Bodies

A word may need to be rendered into an element without a body. A good example is the link element, which is commonly used for linking a CSS stylesheet.

To do so, append the word with . which is not to be confused with the shortcut to the class attribute. A word which has a period as its last character will be rendered into an element without a body. In other words, the element will be closed within its starting tag, and won't have an ending tag (no body).

Example:

Label	HTML (... represents the content of the box)
link[rel="stylesheet" href="style.css"].	<link rel="stylesheet" href="style.css"/>

Special Elements

Special elements are processed to generate content based on their attributes and content.

Example:

As explained in the previous sections, a box with label page#forum. will be rendered into the element <page id="forum"/>.

Now, an element named page is special. After the boxes are rendered into elements, Onwebed processes all the elements for special elements, replacing them with content based on their attributes and content.

Page

The page element represents a page, as its name implies. It'll be replaced with contents of a page, whose name is stated in the id attribute of the element.

So for example, a box with label page#forum. will be rendered into <page id="forum"/>.

In this case, the element will be replaced with the contents of the page named forum.

This special element cannot have any content, as it doesn't make any sense to have one. Make sure you close the element in the starting tag.

Summary:

Let's assume that the page forum has a content of Lorem Ipsum.

Label	HTML (intermediate)	HTML (final)
page#forum.	<page id="forum"/>	Lorem Ipsum

Technically speaking, the so-called "HTML (intermediate)" isn't HTML, it's XML as there is no page element defined in HTML's specifications. But for simplicity and consistency, we're going to use the term HTML.

Holes and Fills

The hole element represents some content which may be replaced at any point by the fill element. If it isn't fill-ed, the content defined in hole will remain.

A hole have a name unique amongst all holes, provided through its id attribute. A fill will only replace contents of its target (a hole), whose name is provided through its id attribute.

It's conventional to name holes and fills in snake case, just like the names of pages.

Holes and fills are used for reducing redundancy in workflow, especially for overriding contents of an external page.

Let's assume we got two boxes, one representing a hole, and another a fill, along with some content, both with the names message provided through their id attributes:

This will result in:

HTML (intermediate)	HTML (final)
<hole id="message">Default Message</hole> <fill id="message">New Message</fill>	New Message

The content of the hole is automatically replaced by the fill's.

If the fill element's name doesn't equal any hole's name, the fill element will be ignored.

Example:

HTML (intermediate)	HTML (final)
<hole id="message">Default Message</hole> <fill id="message2">New Message</fill>	Default Message