A reference implementation showing the capabilities of the PureWiki Extension System.
Note
You can use this extension as a starting template. Copy the folder, rename it and adjust meta.json and extension.php to start building your own extension.
Following features are implemented so far in this extension:
- Frontend & Admin Assets: Injects CSS and JS into the frontend and the admin dashboard.
- Custom Block Rendering: Hooks into the Markdown/Block parser to render a block type (
exampleBlock). - Page Settings Injection: Adds a text field to the "Page Settings" modal and saves the data automatically using the
pw-ext-inputclass. - Global Settings Tab: Registers a tab in the global Settings dashboard.
- Custom API Endpoint: Registers a new API endpoint (
example_action) with role-based access control. - Editor.js Plugin: Registers a block tool (
ExampleBlock) in the Editor.js interface. - HTML Manipulation: Injects content into the final rendered HTML page.
- Internationalization (i18n): Uses the
lang/directory to provide English and German translations for UI elements. - Settings Storage: Uses
getExtensionSettings()andsaveExtensionSettings()to store configuration.
- Copy the
example-extensionfolder into your PureWikiextensions/directory. - Log into your PureWiki Admin Dashboard (
/dashboard). - Navigate to Settings -> Extensions.
- Find "Example Extension" in the list and click the toggle switch to activate it. The page will reload automatically.
After activation, the following components are active:
A tab named "Example Ext" is available in the Global Settings sidebar. It provides an interface to save a configuration string.
The Editor block menu includes a new "Example" tool. The "Page Settings" menu contains a new "Example Metadata" text field.
Pages containing data in the "Example Metadata" field will display a banner at the bottom of the page.
The extension system provides the following hooks. They can be utilized via ExtensionLoader::addHook('hook_name', function() { ... }).
| Hook Name | Description |
|---|---|
parser.block |
Manipulate block data array before it gets rendered to HTML. |
renderer.html |
Post-process the final generated HTML of the entire page. |
renderer.block_html |
Post-process the generated HTML of a single block. |
editor.tools |
Register new Editor.js tools (block types). |
editor.tunes |
Register new Editor.js tunes (block settings). |
page_settings.fields |
Add custom HTML fields to the "Page Settings" modal. |
page_settings.save |
Hook into the save process to manipulate or validate page data. |
settings.tabs |
Register a custom tab in the global Settings dashboard. |
api.routes |
Add custom API routes (Map action strings to PHP files). |
api.admin_actions |
Whitelist specific API routes to require Admin privileges. |
api.public_actions |
Whitelist specific API routes to be publicly accessible. |
| Hook Name | Description |
|---|---|
admin.head_css |
Output <link> or <style> tags in the Admin Dashboard <head>. |
admin.head_js |
Output <script> tags in the Admin Dashboard <head>. |
frontend.head_css |
Output <link> or <style> tags in the Frontend <head>. |
frontend.head_js |
Output <script> tags in the Frontend <head>. |
frontend.footer_js |
Output <script> tags in the Frontend just before </body>. |
meta.json- Core metadata (ID, version, author). Used for discovery and validation.extension.php- The main entry point where all PHP hooks are registered.settings.php- The UI template for the custom settings tab in the admin dashboard.api.php- The backend logic for the custom API endpoint.assets/- Contains custom CSS and JS files for styling and interactivity.editorPlugins/- Contains JavaScript classes for Editor.js blocks (e.g.editor-example.js).lang/- Contains JSON files with translation strings (en.json,de.json).
- Translations: All translation keys for an extension are automatically namespaced. Use
__('ext.example-extension.your_key')to access them. - Asset Paths: When generating URLs for your assets, always use
ExtensionLoader::getUrl('your-extension-id')to ensure compatibility with reverse proxies and subdirectories. - Isolation: Extensions are booted in an isolated
try/catchblock to prevent syntax errors from breaking the whole wiki. However, you should still handle your own exceptions within complex hooks. - Auto-Saving Settings: To add fields to the Page Settings modal that save automatically, simply give your
<input>or<textarea>the CSS classpw-ext-input.