Tutorials/widgets in 4.7 + 5.0

= Definition =

A widget is logical GUI element that can be easily replaced or re-used in any template. It consists of logically divided pieces of code. Usually, there are the following elements:


 * the widget include in templates,
 * the widget template itself and
 * a widget controller.

= Widget include =

Widgets are included with the smarty tag oxid_include_widget. You can use both, standard and additional parameters in the same path using the same syntax:

{parameter name}={parameter value}

Standard parameters are:


 * cl - a controller that describes widget to include.
 * oxwtemplate - path to a different template to be used instead of the default one.
 * nocookie - if equal to "1". Means that cookies shall be removed for the widget when it is used together with a reverse proxy and iIndicates that the widget should be cached.
 * _parent - should be equal to the method $oView-&gt;getClassName as it describes which layout generates the widget. The widget can take over components from it and generates links correctly.
 * _navurlparams - should be equal to the method $oViewConf-&gt;getNavUrlParams. It is an easy way to chain all parameters that describe how to generate the views (list, grid etc.).
 * noscript - if equal to "1" do not generate the JavaScript include. This is used for work with a reverse proxy: JavaScript is encapsulated in widget functions and will be loaded separately from the layout. These functions will be executed by the general layout after the page is loaded.

 Please note:  make frugal use of this parameters. Every parameter configuration generates an additional cache entry in a meaning of additional hits to generate the cache.

An example for additional parameters, more below:

deepLevel=0 noscript=1 cnid=$oView-&gt;getCategoryId

= Widget controller =

The widget controller component extends oxWidget. It's components contain the path to the widget template and all logic needed for template rendering. A lot of widgets can control one layout. The layout renders first and in most cases all components. When the widget is rendered it checks it's list of components for the layout and if the component is not rendered yet, the widget will trigger rendering. If a component is already rendered, this procedure is skipped.

= Widget template =

The widget template is built of html and smarty (needed to generate the widget independently). It usually doesn't include external css used in OXID eShop. Smarty getters call the widget controller.

= Examples =

Widget include
You can find the basket widget included in /tpl/layout/header.tpl:

[{if $oxcmp_basket-&gt;getProductsCount}] [{assign var="blAnon" value=0}] [{assign var="force_sid" value=$oViewConf-&gt;getSessionId}] [{else}] [{assign var="blAnon" value=1}] [{/if}] [{oxid_include_widget cl="oxwMiniBasket" nocookie=$blAnon force_sid=$force_sid}]

It checks whether there is something in the cart and passes the sessionID and parameters. cl describes that the controller can be found in application/components/widgets/oxwminibasket.php. force_sid is used to pass the sessionID to the widget in order to get the content of the cart.

Widget controller
The Mini basket widget describes components that have to be loaded and the path to the default template.

/** * Mini basket widget */ class oxwMiniBasket extends oxWidget { /** * Names of components (classes) that are initiated and executed * before any other regular operation. * User component used in template. * @var array */ protected $_aComponentNames = array( 'oxcmp_cur' =&gt; 1, 'oxcmp_basket' =&gt; 1, 'oxcmp_user' =&gt; 1 ); /** * Current class template name. * @var string */ protected $_sThisTemplate = 'widget/header/minibasket.tpl'; }

Widget template
The widget template includes the minibasket.tpl and minibasketmodal.tpl the same way as it was done in previous versions (like 4.6). Therefore, you will find no changes related to widgets in both template files. The widget template also calls the oxscript that decides if it is necessary to output JavaScript at the bottom of the widget.

[{oxid_include_dynamic file="widget/minibasket/minibasket.tpl"}] [{oxid_include_dynamic file="widget/minibasket/minibasketmodal.tpl"}] [{oxscript widget=$oView-&gt;getClassName}]

Caching
Widgets can be cached by reverse proxy. If reverse proxy caching is active - widgets will be rendered independently from the layout - means, widgets will be rendered separately. To declare whether the widget should be cached or not by the reverse proxy, isCacheable method should be defined in widget's controller. This method will be moved to oxWidget.

To purge cached widget on some event, you need to invalidate it. You can do it like this:

$oCache = oxRegistry::get( 'oxReverseProxyBackend' ); // check if reverse proxy is active if ( $oCache-&gt;isActive ) { $oProxyCacheUrls = oxNew( 'oxReverseProxyUrlGenerator' ); // add widgets which should be invalidated at this point $oProxyCacheUrls-&gt;setWidget( 'oxwmywidget' ); $oProxyCacheUrls-&gt;setWidget( 'oxwotherwidget' ); // add these urls to reverse proxy backend $oCache-&gt;set( $oProxyCacheUrls-&gt;getUrls ); // execute invalidation $oCache-&gt;execute; }

Here widget name is set to url generator and generated urls are passed to reverse proxy backend. Purging is usually done at executeDependencyEvent event.

Edge Side Includes or ESI tag
When reverse proxy is enabled, widget include tag ([{oxid_include_widget cl="oxwMyWidget"}]) is changed by ESI tag. This ESI tag provides generated widget url, which is then used by reverse proxy to check if it does have valid content cached or if it should be loaded. ESI tag looks like this:

&lt;esi:include src='http://shop_url/widget.php?lang=1&amp;cl=oxwmywidget&amp;nocookie=1&amp;oxwparent=start&amp;lang=1'/&gt;