Widgets

A container may have n widgets, each of which represents a fragment of the part of the page which is represented by the container. See /templates_system/containers_and_widgets for more details.

How to create a new type of widget?

Add a new constant to the /src/SWP/Bundle/TemplatesSystemBundle/Model/WidgetModel class, and a reference to a class which extends AbstractWidgetHandler.php in /src/SWP/Component/TemplatesSystem/Gimme/Widget

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
class WidgetModel implements WidgetModelInterface, TenantAwareInterface, TimestampableInterface
{
    const TYPE_NEW = 1;
    ...

    protected $types = [
        self::TYPE_NEW => '\\SWP\\Component\\TemplatesSystem\\Gimme\\Widget\\NewWidgetHandler',
        ...
    ];

    ...

You must then create that class which you have referenced.

As well as having to implement the render function in this class, you can define what, if any parameters should be set in an instance of a widget model which references this class by adding a static variable called $expectedParameters.

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
class NewWidgetHandler extends AbstractWidgetHandler
{
  protected static $expectedParameters = array(
      'parameter_name' => [
          'type' => 'string',            // or bool, int, float
          'default' => 'default_value'   // if no default is provided, the parameter must be set
      ]
  );

  ...

If there is no default value, the default value, by default, will be null.

Typically, the render function will use the template engine to render a template which requires the given parameters.

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
class NewWidgetHandler extends AbstractWidgetHandler
{
  ...

  /**
   * Render widget content.
   *
   * @return string
   */
  public function render()
  {
      return $this->renderTemplate('template_name.html.twig');
  }

  ...

The referenced twig file should be located in the theme’s views/widgets directory. The implementation of the renderTemplate method in the base class prepends ‘widgets/’ to the given string, and passes this argument, along with the expectedParameters and their values in an associative array, to the template engine’s render method.

Available widgets

By default there are three types of widgets bundled into the project:

  • ContentListWidget
  • HtmlWidget (default one)
  • GoogleAdsenseWidget
  • MenuWidget
  • LiveblogWidget
  • TemplateWidget

ContentListWidget

This is the widget responsible for displaying Content Lists’ items. For more details about Content Lists and Content List Items see Content Lists and ContentListBundle sections.

Default parameters:

Parameter Description Required? Default value Type
list_id List’s id yes N/A int
template_name Template name to render yes list.html.twig string

LiveblogWidget

This is the widget responsible for displaying Superdesk LiveBlog embeds.

Default parameters:

Parameter Description Required? Default value Type
uri Liveblog embed (fragment) uri yes N/A string
template_name Template name to render yes liveblog.html.twig string

Default template file name: liveblog.html.twig (default version provided by Publisher can be overriden by theme).

TemplateWidget

This widget is used to trigger some smaller template functionality, for example list of most popular articles in last week, or featured author profile. It is by default looking for template in folder views/widgets

Default parameters:

Parameter Description Required? Default value Type
template_name Template name to render yes N/A string