Final Product

Control How Users Enter Content Using Custom Widgets

Thu Apr 5, 2018

Hours Earlier… You lean back in your chair and marvel at the sexy bit of code you wrote to add new functionality to your organization’s website. The halls of your office erupt with praise from your co-workers, while balloons drop from the heavens and smother your workspace. Parades being conducted outside in your honor reminiscent of a Ferris Bueller’s day off, all hailing that bit of code you developed.

End of the Nerd fantasy, let’s fast forward to now… Your dream sequence abruptly ends when Subject Matter Expert Beth accidentally deleted the semicolon at the end of your JavaScript statement. Or, even worse, the code you have on the site (before rendered) just scared Intimidated User Jerry and he refuses to add content to the site, because he “doesn’t want to break it”.

Don't go breaking my code

Getting your content to display in a predictable, ordered way still requires some occasional styling, and thus adding code that end users can’t see, but could easily disturbed. Even when you wanted to limit the type of information users could enter/view on a page, sometimes the extra wiggle room was a little too much to avoid touching code.

Previously a CMS administrator would drop in code through code insertion points into designated parts of the page, and the user would still have to look at it, and possibly interact with it.

Percussion’s new Widget Builder allows more advanced users to create custom widgets, separate code from display, and give the end user simple text, rich text, and image fields to enter content. I want to show you how to create a custom widget to show structured content—in this case, a page for displaying information on the tallest buildings in the world.

Step 1: Log into Percussion CMS, select Widget Builder view, and create a new widget

Just like Dashboard, Navigation, Design, and other administrator-level views, Widget Builder is available from the main drop-down menu in Percussion CMS.

Also to read more, please refer to our help pages on this feature (Widget Builder is now available on the newest 3.3 release of Percussion).

Step 2: Enter information about your widget

This information is to help you remember the purpose of the widget, and make it easy for users to find it in the widget menu when editing layout.

Step 3: Add and name custom fields 

Our custom fields will be what the user interacts with when entering content, and the type of field you choose controls what type of content can be entered, and where.

Your field type cheat sheet:

  1. Text is simple text, typically used for “Titles, Author’s, etc” no WYSIWYG
  2. Rich Text allows the user to be given a rich text area, with the WYSIWYG editor
  3. Date gives the user the ability to pick a date from a drop down calendar
  4. Text area gives the user more space to enter content, but not necessarily have the ability to use the rich text editor (it's better for content that you don’t want the user to have any styling preferences)
  5. Photo allows the user to either upload a photo, or use one from the site library

Because I want to feature information about the world’s tallest buildings, I select and name my custom fields accordingly, allowing users to enter the building name, height, and other information in a pre-determined order.

Step 4: Add style and function code

If we had some JavaScript/CSS to enhance the display or functionality of the widget, I could add that here. We do suggest for best practice to create a separate style sheet for your widget. The rationale behind that is it makes it one central file for you to edit, and allows for it to be easily modified and changed without having to search through your website’s main CSS file. The files you upload are easily referenced through the Resources tab. 

For proof of concept you can deploy your code into a regular HTML widget and preview it on your page, but once you have configured the widget, we suggest you go back and create its own CSS file.

Step 5: Generate display code automatically

“Percussion, do some work for me” (let Percussion auto generate some of the code for you). This is where you can make some additional edits, tag elements with the correct classes corresponding to your CSS, and so forth.

Step 6: Deploy the widget

Let’s add the widget to our site by clicking the deploy icon. This will allow you to find your widget in the widgets tray when working on a page layout, and drag and drop it into your page like any other widget.

Step 7: Add your widget to a page

In the layout tab of your page template, choose “Add Widget” and in the Type menu, choose “Custom” to display any custom widgets you’ve created. You can then click the widget, drag it over to the intended location on your page, and drop it into the layout.

Step 8: Add content to your shiny new widget

This is where you can hand off the widget to your contributors, enabling them to add only the content you want, structured exactly as you intended it. 

The result: you can now use the widget in a layout (or multiple widgets even) to control the display and type of content you want your users to contribute. Any code pertaining to style, display, or added functionality, is hidden away from the end user, meaning no one can accidentally break or delete what you’ve built. It’s like a dream come true. 

For any questions regarding the widget builder, or questions for creating your own widget, feel free to post a comment below, or start a conversation in our customer community.

Chris Burns Headshot
Chris Burns
Pre-sales Engineer | Percussion Software

Chris Burns studies computer science part time as a graduate student at Boston University. In his downtime he enjoys casually nerding out on his Arduino/Raspberry Pi. His philanthropic efforts entail handling any/all computer/technical support for his family/friends. At Percussion, he loves to show new customers the possibilities of working with our CMS. Chris is also a dedicated humanitarian and lived abroad for one year in South Korea while teaching English as a second language.