Documentation · Version 1.0.0
Set up your
announcement bar.
Announcement Pilot is a free system plugin for Joomla 5.4. It publishes one announcement bar on the frontend of your site and stores every setting in Joomla’s own extension parameters.
1. Install and enable
- Download the plugin ZIP.
- In Joomla Administrator open System → Install → Extensions and upload the ZIP under Upload Package File.
- Open System → Manage → Plugins, search for System - Announcement Pilot and open it.
- Set Show the announcement bar to Yes, write your message and save.
- Open the frontend of your site to see the result.
The installer refuses Joomla versions below 5.4 or 6.0 and above, and PHP versions below 8.1. It does not modify template files.
2. Write the announcement
| Field | What it does |
|---|---|
| Show the announcement bar | Master switch. The bar renders only when this is Yes and the message is not empty. Default: No. |
| Starting design | Fills the message, button text and four colours from a preset. Your own values override the preset field by field. Default: None. |
| Announcement text | Plain text up to 500 characters. HTML is removed. Line breaks are preserved. Default: “Welcome! Discover something you will love.” |
| Button text | Optional, up to 60 characters. The button appears only when both button text and destination link are filled. |
| Destination link | A site path such as /shop or a full https:// address. Protocol-relative links, script links and links containing spaces are rejected. |
3. Adjust the appearance
| Field | Range and default |
|---|---|
| Background colour | Six-digit hex. Default #ff5a1f. |
| Text colour | Six-digit hex. Default #18181b. |
| Button background | Six-digit hex. Default #18181b. |
| Button text colour | Six-digit hex. Default #ffffff. |
| Desktop text size | 12–24 px. Default 16 px. |
| Mobile text size | 12–24 px. Default 16 px. Applies below 768 px. |
| Vertical spacing | 8–32 px. Default 14 px. Applied above and below the message. |
| Bold announcement text | Uses weight 700 for the message and button. Default: No. |
Invalid colours fall back to the plugin defaults. Out-of-range numbers are clamped to the nearest allowed value.
4. Placement and behaviour
Position
Top of page inserts the bar immediately after the opening <body> tag, above your template header. Bottom of page inserts it immediately before </body>, after your footer.
Show on
All devices always shows the bar. Desktop only hides it below 768 px. Mobile only hides it at 768 px and wider. The check is pure CSS, so it adapts immediately when the window is resized.
Visitors can close the bar
Adds a 44 × 44 px close button with an accessible label. Closing hides the bar for the current page view only. The plugin sets no cookie and writes nothing to local or session storage.
Analytics
The dashboard counts impressions and button clicks for the last 30 days and shows the click-through rate and the best day. Only two integers per day are stored in the site’s database; no IP address, cookie, user agent or visitor profile is stored. The counter respects the browser’s Do Not Track setting. The same numbers are available on the Analytics tab in the plugin dashboard.
5. Starting designs
| Design | Background | Text | Button |
|---|---|---|---|
| Welcome | #fff7ed | #7c2d12 | #c2410c on #ffffff |
| Free shipping | #18181b | #ffffff | #ffffff on #18181b |
| Sale | #ff5a1f | #18181b | #18181b on #ffffff |
| Store update | #fef3c7 | #78350f | No button |
A preset is a starting point, not a lock. Clearing a field and choosing a different preset applies that preset’s value. Typing a value always wins.
6. Cache, ordering and updates
After saving, open the frontend. If you use Joomla’s page cache, a full-page cache or a CDN, clear it once before expecting the new bar.
If the bar does not render at all, open System → Manage → Plugins and place System - Announcement Pilot after System - Page Cache in the ordering. The plugin needs to run after the page body has been assembled.
Updates use Joomla’s native update system. The manifest points to updates.xml; when a newer version is published it appears in System → Update → Extensions. Updates keep your saved settings.
7. Compatibility
- Joomla: 5.4 only. The installer blocks other versions.
- PHP: 8.1 or newer. Tested with PHP 8.3.
- Templates: standard Joomla 5 templates, including Cassiopeia. The bar is inserted into the document body and styled only by its own scoped stylesheet.
- Editor: Joomla’s default editor and TinyMCE are unaffected; the message is plain text.
- Multilingual sites: the settings page is translated into English. The bar text is whatever you type.
Third-party templates that rebuild the page outside Joomla’s normal document render, or that strip content inserted after <body>, may need a different placement. Test on staging.
8. Reviewer test
- Install the ZIP on a disposable Joomla 5.4 site with PHP 8.1+.
- Enable System - Announcement Pilot.
- Set Show the announcement bar to Yes, choose the Sale design, set the message to “JED review bar” and save.
- Open the frontend. Confirm the bar appears above the template header with the sale colours.
- Confirm the close button hides the bar. Reload the page and confirm it returns (no cookie).
- Change Position to Bottom and confirm the bar moves below the footer.
- Change Show on to Desktop only and narrow the window below 768 px; the bar must disappear.
- Set Show the announcement bar to No and confirm the bar is gone.
- Inspect the page source. Confirm the only added assets are
/media/plg_system_announcementpilot/css/storefront.cssand/media/plg_system_announcementpilot/js/storefront.js, both from the site itself.
No account, API key, external service or payment method is required at any point.
9. Uninstall
Open System → Manage → Extensions, select System - Announcement Pilot and uninstall it. Joomla removes the plugin, its language files, the media/plg_system_announcementpilot folder and the analytics table. The bar disappears with it. Pro is a separate plugin; uninstall it separately.
10. Troubleshooting
The settings page shows raw language keys
The language files were not installed. Reinstall the ZIP; do not rename files inside it.
The bar is invisible on mobile
Check Show on. “Desktop only” hides the bar below 768 px by design.
The bar covers my fixed header
The bar is inserted in normal document flow, so a fixed header can overlap it. Choose bottom placement or adjust the template’s header offset. The plugin does not edit template CSS.
The button does not appear
Both Button text and Destination link must be filled. A rejected link (for example javascript:) is treated as empty.
The bar shows the old message
Clear Joomla cache, page cache and CDN cache. Check the plugin ordering described in section 6.
Still stuck? Contact PLANO with your Joomla, PHP and plugin versions.
Optional paid edition
11. Announcement Pilot Pro
The free plugin on this page is complete on its own. Announcement Pilot Pro is a separate Joomla plugin that adds message rotation, page and language targeting, scheduled windows and a countdown. It is sold through PLANO’s licensing site, not through Joomla or this download page.
The Pro plugin is a standalone superset of the free plugin. If both are installed and enabled, Pro removes the free bar from the rendered page and prints its own, so visitors never see two bars. Your free settings are not deleted.
Buy and download
- Open the Announcement Pilot pricing page and compare Starter and Growth.
- Choose monthly or yearly. Eligible first subscriptions include a 7-day trial; a card is required.
- Finish checkout on Stripe. Stripe is the merchant of record and handles tax. PLANO never sees or stores card details.
- Open the license account with the email used at checkout. Your license key and the Pro ZIP are listed there.
Prices, currency, taxes and trial eligibility are displayed on the pricing page and again in Stripe Checkout. This guide deliberately does not repeat amounts that can change.
Install and activate
- In Joomla Administrator open System → Install → Extensions and upload the Pro ZIP. The installer accepts Joomla 5.4 and PHP 8.1 or newer only.
- Open System → Manage → Plugins → System - Announcement Pilot Pro.
- Paste the license key into License key and save. The site sends the key, its own site URL and the plugin version to
licenses.weareplano.gr. Nothing else is sent. - The save message confirms the tier. If activation fails, the error is shown and the free features keep working.
- Configure the bar and the Pro fields, then save again.
Activation is tied to one production site per license. Development hosts such as localhost, private IP addresses, .local, .test and staging.* do not consume the site slot. Move a license between sites by deactivating the old site in the portal.
The license token is signed with Ed25519 and verified locally with PHP’s sodium extension. The token is stored in the plugin’s Joomla parameters. No token means no paid fields; the free bar still renders.
Starter fields
| Field | What it does |
|---|---|
| Additional messages | One message per line. The main announcement counts as the first, up to eight unique messages in total. HTML is removed and duplicates are skipped. |
| Seconds per message | 6–60 seconds, default 8. The browser swaps the visible message on that interval. Visitors can pause or advance messages. Rotation runs locally; there is no polling. |
| Show on these paths | Comma-separated site paths such as /shop, /sale/*. * matches any characters. Empty means every page. Matching uses the path Joomla already resolved, case-insensitively and without a trailing slash. |
| Show for these languages | Comma-separated language tags or prefixes, such as en-GB, el. The bar matches the current Joomla language or a browser Accept-Language entry. Empty means every language. |
Growth fields
| Field | What it does |
|---|---|
| Start showing at | Optional date and time in your site timezone. Before it, the bar is not printed at all. |
| Stop showing at | Optional date and time in your site timezone. At or after it, the bar disappears on the next request. |
| Show a countdown | Adds a live “Ends in …” badge inside the bar. When it reaches zero the bar hides itself, or switches to the end message below if you chose not to hide it. |
| Countdown ends at | Optional deadline for the countdown. Empty uses Stop showing at. Both must be in the future for the bar to render. |
| Message after the countdown | Plain text shown when the countdown reaches zero, if the bar is not hidden. Default “This offer has ended.” |
| Hide the bar when the countdown ends | Yes hides the bar; No switches it to the end message. Default: Yes. |
A practical Growth setup is: main message, two extra messages, /shop targeting and a countdown one week out. Test with your own content on staging first.
What each tier unlocks
| Feature | Free plugin | Starter | Growth |
|---|---|---|---|
| One bar, designs, colours, placement | Yes | Yes | Yes |
| Message rotation (up to 8) | — | Yes | Yes |
| Page and language targeting | — | Yes | Yes |
| Scheduled start and stop | — | — | Yes |
| Countdown, end message and automatic expiry | — | — | Yes |
| Pause or advance messages | — | Yes | Yes |
| Local impressions, clicks and CTR | Yes | Yes | Yes |
Paid fields are ignored on the free tier. They are not deleted, so a renewal restores the previous campaign without retyping it.
Updates
Open the license account to download the current Pro ZIP. An Announcement Pilot licence shows two downloads: the WordPress/Wix add-on and Download for Joomla. Choose the Joomla one. The free plugin continues to update through Joomla’s native update system from updates.xml. Pro is a separate paid package and is not listed in Joomla’s public update feed.
Expiry, refunds and cancellation
Each signed token carries an expiry date. While it is valid, Pro checks in at most every 12 hours when it is close to expiry. If the licensing service cannot be reached, the last valid token is honoured until it expires. That means a short outage never switches off a working bar.
When the subscription ends or is refunded, the token expires. Pro then hides the paid fields and keeps rendering the free bar. Nothing is deleted and the backend keeps working. While the key is still saved, Pro retries the check at most once an hour; clear the key to stop those requests entirely. Renew in the portal to restore the paid features.
Cancel or change billing in the portal or through the billing link in your purchase email. Refund handling follows the terms shown at checkout.
What Pro sends, and when
Pro contacts https://licenses.weareplano.gr/v1/licenses/activate, /check or /deactivate with the license key, the site root URL and the plugin version. It does this when you save a key, when the token is missing, and when the token is within three days of expiry. A valid, comfortably unexpired token is verified locally and causes no request. When the saved key is rejected, retries are limited to once an hour. Clearing the key stops activation checks. Rotation and countdowns never contact the server. See the privacy page for the full disclosure.
Pro troubleshooting
The paid fields are ignored. Open the plugin settings. The save message names the tier or explains why activation failed. Re-save the key. If the message says the key belongs to another product, use the Announcement Pilot key from your portal.
The key was accepted but the tier is wrong. Starter and Growth are separate subscriptions. Upgrade in the portal, then save the plugin again so it fetches a new token.
Both bars appear. Pro removes the free bar by its element ID in the rendered HTML. If your template or a third-party plugin outputs a cached copy of the free bar outside Joomla’s normal render, disable the free plugin. The two plugins are not meant to run together on a cached page.
I moved the site to a new domain. Deactivate the old site in the portal, then save the key on the new domain. A key is valid for one production site at a time.