Slidernav Widget Laravel Package

Getting Started

This is a Victoire DCMS widget bundle, not a standalone library. That means nothing in it works until you have a running Victoire installation (Victoire is a Symfony-based CMS, circa Symfony 2.8/3.x). Treat the package as a single widget contribution to that ecosystem.

Minimal setup:

1. Install Victoire core first (victoire/victoire meta-package or the individual bundles) and get a page rendering in the backend editor.
2. composer require friendsofvictoire/slidernav-widget — expect to fight dependency constraints, since the last release is from November 2016.
3. Register the bundle class (root WidgetSliderNavBundle.php), typically in app/AppKernel.php, after the Victoire bundles so the widget compiler pass can discover it.
4. Run bin/console cache:clear and bin/console assets:install --symlink (plus your assetic dump if the project uses assetic).
5. Open the Victoire backend, enter edit mode on a business template, and drag the SliderNav widget from the picker into a slot.

Where to look first, in order:

• Resources/views/ — the widget's Twig template(s); this is what you will override most often.
• Form/ — the widget's *Type, which defines exactly which fields are editable and therefore what the side panel shows.
• Entity/ — the widget model (extends Victoire's base Widget), which tells you what data is persisted and what is convention-only.
• Resources/config/services.yml — whether any service is registered (renderers, listeners, form types) and under what tags.
• Resources/public/ and Resources/translations/ — JS/CSS the widget expects to be loaded, and label keys.

First real use case: a page needs an image/link slider with navigation dots. You add the widget in the editor, configure it through the injected form, and then immediately clone the Twig template into your app's override path to match the designer's markup. Expect to spend more time on the template override than on the widget configuration itself.

Implementation Patterns

The Victoire widget triad. Every widget in this family follows the same shape: an entity extending Victoire's Widget model, a form type (usually extending AbstractWidgetType) used by the editor sidebar, and a Twig template resolved by widget name. When you need to change behaviour, first identify which leg of the triad owns it — data shape (entity + migration), editor UX (form type), or output (template). Avoid hacking the entity for presentation concerns.

Template overriding is the primary integration point. Copy Resources/views/WidgetSliderNav/*.twig into app/Resources/WidgetSliderNavBundle/views/WidgetSliderNav/ (Symfony 3 bundle inheritance). This is the lowest-risk way to restyle the widget, and it survives package updates if you keep the same variable contract. Check which variables the template receives — usually the widget entity itself plus a few resolved relations — and keep that contract stable.

Scoping markup per instance. A page can hold several SliderNav widgets. Always render a wrapper with an identifier, e.g. data-widget-id="{{ widget.id }}", and scope all JS/CSS to it. Slider libraries (Slick, Owl, Swiper, or whatever the bundle ships) that initialize on a global selector will conflict across instances.

Adding configurability. If the form type doesn't expose a field you need, override the type in your app (form type extension or a subclass registered in its place) and map it to a property on the entity. Because the entity extends Victoire's base widget, you can often reuse existing generic fields rather than writing a Doctrine migration; only add columns when the data is genuinely structured.

Editor-mode awareness. Victoire's edit mode injects overlays and toggles slots. Slider JS should be initialized on front-end render only, or re-initialized after editing stops. A common pattern is to check for the Victoire edit-mode body class and skip auto-play/animation.

Programmatic creation. For fixtures and demo content, instantiate the widget entity directly, set its slot, position, and business-template association, then persist via Doctrine. This is how you seed a homepage slider without clicking through the editor — useful when setting up acceptance tests or new environments.

Composition with business templates. The widget is placed inside a business template's slot, so every business entity using that template inherits it. If you need per-page slider content, the widget is the wrong abstraction — you want a business entity with a relation to slider items, and the widget should render that relation rather than static widget fields.

Asset loading. If the bundle ships JS/CSS in Resources/public, include it from your layout once ({% block stylesheets %} / {% block javascripts %}) rather than from the widget template, otherwise multiple instances will include it repeatedly.

Gotchas and Tips

It is effectively abandoned. Last release 2016-11-16, one star, zero dependents. Composer resolution against modern Symfony will likely fail outright. Practical options: pin your Symfony/PHP versions to match, use friendsofvictoire/slidernav-widget only as a reference implementation and copy the code into your app bundle, or fork it and re-release under your own namespace. Do not build a roadmap on upstream fixes.

Widget missing from the picker. Almost always one of: bundle not registered in the kernel, cache not cleared after registration, or the widget class not being discovered by Victoire's compiler pass (wrong parent class or missing tag). Start with cache:clear, then verify the class actually extends the Victoire Widget model.

Blank or unstyled output. Victoire resolves the template by widget name; a mismatch between the entity's name and the Resources/views/<Name>/ directory silently produces nothing or falls back to a generic render. Confirm with debug:twig that the namespace resolves, and check the rendered HTML for Victoire's debug comments (enabled when kernel.debug is true) to see which template was chosen.

Edits are shared across pages. Because widgets live on the business template, changing one changes every page using that template. If editors expect per-page sliders, clarify this early or introduce entity-level data.

Assets go stale. assets:install and assetic dumps are needed after install and after any change to Resources/public. Hard-refresh in the browser; the 2016-era cache-busting is not reliable.

JS lifecycle in the editor. Victoire's edit mode rebuilds DOM fragments when widgets are moved. Slider instances initialized before a move will break or duplicate. Listen for the editor's save/refresh event, or re-initialize defensively on DOMNodeInserted/MutationObserver.

Translation keys. Labels in the form and template typically call |trans against the bundle's domain. Override translations in app/Resources/translations/ rather than editing the bundle, so your copy is not lost on update.

Debugging checklist. (1) cache:clear after any template or config change. (2) Inspect the widget table to confirm the entity persisted with the expected slot and position. (3) Use twig:lint on overridden templates — a syntax error there fails silently in some Victoire versions. (4) Add {{ dump(widget) }} behind a debug flag to see the resolved data.

Extension points worth knowing. Twig template override (safe), form type extension or replacement via service definition (medium), service decoration if a renderer is registered (check services.yml first — the bundle is small, so there may be none), and event listeners on Victoire's widget events if exposed. Anything beyond that is a fork.

Sanity check before adoption. Given the age and the zero-dependent count, run a full install against your target Symfony version in a throwaway branch before committing to this package. If it takes more than a few hours to get the widget visible in the picker, the cost of copying the ~handful of files into an in-house bundle is usually lower than the cost of forcing compatibility.