luxtools-plugin/.github/spec.prompt.md

Page Link Feature Specification

This is the specification for a planned new feature called "Page Link". The idea is this: Every page for which page linking is activated will receive a unique identifier (UUID). This UUID is creaded once and stored on the page directly. Now if a .pagelink file exist in a folder that contains the same UUID the page and the folder are considered "linked". This allows for a variety of new features:

• All syntaxes available in this plugin can now be used with the automatic 'blobs' path alias.
• That means where before you had to write {{images>/Scape/some/folder/*}} you can now write {{images>blobs/*}} if the page is linked to the folder.
• This also works for other syntaxes like {{files>blobs/*}}.
• The mapping of pages to folders is cached for performance by this plugin.
• The UUID is created when the corresponding button is clicked in the editor toolbar.`
• The UUID is stored in the page metadata as pagelink: <UUID>.
• The UUID is not shown to the user directly, only used internally by the plugin.
• Instead the user sees that the page is linked to a folder above the page content (next to the pageid).
• If the page has a UUID but no folder is linked, a text is shown that no folder is linked yet.
• clicking the text copies the UUID to the clipboard for easy creation of the .pagelink file.
• If a folder is linked, the name of the folder is shown above the page content.
• The .pagelink file is a simple text file that contains the UUID.
• The .pagelink file must be created manually by the user in the folder they want to link to the page.

Additional considerations:

• Folder can be moved freely, as long as the .pagelink file remains in the folder.
• That means the link is stable even if the folder is moved or renamed.
• Deleting the .pagelink file will unlink the folder from the page.
• The plugin maintins a cache of all linked folders and their UUIDs for performance.
• This is done in a mapping file stored in the plugin cache folder.
• On page load, the plugin checks if the page has a UUID and looks up the linked folder in the cache.
• If it is not found there, the plugin will search all folders for a matching .pagelink file.
• This search is cached for performance, so it is not done on every page load.

To not overwhelm the server with searches for .pagelink files, the following strategy is used:

• The whole feature is limited to paths under the root aliases defined in the paths setting in #file:../admin/main.php
• Only folders under these root paths are searched for .pagelink files.
• Additionally a new setting pagelink_search_depth is introduced.
• This setting defines how deep the search for .pagelink files goes.
• For example, if the setting is 2, only folders that are at most 2 levels deep under the root paths are searched.