DotNetNuke

DotNetNuke Widgets Guide (Part 2 of 4)

December 29, 2009

author:

DotNetNuke Widgets Guide (Part 2 of 4)

WidgetsThis is Part 2 of my four-part series on DotNetNuke Widgets. In Part 1 of the series, I covered some fundamental concepts related to DotNetNuke Widgets. In this post, I will introduce you to a few of the Widgets that are included with the DotNetNuke distribution. Before getting started I’d like to make one observation…these widgets were created prior to the inclusion of jQuery within the DotNetNuke Core. While the Widgets are production-ready, they could use some refactoring to take advantage of jQuery’s efficient engine for selecting and manipulating DOM elements.

All Widgets follow the same format for embedding in any extension (module, skin, skin object, container)

<object codebase="{WidgetType}" codetype="dotnetnuke/client" id="{WidgetId}">
	<param name="{WidgetParameterName}" value="{WidgetParameterValue}" />
</object>

{WidgetType} (required) = fully qualified Type name of the Widget
{WidgetId} (required) = arbitrary ID for the Widget’s DOM element (must be unique on the page)

A Widget can have zero or more child elements, each with a “name” and “value” attribute with corresponding {WidgetParameterName} and {WidgetParameterValue} values. Widget parameter names are case-insensitive. Widget parameter values are always case-sensitive.

StyleScrubberWidget

The purpose of this Widget is to “scrub” the appearance of a DotNetNuke page by removing undesirable attributes from specific elements on the page. For example, you may have a module that has a hard-coded “style” or “width” attribute that is disrupting the appearance of a page. You don’t really want to change the source code for the module (if it’s available) and you really want to use the module. This is where StyleScrubber Widget comes to the rescue. It enumerates a series of rules you provide and removes the undesirable attributes allowing elements to be fully styled with CSS. This Widget may appear any number of times on a page.

Parameters

classNames (required) – A list of class names separated by semi-colons. The Widget will only act on elements with a matching “class” attribute. At least one value must be specified. Example: head; normal; topic

tag (optional) – A HTML element tag name which acts as a filter in selecting elements. The default value is * which implies all elements. Example: div

removeAttribute (optional) – The name of the attribute which should be stripped from all elements that match the classNames and tag conditions. The removeAttribute parameter may be repeated multiple times to specify more than one attribute that should be removed. Example: style (strips the “style” attribute)

recursive (optional) – Value of true or false to indicate if the scrubbing cascades indiscriminately through all child elements of a matched element. Default is false.

Example

Remove all “width” and “style” attributes from TABLE elements that have a class value of “Normal” or “NormalBold”

<object codebase="StyleScrubberWidget" codetype="dotnetnuke/client" id="ScrubTable">
	<param name="classNames" value="Normal;NormalBold" />
	<param name="tag" value="table" />
	<param name="removeAttribute" value="width" />
	<param name="removeAttribute" value="style" />
</object>
RelocationWidget

The purpose of this Widget is to move or “relocate” content so that they visual location of the content differs from the physical location of the content in the page. The primary use-case is SEO. Using the RelocationWidget it is possible to have content as close to the top of the page as possible while moving the navigation lower down on the page. Since search bots do not run scripts, this arrangement is optimal for them. Users with script-enabled browsers will see the navigation in its intended location. This Widget may appear any number of times on a page.

Parameters

sourceId (required) – ID of the DOM element that contains the HTML content that will be relocated. It is recommended that you apply a CSS style of “display:none” to this element so it is not initially visible in the user’s browser.

targetId (required) – ID of the DOM element where the HTML content from the sourceId element will be moved. It is recommended that you apply a CSS style for “width” and “height” matching the dimensions that the relocated content will occupy. Doing so prevents other elements on the page from visually moving around when the Widget performs its action.

Example

Move all content from element “NavTemp” to “Nav”

<object codebase="RelocationWidget" codetype="dotnetnuke/client" id="MoveIt">
	<param name="sourceId" value="NavTemp" />
	<param name="targetId" value="Nav" />
</object>
RotatorWidget

Changes content within an element at a pre-defined interval. The content can be sourced from a location on the page, an RSS feed or sequentially numbered images. This widget is ideal for scenarios in which the content to be rotated is not known ahead of time and no interactivity is desired from the end-user. This Widget may appear any number of times on a page.

Parameters

elementId (required) – ID of the DOM element where the rotating content will be rendered.

height (required) – Height of the rotated content in pixels.

width (required) – Width of the rotated content in pixels

interval (optional) – Time interval in milliseconds for content rotation. Default is 2500 milliseconds.

direction (optional) – Direction in which new content slides. Values are UP, DOWN, RIGHT, LEFT (default), BLEND

transition (optional, experimental) – Transition effect for new content. Values are SLIDE, SNAP (default)

The RotatorWidget can rotate content from three sources. Content from all the sources is aggregated, then displayed so you can combine multiple sources in the same RotatorWidget instance if desired.

RSS Feed Source

feedUrl (required for RSS feeds) – URL of the RSS 2.0 feed from which content will be sourced

feedAttribute (required for RSS feeds) – Name of the element that contains the content to be rotated. Yahoo Pipes is used to retrieve the feed.

Sequential Image Source

imageUrl (required for images) – The base URL where the images to be rotated are located. Must end in slash (“/”).

imageTemplate (required for images) – The file name template for each image. The token {INDEX} may be used to indicate where the sequence number will be injected. The sequence begins at 1. Example: portrait{INDEX}.jpg for images names portrait1.jpg, portrait2.jpg, portrait3.jpg etc.

imageCount (required for images) – The number of images available for rotation.

imageScale (optional) – Indicates if images should be scaled by width or by height. Values are WIDTH and HEIGHT or blank (default) for no scaling.

Page Content Source

contentElementId (required for content) – ID of the DOM element that contains the content to be rotated. The Widget expects the DOM element to have zero or more child elements. The content of each child element is treated as a separate rotation item. Example: A <UL> element with multiple <LI> elements where each <LI> element contains one item of content.

Example

Rotate 10 images stored in a folder at an interval of 5 seconds.

&lt;object codebase=&quot;RotatorWidget&quot; codetype=&quot;dotnetnuke/client&quot; id=&quot;Animate&quot;&gt;
	&lt;param name=&quot;elementId&quot; value=&quot;PageHeader&quot; /&gt;
	&lt;param name=&quot;height&quot; value=&quot;100&quot; /&gt;
	&lt;param name=&quot;width&quot; value=&quot;400&quot; /&gt;
	&lt;param name=&quot;interval&quot; value=&quot;5000&quot; /&gt;
	&lt;param name=&quot;imageUrl&quot; value=&quot;/Portals/0/HeaderImages/&quot; /&gt;
	&lt;param name=&quot;imageTemplate&quot; value=&quot;header{INDEX}.png&quot; /&gt;
	&lt;param name=&quot;imageCount&quot; value=&quot;10&quot; /&gt;
&lt;/object&gt;
StyleSheetWidget

The purpose of this Widget is to provide a user interface that enables users to switch stylesheets in order to customize their browsing experience. This Widget may appear any number of times on a page.

Parameters

template (required) – The StyleSheetWidget renders an interface element for each stylesheet that the user can select from. The template parameter is used to specify the HTML markup that will be rendered for each stylesheet in the set. The HTML markup must be encoded and can use the tokens {TEXT} (replaced with the name of each stylesheet as specified in other parameters), {ID} (replaced with a unique identifier for each interface element that is rendered) and {CLASS} (replaced with “class” attribute and value). Example: <div title=”{TEXT}” {ID} {CLASS}></div>

default (required) – The value of the stylesheet that should be selected by default.

baseUrl (required) – The URL where the stylesheets are located.

cssClass (required) – The CSS class value to be used on interface elements corresponding to a stylesheet that is not selected.

selectedCssClass (required) – The CSS class value to be used on the interface element corresponding to the selected stylesheet.

In addition to the above, one parameter (name and value) is required for each stylesheet. The “name” attribute should contain the stylesheet filename and the “value” attribute should contain the human-friendly label associated with the stylesheet.

Example

Allow the user to select from five different color palettes.

&lt;object codebase=&quot;StyleSheetWidget&quot; codetype=&quot;dotnetnuke/client&quot; id=&quot;ColorSelector&quot;&gt;
	&lt;param name=&quot;template&quot; value=&quot;&amp;lt;div title=&quot;{TEXT}&quot; {ID} {CLASS}&amp;gt;&amp;lt;/div&amp;gt;&quot; /&gt;
	&lt;param name=&quot;default&quot; value=&quot;blue&quot; /&gt;
	&lt;param name=&quot;baseUrl&quot; value=&quot;&lt;%= SkinPath %&gt;css/&quot; /&gt;
	&lt;param name=&quot;cssClass&quot; value=&quot;Icon&quot; /&gt;
	&lt;param name=&quot;selectedCssClass&quot; value=&quot;Icon-Selected&quot; /&gt;
	&lt;param name=&quot;red&quot; value=&quot;Fire-engine Red&quot; /&gt;
	&lt;param name=&quot;blue&quot; value=&quot;Midnight Blue&quot; /&gt;
	&lt;param name=&quot;yellow&quot; value=&quot;Sunflower Yellow&quot; /&gt;
&lt;/object&gt;
EmbedWidget

This Widget is somewhat unique in that its purpose is to provide a standard way for embedding any embeddable content from other websites. Using this Widget, you create a “snippet” for any such content once using whatever unique requirements the source site may have. Once the snippet is created, you can then use the embeddable content multiple times within DotNetNuke using the standard Widget embedding syntax.

Parameters

publisher (required for user content) – This parameter tells the EmbedWidget where to look for the embeddable content. If it is not specified, the Widget looks for content in the folder “~/Resources/Widgets/DNN/EmbedWidgetResources/{type parameter value}/” If this parameter is specified, the Widget looks for content in the folder “~/Resources/Widgets/User/{publisher parameter value}/EmbedWidgetResources/{type parameter value}/”

type (required) – The type of content to embed. This value must correspond to a file named “{lowercase type parameter value}.snippet.htm” in the folder location specified above. The file must be a plain-text file containing solely the HTML markup necessary for rendering the content.

In addition to the above parameters, you can specify and arbitrary number of name/value parameters that are passed to the content snippet file when the content is rendered by the Widget. The value may be a single value or multiple values concatenated using a delimiter character. The default delimiter is “;”. You can overrride the delimiter by specifying the “multiValueDelimiter” parameter described below. Review the individual snippet file for each type of embeddable content for supported parameters specific to that content type.

multiValueDelimiter (optional) – Character used to delimit multi-value parameters.

When the Widget is rendered, the snippet file is parsed and token substitution is performed using values specified in the parameters. The syntax for tokens is:

{ parameter name : token template : default template }

For each token, the Widget checks to see if a corresponding named parameter is available. If so, it replaces the token with the token template otherwise it uses the default template. In order to substitute parameter values in the token template, placeholders are used. Placeholders are numeric and in the format {0}, {1}, {2} etc. The Widget substitutes values in the order they are specified.

For example: { width : width=”{0}” : width=”500″ } OR { coordinates : x={0},y={1} : x=100,y=100 }

Example

Embed a Flickr slideshow

&lt;object codebase=&quot;EmbedWidget&quot; codetype=&quot;dotnetnuke/client&quot; id=&quot;Flickr&quot;&gt;
	&lt;param name=&quot;type&quot; value=&quot;Flickr&quot; /&gt;
&lt;/object&gt;
VisibilityWidget

The purpose of this Widget is to enable an HTML element on a page to toggle the visibility of a container element located elsewhere on the page. The Widget included with DotNetNuke is now deprecated. Joe Brinkman has updated the Widget’s code and the updated one will be available in a future DotNetNuke release. You can read all about Joe’s enhancements in his blog post DotNetNuke Tips and Tricks #15: DotNetNuke Visibility Widget.

Co-founder/CTO WhenHub; co-founder DNN Software; founder Edaptable; educator; Open Source proponent; Microsoft MVP; tech geek; creative thinker; husband; dad. Personal blog: http://www.kalyani.com. Twitter: @techbubble
21 Comments
  1. John

    Superb Nik! Many of us have been curious about this topic. I'd love to see a nice way to remove user's poorly styled <font/> entries from HTML blocks (leaving only CSStostyle them) and I suspect the StyleScrubberWidget will work great for this!

  2. [...] DotNetNuke. If you haven’t already done so, read Part 1 (overview of DotNetNuke Widgets) and Part 2 (DotNetNuke Widgets reference) to better understand the concepts explored in this post. Let’s [...]

  3. Andrew

    Maybe instead of the scrubber widget removing unwanted code, someone could create a compatibility widget for people who rely on that unwanted code. They can add it in if they need all of those width, font, color, etc tags added in. I'd rather start with clean code and let people choose to dirty it up rather than patching dirty code...

    • techbubble

      I'm trying to picture a usage scenario and am not very clear. The StyleScrubber widget exists to address scenarios where you want to use a certain module, but the markup it emits is not XHTML compliant. What scenario(s) would the compatibility widget be used under? Also, would it just use standard jQuery selectors or some other means to identify which elements would have attributes added? It's pretty trivial to remove attributes, but adding them requires more work and I'm trying to understand a practical usage scenario before I venture to create such a widget.

      • Andrew

        You're right--adding things back in is much harder than taking it out. I guess I was thinking more along the lines of there being a DNN 'compatibility mode' that, if switched off, wouldn't emit any of the default styling--more of a server-side version of what this does. Since this widget is client-side, is there any sort of delay while it runs (like the 'dreaded' FOUT problem w.r.t. web fonts)?

        • techbubble

          When the widget runs it takes a finite amount of time to execute, the duration of which depends on the number of matching elements. In most cases, this is imperceptible. However, if there is a significant visual impact due to its running, the user will notice elements shifting around. This is expected and in order to overcome it, the code would have to be manipulated server-side as you pointed out.

  4. Arpat

    nice topic.
    i am looking to use this VisibilityWidget to create a spoiler to use inside text/html in the forum. Somehow it seems to me that this has to be easy, but so far i was unsuccesful.
    the spoiler would be something like:
    [spoiler={optional}] {parameter} [/spoiler]

    resulting in a "spoiler" = Optional comment, click (or hoover over) to open:
    and here is hidden the spoiler tekst.

    am i correct it can be done with the visibility widget?
    or do i need to use another approach?

    • techbubble

      Interesting use case, and certainly one that would work. My guess is that the forum module is encoding the widget markup preventing it from being executed. Is there a reference URL where I can see this?

      • Arpat

        this site uses "a" spoiler http://pbphouse.com/forum/index.php?topic=2941....
        and here they show a similar jQuery technique
        http://www.learningjquery.com/2007/02/more-show...
        the syntax i expect to use is for active forums from wwww.activemodules.com (or the regular forum from www.dotnetnuke.com
        i expect users to use a [spioler={option}] param [/spioler] with a clickable link and hidden text. (spioler is spoiler ofcourse :)
        i am now learning how to add code so i can experiment on my technowebiste www.it-pro.nl (forums)

        my biggest problem is that every site tels me to add code, but not how and where. what do i need to do step by step to get a spoiler on a text/html module. :-)

        i'll find it out, just takes a few hours (or days in current case for me)

      • Paul Fijma

        i noticed i had made my forum invisible for everybody (not too smart if you want people to look at it ;)

        (due to twitterlogin i am now: Paul Fijma aka Arpat )

  5. [...] cannot be overridden with CSS, users are forced to edit the markup, use Javascript or the StyleScrubber Widget to neutralize the impact of a module’s inline style attribute on other elements of a [...]

  6. uberVU - social comments

    Social comments and analytics for this post... This post was mentioned on Twitter by techbubble: Blogged: DotNetNuke Widgets Guide (Part 2 of 4) http://bit.ly/8nvTs9...

  7. Tim

    I've been playing around with the default widgets and I am having some issues with the VisibilityWidget in dnn 5.2.2. I have a fresh install, and the only third party module im using is the Telerik Rad Controls. All of the other widgets are displaying fine in the the Extropy Beta skin. The only one thats not getting rendered is the VisibilityWidget.

    The default in that skin doesnt render at all:

    <object id="Toolbox" codetype="dotnetnuke/client" codebase="VisibilityWidget" declare="declare">
    <param name="expandClassName" value="Layout-Masthead-InfoBar-ToolBoxIcon-Expanded" />
    <param name="collapseClassName" value="Layout-Masthead-InfoBar-ToolBoxIcon-Collapsed" />
    <param name="targetElementId" value="Layout-ToolBox" />
    <param name="title" value="Toolbox" />
    </object>

    So i tried a couple other variations looking at the parameter names in the VisibilityWidget.js.


    <object id="Toggle" codetype="dotnetnuke/client" codebase="VisibilityWidget" declare="declare" >
    <param name="closeElementId" value="ToolBoxIcon" />
    <param name="targetElementId" value="Layout-ToolBox" />
    <param name="eventsourceElementId" value="ToolBoxIcon" />
    </object>

    <div id="ToolBoxIcon" class="Layout-Masthead-InfoBar-ToolBoxIcon-Collapsed"></div>

    With this variation i get atleast an icon with the div element, but again the widget is not being rendered so no functionality is added to the element. I'm not sure where im going wrong. I do wonder if something is bugged in that widget. In the summary section of the this widget it references the StyleSheetWidget...so im wondering if something else is typo'd. Any ideas?

  8. david

    Implemented the Rotator Widget and it does the job just fine.
    However, How do I wrap text around the images that are rotated?
    This is easy with a static image but I have been unable to work it out when using the widget.

  9. BioChemSoc

    I tried using the StyleSheetWidget, and it seemed to work fine on all the browsers I tried but IE6, where the widget appeared ok, and processed the first event, then wouldn't ever fire an onclick event. Is this a bug with the widget?

    • techbubble

      That's a possibility. I only did some cursory testing on IE6 and most likely broke it during some refactoring. I don't have IE6 readily available so I'll need to setup a VM to figure out the cause. I'll see what I an do...

      • BioChemSoc

        I would greatly appreciate that.

  10. Anonymous

    I am trying and failing to get Disqus comments on my dnn site but despite the excellent instructions here.... I am not getting it. Any example code for disqus?

  11. Game4453

    Hi, I like use Imagevenue but sometimes it fail, now I have used www.isphotobomb.com and is very great. Keep in touch. Regards

  12. backpacking tents dogs

    I do not know if it's just me or if perhaps everyone else experiencing problems with your blog. It appears as though some of the text on your content are running off the screen. Can someone else please comment and let me know if this is happening to them too? This may be a problem with my browser because I've had this happen previously. Cheers My website - backpacking tents dogs

  13. Steve Holton

    Hows abouta link to parts 3 and 4?? I only found part 2 by plugging in "...part-2.." in the URL from part 1 (part 1 did not have a link to part 2, either, so I had to "punt" to get to #2...), but inserting "..part-3..." and "...part-4...) get a 404.

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.