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:

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->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->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:

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:

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.

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.

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:

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:

<esi:include src=’http://shop_url/widget.php?lang=1&cl=oxwmywidget&nocookie=1&oxwparent=start&lang=1’/>


0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *