Filesystem tree

In the Boomla Filesystem, files are also directories. They can store both data and have children, at the same time.

Because there is no difference between files and directories, we usually just draw them as circles:

Files are stored in the order you place them. When placing a file, you have to specify its exact location, not only the parent that shall contain it.

This feature was designed to help ordering elements on the user interface without the need for an orderID field or something similar in a database.

Files can have children, but those children are not directly stored in the parent file, there is an intermediate layer of buckets that are not shown in file paths.

Let's see an example. Say, we have a 2-column layout called layout with a left and a right column. If we place an image in the left column, it should be stored on the filesystem as a child of the layout file, for example at layout/image.jpg. Then the problem is, how can we tell if the image is in the left or the right column? If we stored the image in layout/right/image.jpg, it would be easy to tell.

Boomla uses this approach with a tweak: instead of using a file for the right object in this hierarchy, we use a concept called a bucket.

A bucket is a hidden object in the filesystem hierarchy, in that it doesn't show up in file paths. In the example above the path of the image would be layout/image.jpg, which means the right bucket name would not show up, although it would still exist in the hierarchy.

The purpose of buckets is to create sub-groups among the children of a file. As they are only for grouping files, they are often left out of filesystem drawings for simplicity.

Buckets are defined by the app associated with a file. They are virtual objects, meaning that they don't need to be created on every instance of an app. Once the app defines a bucket, the buckets will automatically exist on every instance of the app.

Bucket names starting with an uppercase letter are considered system bucket names. These bucket names are to be defined by the Boomla OS and apps shall only use them for their specified purposes. Bucket names starting with a lowercase letter are free to be used for any purpose by user space apps.

Currently, there is one such system defined bucket name, the Pages bucket, which is used to store the page hierarchy of a website. If you create a page app that allows its page instances to have sub-pages, you should define that the Pages bucket shall accept page files.

Historically, Boomla had numeric bucketIds instead of bucket names, ranging from 0-255. Bucket 0 was used for source files, assets, etc. This bucket is to be renamed to a more human-friendly name in the future but for now it remains to be called bucket 0. Note that this bucket is also to be considered a system defined bucket. When programmatically creating a file on the filesystem without specifying the bucket, it will be automatically placed in bucket 0.

Apps define which buckets shall exist on instances and what kinds of files should be accepted in those buckets. See file placement and the .Buckets file for more details on this.

Boomla supports file links. You can create a file link by setting the file's link property.

Among other things, file links can be used to mount one volume into another. This is for example used to mount packages.

A Boomla filesystem is a tree of volumes. Volumes can be nested via file links.

The fileNodeId of a file is unique within a volume but not within a filesystem. For example i123.

The fileId of a file is unique within a filesystem. It can be thought of as a fileNodeId path, defining how to reach a file across volume boundaries. For example f4.6.8.