Newswidget Laravel Package

Getting Started

bolt/newswidget is a small Bolt CMS extension that adds a dashboard widget showing the latest Bolt project news. It is admin-side only: it does not add frontend routes, Twig functions, or content fields. Treat it as dashboard chrome rather than application logic.

Minimal steps from a Bolt project root:

composer require bolt/newswidget

Then enable the extension through the Bolt admin Extensions screen, or with the extension-enable console command for your Bolt version (the exact command differs between Bolt 4 and Bolt 5). Clear caches afterward:

php bin/console cache:clear

Where to look first:

• vendor/bolt/newswidget/composer.json — confirms the Bolt version constraint and the extra.bolt / extension registration metadata.
• vendor/bolt/newswidget/src/ — the extension class and the widget class. The widget class is the one implementing Bolt’s widget interface.
• vendor/bolt/newswidget/templates/ — the Twig template used to render the news list. This is the file you are most likely to override.
• Any bundled config or README — look for a feed URL, cache TTL, or item count setting.

First use case: install, enable, log into the Bolt admin, and confirm the “Bolt News” tile appears on the Dashboard. If it does not, check that the extension is enabled and that the widget is registered for the dashboard zone.

Implementation Patterns

Install-and-forget dashboard tile. The common path is to install it once and leave it alone. It is useful for editors and developers who want release/news visibility without leaving the admin. No application code changes are required.

Configuration overrides. If the extension exposes settings, they are usually read from a Bolt extension config file such as config/extensions/bolt.newswidget.yaml (Bolt 4/5) or the equivalent app/config/extensions/ path in older Bolt versions. Typical knobs are feed URL, refresh interval, cache lifetime, and number of items. Prefer config over editing vendor files.

Template override. Copy the widget template from vendor/bolt/newswidget/templates/ into your project’s template override path and adjust markup/CSS there. This keeps upgrades safe. Keep the override minimal: a heading, a list of links, and a timestamp.

Use it as scaffolding for your own widget. The most valuable day-to-day use for a small extension like this is as a reference implementation. A Bolt dashboard widget generally has:

// Illustrative shape — confirm the exact interface for your Bolt version.
class NewsWidget implements WidgetInterface
{
    public function getName(): string
    {
        return 'bolt_news';
    }

    public function getTitle(): string
    {
        return 'Bolt News';
    }

    public function getContent(): string
    {
        // Fetch cached feed data, then render a Twig template.
    }
}

Clone the pattern for internal dashboards: deploy status, open support tickets, recent form submissions, or a “what changed this week” changelog. Register the widget in the extension class or service definition, then render it in the dashboard zone.

Cache the remote call. If you copy the feed-fetching approach, wrap the HTTP request in a cache layer with a sensible TTL (15–60 minutes). The dashboard is loaded frequently by editors; it should never block on a slow external feed. Set explicit HTTP timeouts and fall back to a cached or empty state.

Compose the dashboard deliberately. Bolt dashboards support multiple widgets/zones. If the news tile is noisy, move it below operational widgets or restrict it to a developer-facing dashboard rather than the default editor dashboard.

Gotchas and Tips

• Dashboard latency is the main risk. Any widget that performs a synchronous remote request can slow the admin. Verify timeouts and caching before rolling it out to a large editorial team.
• Silent failures are common. If the upstream news feed changes format, moves, or is blocked, the widget often renders empty rather than throwing a visible error. Add a fallback message and check logs if the tile goes blank.
• Escape remote content. News feeds are untrusted input. If you customize the template, ensure titles/links are escaped and that you are not rendering raw remote HTML.
• Iframe/CSP issues. Some widget implementations embed a remote page. If your Bolt admin has a restrictive Content-Security-Policy or the remote site sends X-Frame-Options, the tile will fail only in the browser. Check the browser console, not just PHP logs.
• Version compatibility matters more than stars. Widget APIs have changed across Bolt major versions. Pin the package version in composer.json and confirm the constraint matches your Bolt major version before upgrading Bolt.
• Clear caches after install and after config changes. Extension registration, service definitions, and Twig template overrides are all cache-sensitive in Bolt/Symfony.
• Do not edit vendor files. Use config and template overrides; otherwise the next composer update wipes your changes.
• Low-maintenance dependency. With a small star count and a narrow scope, assume minimal ongoing support. If the widget becomes important, vendor the small amount of code into your own project extension instead of depending on upstream.
• Debugging checklist: composer show bolt/newswidget, verify the extension is enabled (bin/console extension list), check var/log/ for HTTP/feed errors, clear cache, then temporarily disable other dashboard widgets to rule out conflicts.
• Extension points to prefer: config file, Twig template override, and widget registration. Avoid monkey-patching the widget class.