File Customizations

The appearance and behavior of files and folders in PFS can be extensively customized. To achieve this, Transform Files allow you to set specific attributes on files, which influence how they are displayed in the web interface.

Transform Files allow attaching arbitrary attributes to files. Attributes are hidden unless they are standard attributes. Non-standard attributes can be used with the scripting capabilities of Transform Files to generate values for standard attributes. See the Transform Files documentation for more details. Additionally, the file search makes it possible to search for file attributes, including non-standard attributes.

Some standard attributes can only be read, not written. They can be used to extract information about the files.

Standard Attributes

`id`

The id attribute represents the name of the file on the filesystem. This attribute is read-only.

`name`

The display name of the file shown in the UI. By default, the name attribute has the same value as id, which corresponds to the filename on the filesystem.

You can also set the name attribute using the rename <file> <name> function. Here, <file> can be either a file object or a string containing the filename.

// All of these lines are equivalent.
'file.txt'.name = "Custom Name"
rename 'file.txt' "Custom Name"
rename "file.txt" "Custom Name"

`path`

The path to this file or directory, relative to the root directory. Path segments are separated by /. This attribute is read-only.

`isDir`

A file object may represent a file or a directory. The isDir boolean attribute indicates whether the file object represents a directory. This attribute is read-only.

Volume

A folder can be located on multiple data volumes at the same time. The contents of these folders are merged, meaning the content of a folder in PFS can span multiple volumes. Using the volumes attribute, you can retrieve a list of all volume names where the folder's content is located.

In contrast, files are always located on exactly one volume. You can read the volume name from the volume attribute.

For folders, the volume attribute is null. For files, the volumes attribute is null.

The volume and volumes attributes are read-only.

`size` and `filecount`

The size attribute contains the file size in bytes. For folders, size represents the total size of all files located within that folder.

The filecount attribute contains the number of files located within that folder, including nested files. For files, filecount is always 1.

For folders, size and filecount are only defined during their Bottom-Up Transform Files. During Top-Down Transform Files, both attributes are null. For files, however, size and filecount are available during Top-Down Transform Files as well.

The size and filecount attributes are read-only.

Hidden files

size and filecount reflect the actual file size or number of files. Attributes such as hidden are ignored during this calculation. This means that size and filecount also include hidden files and Transform Files.

`type`

The type attribute contains a string indicating the file type. This type defines how PFS interprets the file (e.g., whether it is displayed as a video or an image).

This type should not be confused with the file extension. Files with different extensions can have the same type, e.g., jpg and png are both images. However, the type is usually derived from the extension.

Valid values for the type include "dir" (for directories), "video", "image", "audio", "text", "html", "pdf", "svg", and "file" (for other files).

The type attribute is not read-only. When set, PFS treats the file according to the specified type, regardless of whether the actual file content matches that type.

`parent`

The parent attribute contains a reference to the file object of the containing folder (i.e., the folder in which the file is located). This attribute is read-only.

`info`

For files, a description can be displayed on the detail page. This description can be set using the info attribute.

`infoposition`

By default, the file info is displayed at the top of the file detail page, above the content. The infoposition attribute can be used to control where the file info is displayed. Valid values are "top" (above the content) or "bottom" (below the content).

Thumbnail

`thumb`

The thumb attribute allows you to specify a thumbnail image for this file or directory. A thumbnail is an image displayed alongside the file in various places within the UI. For example, it appears in the file list next to the filename. The thumbnail should be a JPG or PNG image.

During the rebuild process, the thumbnail is automatically downscaled to a specific size and stored on the main volume. This allows thumbnails to be displayed in the file list without requiring data volumes to be mounted.

You can also set the thumbnail using the thumb <file> <thumb> function. Both <file> and <thumb> can be specified as file objects or filenames. Additionally, this function automatically sets the hidden attribute of the thumbnail file (<thumb>) to true, thereby hiding it from the file list.

thumb "file.txt" "thumb.jpg"
// ... is equivalent to ...
'file.txt'.thumb = 'thumb.jpg'
'thumb.jpg'.hidden = true

`hidethumb`

By default, the thumbnail is displayed on a file's detail page next to the info. If you set hidethumb to true, the thumbnail will not be displayed on the detail page. The thumbnail will still appear in the file list.

`thumbmaxwidth` and `thumbmaxheight`

The thumbmaxwidth and thumbmaxheight attributes allow you to specify the maximum display size of the thumbnail in pixels. These serve as maximum limits for the dimensions. The actual displayed size is calculated based on the original dimensions and aspect ratio of the thumbnail image.

`hidden`

If the hidden attribute of a file is set to true, it will be hidden from the file list.

For Transform Files, the hidden attribute is true by default, while it is false for all other files.

The hidden attribute can also be set to true via the hide <file> function.

Hidden files are accessible

Hidden files are only hidden from the file list. Users can still access hidden files via the UI. The hidden attribute does not provide any security protection for sensitive data!

`cache`

If the cache attribute is set to true, a copy of the file is stored on the main volume during the rebuild process. This allows the file to be viewed without mounting the volume where it resides.

Use selectively

File caching on the main volume should only be used selectively for a few small files, as caching increases disk usage on the main volume.

`newTab`

If the newTab attribute of a file is set to true, clicking the link in the file list within the UI will open the file's page in a new browser tab. By default, a file's page opens in the same browser tab.

Directory Layout

The content of a folder can be displayed in two different views. Users can switch freely between these views.

By default, folders are displayed in the list view, where files are listed vertically. Additionally, a grid view is available, which displays files as tiles in a grid.

You can control which view is displayed by default for a folder using the defaultview attribute. Valid values are "list" (for the list view) and "grid" (for the grid view).

Info Bullets

Info Bullets are small elements used to display information about a file or folder. Good use cases for info bullets include displaying the duration of a video or the capture date of a photo.

There are different types of info bullets that differ based on where they are displayed. Each type is configured via a different attribute.

headerbullets: Header bullets are displayed in the header on the detail page of a file or folder.
titlebullets: Title bullets are displayed in the file list next to the filename.
thumbbullets: Thumb bullets are displayed inside the thumbnail on the file list page.

Each of these attributes can contain an array of info bullets. An info bullet can be defined in two ways:

A string containing the text to display in the info bullet.
An object with the following structure:
```
{{
    text: string
}}
```
The text attribute contains the text to display.

Example:

file.headerbullets = ["Info"]
file.thumbbullets = [
    {{
        text: "Info"
    }}
]

Inplace Content

A folder page displays the files within that folder, and a file page displays an element representing that file. This is referred to as the content of the file or folder.

`inplace`

With inplace content, it is possible to display additional content elements on a file's detail page alongside the default content. Inplace content can be configured using the inplace attribute. The inplace attribute can contain either a single inplace object or an array of inplace objects, allowing you to define multiple inplace elements.

An inplace object follows this structure:

{{
    file: file | string
    id: string (optional)
    title: string (optional)
    width: string (optional)
    space: string (optional)
    volume: float (optional)
    sync: string (optional)
    mime: string (optional)
}}

file: The file to be displayed as an inplace element. It can be specified as a file object or as a relative path.
id: An ID for this inplace element. This is required only if the inplace element needs to be referenced elsewhere. The default content element has the id main.
title: An optional description for this inplace element, displayed as a tooltip when hovering over it.
width: If width is set to "full", the inplace element will be scaled to the full width of the page. By default, the width depends on the file type and content. No values other than "full" are supported.
space: If space is set to "none", there will be no gap between this inplace element and the next one. By default, inplace elements are separated by a small gap. No values other than "none" are supported.
volume: By default, the volume setting for media elements is saved in the browser's local storage, giving the user control over the volume. The volume attribute allows you to set a default volume for an inplace audio or video element (e.g., volume: 0.0 mutes the media element by default).
sync: sync can be set to the id of another audio or video inplace element to synchronize the playback of this element with the specified one. This means that if one of the two elements jumps to a specific timestamp, both will jump to that timestamp. If one element is paused, the other will pause as well. sync can be useful, for example, when you have audio and video tracks separated.
mime: The MIME type of the inplace element. By default, the MIME type is derived from the filename. If the mime attribute is set, the file is treated as having that MIME type, regardless of its actual content. This attribute should only be set if the MIME type is not correctly detected by default.

Hide Default Content

If you set the hidecontent attribute to true, all file content on the page will be hidden except for the inplace content. This allows you to take full control over the page layout by hiding the default content and implementing a custom one using inplace content.

Video Timestamps

Timestamps are useful for quickly jumping to specific locations within a video file. You can define timestamps for a video file, which will be displayed as buttons below the video element. Clicking a button allows you to jump directly to that timestamp.

Timestamps are defined in the timestamps attribute. This contains an array of timestamp objects in the following format:

{{
    text: string
    time: integer
    hover: string (optional)
}}

text: The text displayed as a label on the timestamp button.
time: The point in time specified as an integer representing seconds in the video (e.g., time: 100 represents 1 minute and 40 seconds).
hover: Optional text displayed when the mouse hovers over the timestamp button.

File Customizations

Standard Attributes

id

name

path

isDir

Volume

size and filecount

type

parent

info

infoposition