36 lines
2.8 KiB
Markdown
36 lines
2.8 KiB
Markdown
# 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. |