# 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.