HTML Structure Edit

Drop analytics, chat widgets, verification tags or custom styling into every page of your Blesta site without touching a single template file.

What it does

Adding a tracking pixel, a live chat script or a bit of custom CSS to Blesta usually means editing theme files by hand, and re-applying those edits every time you update Blesta. HTML Structure Edit removes that entirely: paste your markup into three boxes on one settings page, and it is injected into every client-facing page automatically, with nothing to touch in your theme and nothing to redo after an upgrade. A built-in code editor, live tags for the current client, company and staff member, and a couple of helper functions make it flexible enough for anything from a Google Analytics snippet to a signed chat-widget identity.

Key features

• Three Injection Points on Every Page: Paste markup, styles or scripts into the end of the page head, the start of the body or the end of the body, and it appears on every client-facing page automatically.
• No Template Edits Required: Nothing to paste into a theme file and nothing to re-apply after a Blesta upgrade.
• Syntax-Highlighted Code Editor: Each section is edited in a built-in code editor with line numbers, HTML/CSS/JavaScript highlighting and bracket matching, so long snippets stay readable.
• Personalise With Live Tags: Insert the logged-in client, the company record and its ID, the logged-in staff member and the current page address straight into your markup.
• Built-In Helper Functions: Encode and decode JSON and generate HMAC signatures inline in your snippet, which is exactly what live-chat and support widgets need for verified visitor identity.
• Master On/Off Switch: Turn all injection off with one checkbox and back on again later, so you can disable third-party scripts while debugging without losing the code you wrote.
• Optional Admin-Area Injection: By default only client-facing pages are touched. Tick one box and your code is injected into the staff area too, for internal tooling or staff-side tracking.
• A Bad Snippet Never Takes the Site Down: If one of your snippets fails, that section is skipped and the page still renders, so a typo in a tracking tag cannot lock you out of the very pages you need to fix it from.
• Fully Translatable, Per-Company Configuration: Every label ships in editable language files, and each company on a multi-company install runs its own independent settings.

Installing HTML Structure Edit

Before you start

• If you are on the leased (subscription) licence, the Blesta Club Subscription Manager must be installed and your subscription active. The owned and owned-source licences have no such requirement.

1. Upload the files

Upload the extension folder into your Blesta installation so it lands under your Blesta directory at:

plugins/html_structure_edit/

For example, on a typical install: /var/www/html/blesta/plugins/html_structure_edit/

2. Install it in Blesta

1. Log in to your Blesta admin area with a staff account that has the Plugins permission, including Install Plugin and Manage Plugin (found under the Settings group in Manage Staff Groups).
2. Go to Settings > Company > Plugins and click the Available tab.
3. Find HTML Structure Edit in the list and click Install.

3. Configure it

1. From the Installed tab, click Manage next to HTML Structure Edit.
2. Enter the HTML, CSS or JavaScript you want injected into the page head, the start of the body, or the end of the body. Each box is a syntax-highlighted code editor.
3. Leave Enable injection on client-facing pages checked (it's on by default) so your code goes live on save. Only tick Also inject into the admin area if you also want your code to run in the staff portal.
4. Click Save.

This plugin registers no cron tasks and reaches no external API - once you save a section, it starts appearing on your pages immediately.

You're ready to go - see the usage guide for a walkthrough of day-to-day use.

Updating HTML Structure Edit

Upgrading works just like installing: upload the new files over the old ones, then run the upgrade from the same page you installed it on.

1. Back up your current extension files first - good practice before any upgrade.
2. Upload the new version over the existing folder, replacing the old files.
3. Log in to your Blesta admin area and go to Settings > Company > Plugins.
4. Find HTML Structure Edit and click Upgrade to run the upgrade.

Version-specific notes

• v2.0.0: Adds two new settings - Enable injection on client-facing pages and Also inject into the admin area - plus a syntax-highlighted code editor for the three sections and the <%company%>, <%staff%> and <%uri%> template tags. Both new settings default to match your current behaviour (injection stays on for client-facing pages, admin pages stay untouched), so nothing you've already configured changes until you deliberately flip one of them. This version also stops the plugin from ever injecting into its own settings page, so a mistake in your code can no longer lock you out of the page that fixes it.
• v1.1.0: Fixes a blank settings page that could appear when your licence was invalid, and a fatal error that a malformed function tag could cause on every client-facing page. If you're upgrading from v1.0.0 or earlier, your existing sections and settings carry over unchanged.

If your custom code breaks the admin area

The plugin never injects into its own settings screen, so Settings > Company > Plugins > Manage for HTML Structure Edit is always reachable. Go there directly (type the URL if the navigation is unusable), untick Enable injection on client-facing pages or clear the offending section, and save.

If the admin area cannot be reached at all, one SQL statement against your Blesta database turns injection off:

UPDATE html_structure_edit SET enabled = 0 WHERE company_id = 1;

Replace 1 with your company id. To clear the code instead, use SET head = '', body_start = '', body_end = ''.

Using HTML Structure Edit

For your staff

Manage HTML Structure Edit

Go to Settings > Company > Plugins, find HTML Structure Edit in your installed plugins, and click Manage. This is the only screen the plugin adds to your admin area.

Two toggles sit above the three code sections:

• Enable injection on client-facing pages - the master switch. When unchecked, none of your code is injected anywhere, without you having to clear the three sections or uninstall the plugin. It's on by default.
• Also inject into the admin area - by default your code is injected only into the client-facing storefront. Turn this on to also inject it into the Blesta staff portal. It's off by default.

Below the toggles are three code editors with line numbers, syntax highlighting and bracket matching:

• Head - injected at the end of the page's <head> tag. Good for CSS and tags that need to load early, like verification meta tags or analytics snippets.
• Body Start - injected right after the opening <body> tag. Good for banners or anything that should appear before the rest of the page content.
• Body End - injected just before the closing </body> tag. Good for chat widgets, floating buttons and scripts that don't need to block the page from loading.

An Available Tags reference and an Available Functions reference sit alongside the editors, listing every tag and function you can use (see below). Click Save changes when you're done.

Note: admin-area pages have no logged-in client, so the <%client%> tag resolves to an empty value there. The <%company%>, <%company_id%>, <%staff%> and <%uri%> tags still work. Don't template client-specific fields into code meant only for the admin area.

Template tags

Insert dynamic values into any section with <% ... %> tags:

• <%client%> - the logged-in client record; used bare it prints the client's name (empty when nobody is logged in, and on admin pages), or use a property directly, e.g. <%client.first_name%> or <%client.email%>.
• <%company_id%> - the current company id.
• <%company%> - the current company record; used bare it prints the company name, or use a property directly, e.g. <%company.name%> or <%company.hostname%>.
• <%staff%> - the logged-in staff record; used bare it prints the staff member's name (only populated on admin pages when admin injection is enabled), or use a property directly, e.g. <%staff.first_name%>.
• <%uri%> - the current page's request address, so a snippet can vary by page.

Tags are inserted exactly as stored - escaping is yours to do. Because raw output is the whole point of this plugin, tag values are not HTML-escaped. A field a client controls (their first name, company name or address) printed straight into your markup renders as markup. If you're printing a client-supplied value into HTML, append the force_escape filter: <%client.first_name|force_escape%> (|e is the same filter under a shorter name). Values you control (<%company_id%>, <%uri%>) don't need it.

Use force_escape, not escape - the bundled template engine runs |escape twice and prints < where you wanted <. Still safe, just wrong-looking.

Don't print client-controlled values inside a <script> block. Neither |escapejson nor the json_encode function (below) escapes a </script> sequence, so a value containing one closes your script tag early. Put the value in a data- attribute with |force_escape and read it from JavaScript instead.

Helper functions

Call a small set of helper functions with <;function<:>arg1<:>arg2;> syntax:

• <;json_encode<:>value;> - JSON-encodes the value.
• <;json_decode<:>json;> - decodes a JSON string.
• <;hash_hmac<:>algo<:>data<:>key;> - an HMAC signature, e.g. <;hash_hmac<:>sha256<:><%client.first_name%><:>some_secret;>.

A malformed function or tag never takes the page down. A function call that fails (an unsupported hash_hmac algorithm, or too few arguments) falls back to its own raw <;...;> text with a comment noting the failure - other tags and functions in the same section still resolve normally. A <% ... %> tag that fails to parse falls the whole section back to its raw, un-rendered content with a comment noting the failure.

For your clients

There's nothing for your clients to configure. Whatever you save in the three sections simply appears on the pages they visit - a banner, a chat widget, custom styling - exactly as you wrote it, personalised with their own name or company details if you used the template tags.

Good to know

• That "never takes the page down" guarantee covers the PHP layer only. Malformed HTML or JavaScript in a section is injected exactly as written, so it can still break the rendered page in a browser. If you enable Also inject into the admin area, that includes the staff portal.
• The plugin never injects into its own settings screen (Settings > Company > Plugins > Manage), so you can always get back there to clear or disable the offending code, even when the rest of the admin area is broken. Go there directly if the navigation is unusable.
• If the admin area is unreachable for any other reason, the last resort is one SQL statement against your Blesta database: UPDATE html_structure_edit SET enabled = 0 WHERE company_id = 1; (replace 1 with your company id), or SET head = '', body_start = '', body_end = '' to clear the sections outright.
• Settings are per company, so on a multi-company install each company runs its own independent sections and toggles.