how to use the example jquery plugin

[hlb-schmidt]

am i blind or does https://github.com/shopware/devdocs/blob/master/source/designers-guide/javascript-statemanager-and-pluginbase/index.md not mention how to use the example plugin?

i see a hint "Automatically binding the plugin to the element using jQuery's data-method"...

or is this doc only for using the example plugin with the statemanager?
where is the documentation on how to use (this example) shopware-exclusive* jquery plugin without statemanager?

*jquery plugin documentation here looks completely different https://learn.jquery.com/plugins/basic-plugin-creation/ so are these two different jquery plugin systems?

[klarstil]

Hey @hlb-schmidt,

let me clear it up for you. The plugin base is an abstraction layer which provides you with the best practices of the jQuery plugin authoring based on a pattern from Alex Sexton & Scott Gonzalez including further changes from Addy Osmani: https://github.com/jquery-boilerplate/jquery-patterns/blob/master/patterns/jquery.prototypal-inheritance.plugin-boilerplate.js

The call of $.plugin('<name>', myPluginObject) will bind the plugin internally to the jQuery.fn object and therefore it is a normal jQuery plugin. The plugin can be used like any other jQuery plugin like $('.selector').example().

Speaking about the automatic binding of plugins to DOM elements. Plugins which are meant for general usage are registered with a data attribute selector e.g. $(*[data-modal=true]).swModal(), see: https://github.com/shopware/shopware/blob/5.3/themes/Frontend/Responsive/frontend/_public/src/js/jquery.shopware-responsive.js#L82-L93

The state manager on the other hand provides us to enable / disable jQuery plugins based on screen sizes. For example on mobile devices the real screen estate is pretty small and we're needing an offcanvas menu for our category navigation. On devices with bigger screens we don't need the plugin anymore, therefore it just makes sense to destroy the plugin, which is what the state manager does automatically for you. It also provides you with the ability to change the configuration.

Best regards

[hlb-schmidt]

so in the context of that example plugin, there is no automatic binding to a css selector nor a dom element. nor is there a requirement for a data attribute. and the plugin author (or user) has to manually define the css selector, either through StateManager (as shown in the documentation) or:

$('.whatever').example();

and then the user binds it to a dom element by adding the css selector to the desired dom element.

ps. i guess the shopware plugin-name-to-css-selector convention swCollapsePanel -> data-collapse-panel="true" is just random, and does not provide any extra features?

[buddhaCode]

Exactly. Do did sum it up well!