Smartwig Bundle Laravel Package

Getting Started

The first thing to understand is that this is a Symfony2 bundle, not a Laravel package — so "day-to-day leverage" for a Laravel developer mostly means one of two things: (a) you're maintaining a legacy Symfony2 app that already depends on it, or (b) you're using it as a reference for how to wrap jQuery UI widget generation into server-side templates. There is no Blade/Laravel service provider here.

If you're on a Symfony2 app:

1. Check the composer.json in the repo first — it targets Symfony ~2.1+ and jQuery4PHP. Do not attempt to install on Symfony 4+/Laravel; the Yepsua\SmarTwigBundle\YepsuaSmarTwigBundle class uses the old bundle conventions and Twig APIs.
2. Install: composer require yepsua/smartwig-bundle
3. Register in app/AppKernel.php:

   new Yepsua\SmarTwigBundle\YepsuaSmarTwigBundle(),
   

4. Publish assets: php app/console assets:install --symlink web/
5. Make sure jQuery and jQuery UI (and any plugin JS/CSS the widgets need, e.g. jqGrid) are loaded in your base layout — the bundle generates widget JavaScript, it does not ship the upstream library for you.
6. Write a template that uses a widget tag.

First use case — a jQuery UI dialog:

{% ui_dialog title="Hello" autoOpen=true %}
    <p>This content is rendered server-side and handed to jQuery UI.</p>
{% end_ui_dialog %}

The bundle's Twig extensions translate tag + attributes into jQuery4PHP component objects, which render as inline <script> calls during template output. Look first at Resources/config/ for the service definitions and Twig/ for the tag extensions — that is where the actual attribute-to-option mapping lives, and it is your source of truth when documentation is thin (which it is).

Implementation Patterns

1. Declarative widgets via Twig tags. Each supported widget has a matching tag (ui_dialog, ui_button, ui_tabs, ui_accordion, ui_datepicker, ui_slider, ui_progressbar, ui_autocomplete, jqgrid, etc.). Attributes on the tag map to jQuery4PHP/jQuery UI options. Nest tags to compose layouts (tabs containing grids, dialogs containing forms).

2. jQuery4PHP as a programmatic layer. The underlying jQuery4PHP library can be used outside Twig — in a controller or a small service — by building component objects and calling ->render() (or ->execute()) to emit the script. This is useful when a widget's configuration is driven by runtime data (column models for jqGrid, dynamic tab lists, etc.) that would be awkward as literal tag attributes.

3. Ajax data patterns. The most practical real-world use is jqGrid + a Symfony controller that returns JSON. Keep the data endpoint a normal controller returning new JsonResponse(...) (or Response with application/json), and let the grid tag point at the route. Keep pagination/sorting params (page, rows, sidx, sord) handled server-side.

4. Assetic for asset wiring. Since this predates Symfony Webpack Encore, you'll be combining it with Assetic to bundle jQuery, jQuery UI themes, and plugin assets. Define combined files in config.yml and reference them in the layout.

5. Forms + widgets. Pair Symfony form rendering with jQuery UI widgets — render the field normally, then attach a ui_datepicker/ui_autocomplete tag targeting the input's selector. Avoid rebuilding the form in JS; let the server own field names and CSRF tokens.

6. Extending with custom widgets. The extension point is a Twig extension that instantiates a jQuery4PHP component and returns its script. Register it as a tagged Twig extension service. This is the sanctioned way to add a widget the bundle doesn't ship.

7. Porting the pattern to Laravel. If your actual goal is a Laravel app, the reusable idea is: a Blade component/directive that owns the JS for one widget, driven by an options array, emitting a data-* payload that a small JS initializer consumes. That gets you the same declarative ergonomics without the dead dependency.

Gotchas and Tips

• Framework lock-in. Symfony2-only. No Laravel integration, no Blade, no service provider. If you're a Laravel developer, treat this as architecture inspiration, not a dependency.
• It's a 2013-era package (low stars, zero dependents, no maintenance signal). Expect jQuery 1.x/2.x era assumptions. Modern jQuery 3.x removed/deprecated APIs (e.g. $.browser, some jQuery UI widget signatures) that jQuery4PHP-generated code may rely on. Pin jQuery and jQuery UI versions if you must run it.
• Asset publishing is mandatory. Forgetting assets:install (or the newer equivalent) is the classic "nothing renders" failure — the widget JS exists in the bundle but not in web/.
• Inline script ordering. Widgets render as inline <script> blocks. If your tag output appears before jQuery is loaded, you get $ is not defined. Ensure the widget region renders after the library scripts — usually by placing widgets in the body, not the head, and by depending on the bundle's document-ready hook rather than raw inline calls.
• Twig tag parsing quirks. These are custom tags, not functions/filters. Nested widgets, whitespace control ({%-), and attribute quoting can trip the token parser. When a tag silently fails, simplify to a single flat widget first, then re-nest.
• Autoescaping. Widget content may be HTML by design; check whether the tag disables autoescape or double-encodes your markup. If dialogs show literal <p> tags, that's the culprit.
• Attribute → option mapping is not 1:1. An attribute name on a tag may map camelCase, snake_case, or not exist at all versus the underlying jQuery UI API. Always confirm in the extension source rather than trusting jQuery UI docs.
• Debugging approach. View source on the rendered page; find the inline jQuery4PHP script block; paste it into a bare HTML page with the same jQuery versions. That isolates "bundle problem" from "JS environment problem" quickly.
• Performance. Each widget is its own inline script and often its own asset include. Pages with many widgets bloated. Batch/combine assets and consider initializing widgets from a single script for grid-heavy pages.
• Extension points. Custom widgets = a Twig extension service wrapping a jQuery4PHP component. Overriding the bundle's templates/resources is supported but check Resources/views/ before forking — and be aware that bundle-level overrides are fragile across Symfony minor bumps.
• Config quirks. The bundle's configuration is small; most behavior comes from tag attributes, not config.yml. Don't waste time hunting for a knob that isn't there — read the extension class.
• Maintenance reality check. jQuery4PHP itself is dormant. For new work, use a modern UI toolkit or a small custom initializer; keep this package only for existing Symfony2 codebases where removal cost exceeds the risk.