extension.php

<?php
/**
 * Example Extension for PureWiki
 * 
 * Demonstrates the usage of the Extension functions and hooks.
 * It is a good starting point for creating your own extensions.
 * This extension is just a demo and is not intended to be used in a production environment!
 */
defined('PUREWIKI') || die('Direct access denied.');


// ASSET INJECTION (FRONTEND)
// Inject custom CSS and JavaScript into the public frontend.
// Use 'ExtensionLoader::getUrl($id)' to get the correct absolute URL for your extensions folder.
ExtensionLoader::addHook('frontend.head_css', function($context) {
    echo '<link rel="stylesheet" href="' . ExtensionLoader::getUrl('example-extension') . '/assets/extension.css">' . "\n";
});
ExtensionLoader::addHook('frontend.footer_js', function($context) {
    echo '<script src="' . ExtensionLoader::getUrl('example-extension') . '/assets/extension.js" defer></script>' . "\n";
});


// ASSET INJECTION (ADMIN DASHBOARD)
// Inject custom CSS and JavaScript into the Admin Dashboard.
ExtensionLoader::addHook('admin.head_css', function($context) {
    echo '<link rel="stylesheet" href="' . ExtensionLoader::getUrl('example-extension') . '/assets/extension.css">' . "\n";
});

ExtensionLoader::addHook("admin.head_js", function($context) {
    echo '<script>console.log("Example Extension Admin JS loaded!");</script>';
});


// CUSTOM BLOCK RENDERING
// Process custom Editor.js blocks before they are converted to HTML.
// This is called for every block on the page.
ExtensionLoader::addHook('parser.block', function($block, $context) {
    if (($block['type'] ?? '') === 'exampleBlock') {
        $text = htmlspecialchars($block['data']['text'] ?? 'Default text');
        
        // Setting '_rendered' tells the core parser to skip its default processing
        // and just output this HTML string directly.
        $block['_rendered'] = '<div class="pw-ext-example-block"><strong>Extension Block:</strong> ' . $text . '</div>';
    }
    return $block;
});


// PAGE SETTINGS INJECTION
// Add custom fields to the "Page Settings" page in the editor.
// You must append your HTML to the incoming `$html` string and return it.
ExtensionLoader::addHook('page_settings.fields', function($html, $context) {
// The value is auto-populated by Javascript (pageSettings.js)
// as long as your input has the class 'pw-ext-input'.
// The 'name' attribute must map exactly to where you want it saved in pageData.Settings.
    $html .= '
    <hr class="pw-separator">
    <h3 class="pw-settings-heading">' . __('ext.example-extension.tab_label') . '</h3>
    <div class="pw-setting-field">
        <label class="pw-setting-label">' . __('ext.example-extension.page_meta_label') . '</label>
        <p class="pw-hint-compact">' . __('ext.example-extension.page_meta_desc') . '</p>
        <input type="text" name="example_meta" class="pw-input pw-w-full pw-ext-input">
    </div>';
    return $html;
});


// SAVE PAGE SETTINGS
// Safely grab the data sent by your custom inputs from the raw POST request
// and store it into the page's $pageData array before it gets saved as JSON.
ExtensionLoader::addHook('page_settings.save', function($pageData, $context) {
    $post = $context['post'] ?? [];
    if (isset($post['example_meta'])) {
        $pageData['Settings']['example_meta'] = trim($post['example_meta']);
    }
    return $pageData;
});


// GLOBAL SETTINGS TAB
// Adds a dedicated tab in the global Settings dashboard.
// The 'file' points to a PHP script that outputs the HTML content for your tab.
ExtensionLoader::addHook('settings.tabs', function($tabs) {
    $tabs[] = [
        'id'    => 'example', // Automatically prefixed -> 'pw-tab-example'
        'label' => __('ext.example-extension.tab_label'),
        'icon'  => 'mdi:puzzle-star-outline',
        'file'  => __DIR__ . '/settings.php',
    ];
    return $tabs;
});


// CUSTOM API ROUTES
// Register new API endpoints. They will be accessible via:
// api.php?action=example_action
ExtensionLoader::addHook('api.routes', function($routes) {
    $routes['example_action'] = __DIR__ . '/api.php';
    return $routes;
});

// Protect the route so only logged-in admins can access it.
// Use 'api.public_actions' if you want anonymous users to access it.
ExtensionLoader::addHook('api.admin_actions', function($actions) {
    $actions[] = 'example_action';
    return $actions;
});


// FRONTEND HTML MANIPULATION
// Runs right before the final HTML is sent to the browser.
// Allows appending, prepending, or using str_replace() to modify the entire page.
ExtensionLoader::addHook('renderer.html', function($html, $context) {
    $pageData = $context['page'] ?? [];
    $meta = trim($pageData['Settings']['example_meta'] ?? '');
    
    // Load the global extension settings (in this case the greeting)
    $extSettings = getExtensionSettings('example-extension');
    $greeting = trim($extSettings['greeting'] ?? '');
    
    if ($meta !== '' || $greeting !== '') {
        $bannerContent = '';
        if ($greeting !== '') {
            $bannerContent .= '<strong>Global Greeting:</strong> ' . htmlspecialchars($greeting) . '<br>';
        }
        if ($meta !== '') {
            $bannerContent .= '<strong>Page Metadata:</strong> ' . htmlspecialchars($meta);
        }

        // Output a banner at the bottom of the page
        $banner = '<div style="background: var(--pw-primary); color: white; padding: 10px; text-align: center; margin-top: 20px;">
            ' . $bannerContent . '
        </div>';
        
        // Safely inject it before the closing footer or append it
        if (str_contains($html, '</footer>')) {
            $html = str_replace('</footer>', $banner . '</footer>', $html);
        } else {
            $html .= $banner;
        }
    }
    
    return $html;
});


// EDITOR.JS TOOLS
// Register new tools for Editor.js.
// Important: add your JS file to "editor_plugins" in meta.json.
ExtensionLoader::addHook('editor.tools', function($tools) {
    // The key ('exampleBlock') must match what you look for in parser.block
    // The class ('ExampleBlock') must match the JS class exposed to window in your plugin JS.
    $tools['exampleBlock'] = [
        'class' => 'ExampleBlock',
        'shortcut' => 'CMD+SHIFT+E'
    ];
    return $tools;
});