Widget Builder for Umbraco v6

Welcome to the Widget Builder Documentation Portal

Widget Builder is on-the-fly fieldset management and gives editors the flexibility to add what they need when they need it.

Comes with several native property types and is compatible with some 3rd-party property editors like DAMP.

If you need similar functionality in v7, please use Archetype.

Licensing

This software is released under the MIT License.

You may use this package free of charge as there is no license check required in the current versions. However you may purchase a support license if you desire at the bottom of the page.

Clean Installation

Installing Widget Builder is done like any other package. Simply download and use the Developer Section->Install Local Package Wizard to get going. That's it.

Upgrading 1.x to 2.x

Make a backup of both your site code files AND the database. You'll be sorry if it all goes unwell.

This should be straight-forward, but somethings have been moved around and renamed so it may get slightly rocky (but probably not).

Download the package but DO NOT use package installer yet. Edit ~/App_Data/packages/installed/installedPackages.config with a text editor. Remove the XML 'package' element for Widget Builder only. This effectively tells your site to 'forget' about the fact you have Widget Builder installed. Delete from /bin - widget_builder.dll (and remove the reference if using VS). Install Widget Builder as a clean install as stated above.

Designing Your First Widget

Designing a Widget is easy. Follow these steps to get going:

• Visit the Developer Section
• Right-click Data Types
• Left-click Create
• Give your Widget a name, Click Create
• Choose Widget Builder from the drop down, click the save icon.
• You should now see the toolbar of things you can add to your Widget
• Single-click each item you wish to add. Make sure you give them UNIQUE (to the Widget) element names. * The element name will be used in the cache for data retrival later on your template.
• Each element you add to your Widget will have different settings.
• Choose how many times this Widget can be repeated within a property (Max Widgets Per Property). Choose 1 if you do not want an editor to be able to add more on the data editor screen.
• Click the save icon and you are done.
• Place your Widget

Now that we have a Widget, you will need to affix the Widget to a doctype as you would any other data type.

• Visit the Settings Section
• Choose your document type you wish to add this to.
• Add it as you would anything else.
• Save your doctype.
• Test your Widget

Now that we have created a Widget and added it to a doctype. We need to create a piece of content based on that doctype. We will assume you know how to create content. Test your Widget from the newly created content.

Output Your Widget

You grab data from a Widget in your templates as you would any other data type. You can check your local ~/App_Data/umbraco.config to see how your data is being stored. It should be no surprise that Widget Builder stores its data as XML.

If using XSLT, you can navigate your $currentPage element and dig into your Widget as you see fit.

If using Razor, include the WidgetBuilder.Extensions namespace into your project. A list of methods can be found here.

Give Your Widget Personality

Another cool feature is injecting jQuery and/or CSS to your Widget to give it special behavior. You can inject these in two ways:

You can simply edit the built-in ~/umbraco/plugins/WidgetBuilder/custom.js (or css) files Or use different files by specifying the file names in the Developer Section-> Data Types -> My Widget prevalue page.

Import/Export Your Widget

Wouldn't it be great if you could simply copy/paste a widget to another widget either locally or to a different install altogether? Well you can.

• Visit the Developers Section->Data Types->Your Widget.
• Click Toggle JSON (Advanced Only)
• A textarea will become exposed. Copy the JSON from the box to your clipboard.
• Create a new Widget and save it.
• Click Toggle JSON (Advanced Only)
• Paste the JSON into the box and save.
• If you have any custom CSS/JS, you will need to make sure you copy them over if going to another install.

Permissions

Permissions in Widget Builder works as simply hiding some (or all) properties by User.

• Visit the Users Section->Widget Builder User Permissions.
• Click a user, then toggle what the user can see.

At this time you cannot do this by role. This information is stored in the ~/config/WidgetBuilder.config file.

How to get DAMP to work with Widget Builder

Make a backup of both your site code files AND the database. You'll be sorry if it all goes unwell.

If you use DAMP and want to use it with Widget Builder, you are in luck. Widget Builder presently works with DAMP 2.7. We can't control DAMP's development, but as long as you have that version of DAMP; we can rock and roll with it.

• Download and Install DAMP 2.7
• Next go here and grab DampWidgetExtension.dll and drop it into your /bin
• DAMP will now appear in your tool bar while designing a Widget.
• Be sure to remove DampWidgetExtension.dll if you uninstall DAMP.

Known Issues

Widget Builder isn't perfect, here is a list of known issues:

• WB does not play nice with the 'Related Links' data type. Please use the uComponents Multi-Url Picker instead.
• WB's RTE (TinyMCE) implementation has an issue with 'Insert Macro'. At this time it does not work.
• WB's RTE (TinyMCE) implementation has an issue with the 'styles' dropdown being misplaced at times. There is no fix at this time.
• WB's RTE (TinyMCE) implementation had an issue with Umbraco v6.1.x when sorted. There is now a fix! Replace your /umbraco/Plugins/WidgetBuilder/WidgetBuilder.js with this.

Support

This project is sunset but if you have a question, please send a tweet to @KevinGiszewski.

Formal support licensing (companies who need a bug fix, analysis, etc) can be purchased as well: