Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

We're retiring the forums!

The SilverStripe forums have passed their heyday. They'll stick around, but will be read only. We'd encourage you to get involved in the community via the following channels instead:

Archive /

Our old forums are still available as a read-only archive.

Moderators: martimiz, Sean, Ed, biapar, Willr, Ingo

Rendering modules and widgets...

Go to End

15 Posts   5727 Views


Forum Moderator, 628 Posts

19 July 2007 at 5:49pm

Edited: 19/07/2007 5:55pm

Brian et al, something that may or may have been covered by the recent Themes Discussion (which please put highlights in a thread here) is allowing modules automatically work after a mere /db/build but also be capable of configuration.

This will bear on all of the existing modules made, and needs to established in the next few weeks as the GSOC code comes into more shape. E.g. see, where we now have modules returning their HTML into a template in different ways. We need a convention, and one soon.

To my mind, there's a few ways a 'module' or 'widget' may wish to exist;

1. Append to $Content. This could be the default option.

2. Return as a dollar variable, allowing you to put $FlickrGallery or something anywhere in your templates

3. As a /Layout/ file, which I think was a good scheme but was broken down in the rush to build the BlackCandy file. I feel as though Layout/ is "too big" and at this tage "layouts" are both trying to be most of a page, and a replacement or addition to $Content. Its role needs to be properly established.

4. "As a widget" in which the location can be prescribed in the CMS or some easy manner. In essense, this is to allow putting it a right hand column of widgets akin to Wordpress, etc.

5. None of the above, aka, let me manually put it somewhere in some other format.


It might be that as a default it does #1 (for the time being, if #4 is some time off), simply so that the default case is a module that runs instantly with no template editing. You can then edit your mysite/_config.php a method that provides a clean way to make it render your module in a different manner, e.g.

flickrgallery->renderasvariable("myflickrgallery"); // means $myflickrgallery works

Now, this brings me onto another topic as well...


Administrator, 690 Posts

19 July 2007 at 10:39pm

Some thoughts...

* #1 and #3 are two different forms of having a special page type to support the module. This works well for things like e-commerce where your module is "taking ownership" of a particular page or set of pages.

* We should fix the "Layout" template scheme by more precisely defining what parts of the site should appear inside the Layout template.

* Additionally, some templates will need to provide content to go on the outside of Layout. For instance, a shopping cart module might want to put a cart contents / checkout link at the top of the forum. Most likely, in addition to "Layout" we want some extra named-spaces in which we can put our stuff. For example, "UtilityInfo" could be an area at the top of the screen where we can put log-in info, checkout links, etc. The template designer could then choose a suitable place for UtilityInfo to appear.

* For #2, we could add a method Widget($className) to SiteTree. It would instanciate and return $className. Your module could be implemented as a subclass of ViewableData. And you could then put $Widget(FlickrGallery) in your template.

* #4 is a good idea that hasn't been explored much in SilverStripe. It would probably use the same kind API as #2 - that is, widgets could be inserted into the templates using $Widget(). Site/Template Developers would be able to set up one or more 'widget list' areas somewhere in their template - such as the right hand column - and have it populated by a corresponding 'widget editor' control in the CMS. In keeping with SS design principles, site developers could easily customise whether they had 0, 1, or many of these controls on their site, and have different settings on different page types.

These will require some careful thought, and probably some core changes that will need to be part of 2.0.3. I'll going to be travelling the world for the next couple of weeks :-) but will come back to it in early August. In the meantime, I'll keep an eye on this thread... ;-)


Forum Moderator, 801 Posts

29 July 2007 at 2:19pm

from what i see, there are two types of widgets:
1. global widget (e.g. a tagcloud) that just needs a page-context
2. page-specific widget (e.g. gallery), where settings like thumbnail-size are specified on an instance-basis

as we're relying on pagetypes to show config-settings, we need a more granular approach for #2. i like sams idea of specifying "widget-areas" in your, which are then populated in the CMS on page-by-page basis. we could solve this with a new API for a mini-getCMSFields().

"global widgets" could still be configured in _config.php, until we get a proper UI for global settings. unlike #2, they could be inserted straight in the template, with the proposed Widget() template accessor.

the tricky part is widgets which are supposed to be used global AND page-specific (e.g. a tagcloud might have optional page-specific settings as well). this again comes to building a config-API which can look up settings in the page-context (database), but falls back to global (_config.php).

i think it would be appropriate to solve the issue with a new config API first (and on a broader level), and then get into page-specific widgets.

when i'm back in germany, i'll dig up some examples how joomla/typo3/etc solve this problem :)


Community Member, 231 Posts

31 July 2007 at 11:04am

Currently, I am implementing #4 - that is, a page can specify a widget area, with an editor in the cms that allows you to specify which widgets are used, and configuration options using the 'mini-getCMSFields' that Ingo mentioned.

#2 can be easily implemented by creating a method on the page controller, which can create a widget, set its config and then return it to the template.


Administrator, 690 Posts

31 July 2007 at 4:22pm

This all sounds really good, I look forward to seeing it when it's ready! :-)


Community Member, 231 Posts

2 August 2007 at 10:06am

I've documented what I've done for widgets (including using dollar variables) on the interal wiki at, which will be moved to the public wiki when the module is released.


Forum Moderator, 922 Posts

2 August 2007 at 2:55pm

Edited: 02/08/2007 3:11pm

In addition to your use of dollar variables in the documentation, can we not make a function for the controller like so:

function Widget($widgetClass = null) {
   if($widgetClass && class_exists($widgetClass) && $widgetClass instanceof Widget) {
      $widget = new $widgetClass();
      return $widget->renderWith('WidgetHolder');
   } else {
      return user_error("SiteTree::Widget() could not find a widget class to create.");

Then you could just go $Widget(FlickrWidget) anywhere in the template? Unless you've already done this, and I've missed something?

EDIT: As Sam was saying, we'd just add this to SiteTree.



Forum Moderator, 922 Posts

2 August 2007 at 3:20pm

Edited: 02/08/2007 3:21pm

One other question: with your blog module at the moment there are Widget, WidgetArea and WidgetAreaEditor classes inside there, along with it's associated templates.

Are you just putting them into the blog code for now, so later on they will be placed back into the core? It all looks good and fine to me the way you've done it. Looks rather simple in fact. :-)

By the looks of it, I just made myself 'CoolWidget.php', dropped it into the code with some default $title and $description variables - and had myself a widget that popped up into the Widgets tab on the BlogHolder class. Fantastic!

Another question:

BlogHolder.php (line 19):
$fields->addFieldToTab("Root.Content.Widgets", new WidgetAreaEditor("SideBar"));

Is there not a way to automatically have these widgets included on all pages, so we don't have to create a new field to apply widgets to (on a class-by-class basis)? I guess you're always going to need a place to tell it where to apply the widgets to, for this example you're rendering into $SideBar for all the widgets, I take it? Is it possible to abstract this even more, or is it best we just let the site developer apply this field to whether they deem appropriate?

Great work Jeremy and Andy!


Go to Top