File Placement

File placement is the operation of creating or moving a new file node in the filesystem tree.

A file can be placed relative to another file.

Placement modifiers

The full list of placement modifiers:

AFTER
APPEND
BEFORE
FORCE
PREPEND
RENAME
TYPESAFE
TYPESAFE_IF_POSSIBLE

Direction

You must always specify the placement direction:

  • BEFORE places the file before the target file, in the same placeholder, as its previous sibling.
  • AFTER places the file after the target file, in the same placeholder, as its next sibling.
  • PREPEND places the file into the target file, to the beginning of a placeholder. The placeholder is either provided or defaults to 0. It may also be overridden by other placement modifiers.
  • APPEND places the file into the target file, to the end of a placeholder. The placeholder is either provided or defaults to 0. It may also be overridden by other placement modifiers.

Conflict resolution

If a file already exists at the target location, it may be resolved in 1 of 3 ways:

  • By default, the operation will fail.
  • RENAME instructs the system to find a name that doesn’t conflict. This typically means suffixing the name with -2 or similar, though file extensions are respected, so foo.jpg becomes foo-2.jpg.
  • FORCE removes the conflicting file and proceeds with the placement.

Type safety

Applications define what kind of files they support. For example, a gallery may display images but no zip files. The application is said to accept files that it supports. (See .Accept rules.) In such cases, the placement is typesafe, otherwise it’s not.

When placing a file, we can instruct Boomla to consider typesafety in one of the following ways:

  • By default, typesafety is not considered and the operation will succeed.
  • TYPESAFE instructs the system to only place the file if the placement is typesafe. Otherwise, the operation shall fail. When using APPEND or PREPEND, this flag will instruct Boomla to find the first accepting placeholder so that the operation can succeed in a typesafe manner.
  • TYPESAFE_IF_POSSIBLE is only effective for APPEND and PREPEND operations. It instructs the system to try placing the file in a typesafe manner. If that is not possible, place the file anyway. The following steps are taken:

    • If the placeholder is provided, and it is typesafe, use that placeholder.
    • Otherwise, if there is any typesafe placeholder, use the first.
    • Otherwise, if the placeholder is provided, use that.
    • Finally, default to using placeholder 0.