Skip to content

Layout Customization

Poweradmin allows you to customize various layout aspects to better fit your workflow. These settings are configured in the settings.php file under the interface section.

Poweradmin looks for two optional snippet files inside the active theme: custom/header.html and custom/footer.html. When a file exists, its content replaces the visible logo/title area at the top of the page or the footer line at the bottom. They do not inject content into the page <head> element (see Injecting content into <head> below if you need that for analytics or custom meta tags).

Configuration

No setting switches the snippets on and no theme change is needed - the files are picked up from whichever theme you already run, so the path is templates/<active theme>/custom/. On a stock install that is templates/default/custom/.

The theme-related settings themselves:

return [
    'interface' => [
        'theme' => 'default',  // Theme whose custom/ directory is used ('default' or 'modern')
        'style' => 'light',   // Options: 'light', 'dark'
        'theme_base_path' => 'templates', // Base path for theme templates
        'title' => 'DNS Server 1', // Custom title to distinguish multiple server instances
    ],
];

Tip: If you manage multiple DNS servers, customize the title setting to easily distinguish between them. For example, use server names like "Production DNS", "ns1.example.com", or "DNS Server - East Coast" to quickly identify which server you're managing.

Creating the Snippet Files

  1. Create a custom directory inside your active theme

  2. Add either or both files (see sections below)

    templates/
└── default/
    └── custom/
        ├── header.html
        └── footer.html

Custom Header (templates/default/custom/header.html)

<!-- Your custom header content goes here -->
<img src="assets/your-logo.png" height="32">
<span class="fs-4">Your Custom Title</span>

<!-- Your custom footer content goes here -->
<p>© 2025 Your Organization - Powered by <strong>Poweradmin</strong></p>

Here are examples of custom templates in action:

Custom Header File Structure

Custom Header Structure

Custom Footer Example

Template Variables

The following template variables are available in your custom templates:

Header Template Variables

  • {{ iface_title }} - Application title from configuration settings (appears in browser tab and header)
  • {{ iface_style }} - Current theme style (light or dark)
  • {{ file_version }} - Opaque cache-busting token for asset URLs. Not a timestamp: it is a truncated HMAC over the Poweradmin version and a content digest of the bundled assets, so it stays stable until an asset or the version changes
  • {{ version }} - Poweradmin version
  • {{ iface_style }} - Current theme style
  • {{ file_version }} - Opaque cache-busting token for asset URLs. Not a timestamp: it is a truncated HMAC over the Poweradmin version and a content digest of the bundled assets, so it stays stable until an asset or the version changes

Examples

Corporate Branding Header

<img src="assets/corporate-logo.png" height="40">
<span class="fs-4 ms-2">Corporate DNS Management Portal</span>

<div class="d-flex flex-column">
  <p class="mb-1">© 2025 Your Organization - DNS Management</p>
  <p class="mb-0 small">
    <a href="https://support.example.com" class="text-decoration-none">Support</a> |
    <a href="https://docs.example.com" class="text-decoration-none">Documentation</a> |
    <a href="mailto:dns-admin@example.com" class="text-decoration-none">Contact</a>
  </p>
</div>

Poweradmin renders the favicon (<link rel="icon">) and the header logo from two interface settings (added in 4.4.0):

  • favicon_path: Path or URL to a custom favicon. Empty uses the bundled favicon.ico. Default: ''
  • logo_path: Path or URL to a custom header logo image. Empty uses the bundled assets/logo.png. Default: ''
return [
    'interface' => [
        'favicon_path' => '/branding/favicon.png',
        'logo_path' => 'https://cdn.example.com/branding/dns-logo.svg',
    ],
];

Absolute URLs (https://cdn.example.com/...) and protocol-relative URLs (//cdn.example.com/...) are used as-is. Path values are served from the Poweradmin web root and automatically get base_url_prefix applied, so /branding/favicon.png works unchanged whether Poweradmin runs at the domain root or in a subfolder.

Notes:

  • logo_path only applies to the standard header markup. If you use a custom header template (see above), the template controls its own logo.
  • Files placed inside the Poweradmin web root can be overwritten by upgrades. With Docker, bind-mount your branding files (e.g. -v ./favicon.ico:/app/favicon.ico) or point the settings at an external URL.
  • On versions before 4.4.0, replace favicon.ico in the Poweradmin web root (works for installs served at the domain root, browsers request /favicon.ico by convention) or add a <link rel="icon" href="..."> tag through the header template fork described in Injecting content into <head>.

UI Element Positioning

Form Element Positioning

Control the positioning of key UI elements:

  • position_record_form_top: Place the "Add record" form at the top of the page. Default: true
  • position_save_button_top: Place the "Save changes" button at the top of the page. Default: false
return [
    'interface' => [
        'position_record_form_top' => true,
        'position_save_button_top' => true,
    ],
];

Content Display Options

Configure which information is displayed in the user interface:

  • show_record_id: Show record ID column in edit mode. Default: false
  • show_zone_comments: Show zone comments. Default: true
  • show_record_comments: Show record comments. Default: false
  • display_serial_in_zone_list: Show serial number in zone list. Default: false
  • display_signed_serial_in_zone_list: Show the serial as served by PowerDNS with SOA-EDIT applied (the "signed" serial) in zone lists. Requires the API backend (dns.backend = 'api') and PowerDNS 4.3+ (v4.5.0+). Default: false
  • display_template_in_zone_list: Show template information in zone list. Default: false
  • display_owner_in_zone_list: Show owner column in zone lists (v4.5.0+). Default: true
  • display_group_in_zone_list: Show group column in zone lists (v4.5.0+). Default: true
  • show_zone_record_count: Show record count column in zone lists (v4.5.0+). Each user can override this in their preferences. Default: true. In API backend mode this costs one PowerDNS request per zone shown on the page; turn it off to skip those
return [
    'interface' => [
        'show_record_id' => true,
        'show_zone_comments' => true,
        'show_record_comments' => true,
        'display_serial_in_zone_list' => true,
        'show_zone_record_count' => true,
    ],
];

Page Width

By default pages are rendered in a fixed-width container, which leaves unused margins on wide monitors. Enabling the full-width layout lets the content span the entire browser window, which gives zone lists and other wide tables more room for long zone names.

  • wide_layout: Use the full browser width instead of a fixed-width page (v4.5.0+). Default: false
return [
    'interface' => [
        'wide_layout' => true,
    ],
];

This is a site-wide default. Each user can override it under Preferences -> Display Settings -> Full browser width, so individual users can opt in or out regardless of the configured value.

Pagination

Control how many items appear per page:

  • rows_per_page: Number of items displayed per page. Default: 10
return [
    'interface' => [
        'rows_per_page' => 20,
    ],
];

Zone Editing Features

Enable or disable special editing features:

  • add_reverse_record: Add the checkbox option to create PTR records from A/AAAA record view. Default: true
  • add_domain_record: Add the checkbox option to create A/AAAA records from PTR record view. Default: true
return [
    'interface' => [
        'add_reverse_record' => true,
        'add_domain_record' => true,
    ],
];

Notes

  • The custom templates use a simple templating system
  • Changes may be overwritten during updates - keep backups of your custom files
  • Custom header/footer templates render inside the page body (logo area / footer line). Scripts placed here run on every page but are not in <head>. For analytics tags, see the next section.

Injecting content into <head>

Tracking snippets (Matomo, Plausible, Google Analytics) and additional meta tags need to live inside the page <head> element, not in the custom header template. Poweradmin does not expose a configuration setting for this - it gives you two supported paths instead. (For favicons, use the favicon_path setting described in Custom Favicon and Logo - no <head> injection needed since 4.4.0.)

Option 1: Fork the theme header template (simple, but upgrade-aware)

  1. Copy your active theme's header to a custom theme directory, e.g.:

    mkdir -p templates/custom
cp templates/default/header.html templates/custom/header.html

  2. Set 'theme' => 'custom' in the interface section of settings.php. Unlike the custom/header.html snippet described earlier, this path forks the whole header template, so the theme really does have to change.

  3. Open templates/custom/header.html and paste your snippet immediately before </head>. For example, a Matomo <noscript> tracker:

        <script type="text/javascript" src="{{ base_url_prefix }}/assets/formBusy.js?time={{ file_version }}"></script>
    <noscript><p><img src="https://analytics.example.com/matomo.php?idsite=23" style="border:0;" alt="" /></p></noscript>
</head>

    The full JavaScript tracker from Matomo/GA/Plausible goes in the same place.

  4. Track the upstream templates/default/header.html (or templates/modern/header.html) on each Poweradmin upgrade. If it changes, re-apply your edit on top of the new version.

Option 2: Reverse-proxy injection (upgrade-safe)

If Poweradmin sits behind Nginx or Apache, inject the snippet at the proxy layer so application updates never touch it. Example for Nginx with ngx_http_sub_module:

location / {
    proxy_pass http://poweradmin_upstream;
    sub_filter '</head>' '<script src="https://analytics.example.com/matomo.js" async></script></head>';
    sub_filter_once on;
    sub_filter_types text/html;
}

This is the recommended path for production deployments because it survives Poweradmin upgrades with no patching.

Why no configuration setting?

A custom_head_html config value would mean pasting a multi-line HTML/JavaScript block into config/settings.php. The configuration file is intended for short scalar settings, so HTML injection lives in templates or at the proxy layer instead.