File publish dependencies

When the feature contentfile_auto_offline is activated for a node, files and images of that node will not be published, unless they are used by other objects.

1 Activating Feature

The feature must be generally activated:

conf/features.yml

feature:
  contentfile_auto_offline: true

Changing the general setting for the feature requires the CMS to be restarted.

Once the feature is generally activated, it can be turned on and off for each node using the Backend UI by a user with edit permission on the node:

  1. Choose Features from the Context Menu of the Node in the tree.
  2. Activate the checkbox next to contentfile_auto_offline
  3. Click OK to activate the feature

If the option Features is missing from the context menu, or the feature contentfile_auto_offline is not listed in the features activation dialog, the feature contentfile_auto_offline is probably not generally activated.

2 How the feature works

During the publish process, a file or image will be marked online, if at least one of the following is true

  • The feature contentfile_auto_offline is generally disabled (meaning: all files should be online)
  • The feature contentfile_auto_offline is not set for the node of the file
  • The file shall be forced to go online (see Forcing files to go online on details)
  • The file is used by at least one page or folder (see Examples of objects using files for details)

If a files is not marked online, it is offline and will neither be published into the filesystem, nor into the contentrepository.

This will be done in every publish process, regardless of whether the feature contentfile_auto_offline is activated or not.

2.1 Examples of objects using files

  • A page contains a link to the file
  • A page displays properties of the file by rendering an overview that contains the file
  • A page displays properties of the file by rendering velocity code

Dependencies are only calculated when rendering objects during the publish process. If e.g. a page uses a file only in edit or preview mode, but not in publish mode, the dependency does not count. When the dependency is created in an object property, it only counts, if the object property is either rendered in the page content or published into the contentrepository.

Dependencies from other files (e.g. in object properties) do not count. If the system contains e.g. two files that link to each other in an object property, but not other object has dependencies on either of the files, they will both be offline.

3 Forcing files to go online

Files/images that need to be published regardless of whether they are used or not can be forced to go online by checking the checkbox next to Force publish in the Properties dialog of the file or image.

4 Display of publish status

The tooltip for files/images in the file/image list of the backend UI displays the current status of the file (whether the file is currently marked online or offline).

5 Online status of new files

When a new file is created, it is marked offline by default (because it has not yet been published). During the next publish process, a check will be done, whether the file has to be set online.

6 Instant publishing

Instant publishing is also affected by the feature contentfile_auto_offline. When a new file is created in a node with the feature enabled, and the file does not have Force publish flag enabled, the file will not be instantly published into the content repository. If then a page is published, that uses the currently offline file, this is detected and the file will be set to be online (because it is now used by a page) and instantly published together with the page into the content repository.

This ensures that no page written into the content repository will link to files that are not yet written into the content repository, even if instant publishing is used.

7 Searching for offline or online files

The extended search for files/images now contains an option to filter only online or offline files/images. This option will be available even if the feature contentfile_auto_offline is not activated.