User space apps

Goal of this step: Understand the Boomla execution flow; create a page app and some page instances.

Execution flow

Boomla has a simple execution flow for serving a request:

  1. The request is received & parsed,

  2. The requested file is located by the requested path,

  3. The .Request method is called on the requested file -> user space code runs,

  4. The response returned by the user space code is formatted and sent.

It's good old Object Oriented Programming.

In our previous example, the html-1 built-in app's .Request method was executed which returned the HTML code stored within the requested file's body. You could write static HTML and the app returned it. If you wanted to, you could write an app yourself that does the same.

User space app

To create a user space app (everything you do is in user space), create a file anywhere on your filesystem and set its type to app-1. That's like creating a class{} in an object oriented programming language. (Except Boomla is prototype based.)

To make it implement the Request method, create a file named .Request inside it. Note the starting dot .! In Boomla, each method is stored in its own file to make it programming language independent - though currently the platform only supports JavaScript.

Then set the .Request file's type to sjs-4 to execute JavaScript code (that's the name of the JS engine) and add the code to be executed on each request.

Let's try it on our page example.

Page app

Let's create our page app at /apps/page like so:

PATH                              [TYPE]
//example.com/apps/page           [app-1]
//example.com/apps/page/.Request  [sjs-4]

Notice how the .Request file is stored within the page file:

Add some hello world code to the .Request file:

response.body('Hello from ' + f.path());

Then visit /apps/page in your browser.

For example, if you website's domain is example.com, you would go to http://example.com/apps/page and see:

Hello from //example.com/apps/page

Congratulations, you just wrote your first app!

Page instances

To create instances of this app, create other files and point their file types to the page app.

To do that, set their file types to the app file's path, for example /apps/page.

You could end up with the following filesystem tree:

PATH                               [TYPE]
//example.com                      [/apps/page]
//example.com/apps                 []
//example.com/apps/page            [app-1]
//example.com/apps/page/.Request   [sjs-4]
//example.com/about                [/apps/page]
//example.com/contact              [/apps/page]

Let's look at our JavaScript code stored in the .Request file. Here it is again:

response.body('Hello from ' + f.path());

The variable f refers to the currently visited page instance, similar to the keyword this in object oriented languages. The variable response points to a temporary response file. Write to that file to return a response.

There are a couple more injected files, here is the full list:

  • f - like keyword this in OOP

  • source - points to the current file holding the source code (holding the word source),

  • context - points to the originally requested file (see later),

  • request - holds all request data, including query parameters and uploaded files,

  • response - decorate to customize the response.

File type

The file type is either a built-in type like sjs-4 or a path pointing from one file to another, like /my-app, ./my-app or ../my-app.

Type chain

A file's type can point to another file. The type of that file can in turn point to yet another file. And so on. The chain of these file's is called the file's type chain

The type chain must end in a built-in type, otherwise the type chain is considered broken.

The .Request file may exist anywhere on the file's type chain. Boomla will execute the first one it finds.

Here is an illustration of a filesystem tree and a type chain inside it. On the right, you can see the same type chain straightened out. When you think of searching for the .Request file on the file's type chain, the one on the right is probably the better mental model.

Undo, redo

Good to know: find undo & redo on the Boomla Toolbar. Undo restores previous states of your website's filesystem. You can undo any change as long as website exists (max 50).

See how to do it (silent video)

Subscribe to our newsletter!