Monthly Archives: August 2013

Widget Builder for Umbraco

One of my absolutely favorite packages for Umbraco in the recent months has to be Kevin Giszewski’s Widget Builder. I do not know why allowing editors to repeatedly add input fields isn’t a core functionality of Umbraco yet, but until it is, Widget Builder provides a handy solution.

So what is really the problem?

Imagine a simple (and simplified) scenario: A local cafe, for which you are building an Umbraco website, likes to entertain their guests with music performances. They would like you to include a page in their website that sports a simple list of date/time, performer and title of the performance. As simple as that.

With current Umbraco capabilities your choices are:

  1. Providing limited number of time/performer/title groups so that the website will only display a set number of them at a time – I think we all know that this is a very bad UX practice.
  2. Setting the input field as a TinyMCE and letting your editors enter the information in any form they choose – we’ve all been there and we’ve all seen how quickly this can go bad. I firmly believe that RTE should only be available to editors if what they want to enter is body text. In all other cases, the more structure we can make it, the less chances for mistakes and the more clear and uniform the website
  3. Creating a docType for the entertainment page with the list AND a docType for a list item so that every time the editor wants to add an item to the list, she has to create new content item as a child to the entertainment page. – with a simple macro, this solution will of course work. But it seems like we’re adding extra work for the editor. Adding a new piece of content only to display a line with three information pieces on the website, just doesn’t seem right.

So what is an Umbraco developer to do?

Enter Widget Builder

Kevin writes in his documentation:

Widget Builder is a data type designed to be repeatable within a property.

What it means is that this package solves our problem with the entertainment list by allowing the editor to repeat the set of input fields, we had defined, as many times as is needed within one content node. Here is how to do it:

  1. Install package as per usual
  2. Go to Developer and add new dataType. Choose Widget Builder as Property Editor and save.
  3. Define your set of properties that should be repeatable:

Umbraco widget builder screenshot In the case of our cafe, we want to add three simple textbox fields Date and Time, Performance Title and Performer. Once the widget is saved we can move on to docTypes.

  1. Create a doctype that will display the list of performances: Entertainment List
  2. The doctype should include one property: Entertainment. Choose your freshly created widget builder as a type for this property. In my case this is also called Entertainment.

Now you can move on creating content.

  1. Create page with the docType you’ve just created.
  2. Add as many sets of input field sets as you want by clicking on the green plus icon on the left. Remove sets with the red icon and move them around by dragging and dropping.

Using widget builder - screenshot

Voila! Well, not really. You still need to be able to display the input from the widget and you certainly cannot do it with @Umbraco.Field(“Entertainment”). Here is where the fun begins. To access the editor’s input you will need a macro. In my case we will use a Razor macro:

<ul>
  @foreach (var performance in Model.entertainment)
  {
     <li>
       <span class="performanceDateTime">@performance[0].InnerText</span>
       <span class="performanceTitle">@performance[1].InnerText</span>
       <span class="performancePerformer">@performance[2].InnerText</span>
     </li>
  }
</ul>

Read this macro as follows:

  • Model – current page
  • Entertainment – The property that stores all the sets of input fields
  • Performance – a set of input fields
  • Performance[0] – the first input field in the set etc.

And voila! If you add this macro to your page’s template, it will happily display all the sets as list items. You can of course style them as you want and display them as divs, paragraphs or whatever else your imagination dictates.

What if I want to use different dataTypes?

The last thing worth mentioning is that, as you might have noticed when creating the set of input fields in development section, you can use different input types. This makes the macro you need to write a little bit more complicated.

So let’s say that our cafe owning client would like to display a list of performers for each performance. After all there is often more than one. So instead of a textbox, we want to use a list for the performer field. Head back to the developer section, delete the last widgetTextBox and add a widgetList. For simplicity’s sake let’s keep the name Performer. With this input type we can choose to allow more than one indent level, but this really isn’t necessary in our case. Save the dataType and move on to the content.This time to add new items in the list but not a new input fields set, click the green icon on the right.

If you look at the page now, the macro that we have created will in fact work but not perfectly. All names you’ve added to a list will be displayed together as a string, without so much as a space between words. To fetch list items as separate strings, we need to add to our macro:

<ul>
    @foreach (var performance in Model.entertainment)
    {
        <li>
            <span class="performanceDateTime">@performance[0].InnerText</span>
            <span class="performanceTitle">@performance[1].InnerText</span>
            <ul class="performancePerformer">
                @foreach (var item in performance[2])
                {
                    foreach (var name in item)
                    { 
                       <li>@name.InnerText</li>
                    }
                }
            </ul>
        </li>              
    }
</ul>

As counterintuitive as it may seem, you need to add two foreach loops in order to achieve the intended result.
In this case:

  1. performance[2] – the property that holds list
  2. item – the particular list that holds list items
  3. name – each list item we want to display

Now it it finished and all ready to be styled to your heart’s content.

I know it feels like the macro gets a bit complicated when you try to access input from special dataTypes but providing this simple functionality for your editors will make their lives so much easier and their pages so much more structured. The only thing to wish for is that the Widget Builder will become a core functionality of Umbraco one day. Maybe in Umbraco 7? Who knows?