The {stringify} block is a custom extension to the TrimPath parser used by NewsGator widgets. It turns everything inside the block into a Javascript string, which you can then use. As with other TrimPath block expressions, you can use any syntax you want inside of it, including newlines and curly braces.

Note that tokens and TrimPath expressions inside the {stringify} block are put into the resulting string verbatim – tokens will not be replaced with values, and TrimPath expressions will not be evaluated. This feature is similar to a TrimPath {cdata} block.

What Is It Good For?

The primary purpose for a {stringify} block is to get “subtemplates” into your widget. For instance, some complex widgets have a master widget with many subordinates. Using {stringify} with other features of the widget framework allows you to specify the template for the subordinate widgets inside the master, rather than copying it into each subordinate widget. Another example is for popups that are not rendered until they are needed, for instance in a Google Maps mashup.

In general it’s useful for long chunks of text that would be inconvenient to escape into Javascript strings.

How Do I Use It?

The syntax for a {stringify} block is similar to the long form used for a {cdata} block. It begins with a {stringify} statement that must also include a variable name. The variable name will contain the resulting string, and also acts as the delimited that closes the {stringify} block. Once again, the {stringify} block is closed by repeating the variable name used to open it, not with a closing {/stringify} statement.

For example, paste the following into the HTML Template section of your widget:

{stringify MyText}

  This is a stringify block.

MyText

This will create a Javascript variable named “MyText” with the value “This is a stringify block”. Now, paste the following into the HTML Template section:

            {stringify TextWithTokens}

                        This text includes

{if false}

TrimPath syntax:

                        {/if}

                        and tokens: ${Post.PostId}

            TextWithTokens

{eval}

            alert(TextWithTokens);

{/eval}

Now preview the template. You should see an alert box with the exact text inside the {stringify} block. Notice that it includes all the TrimPath syntax.

Note that the variable created by {stringify} is only visible within the context of the HTML template, unless you take steps to make it available elsewhere. One of the easiest ways to save it is to attach is to the BuzzObj for later retrieval. For example:

            {stringify CheckboxTemplate}

                        …code here…

            CheckboxTemplate

            {eval}

                        BuzzObj.CheckboxTemplate = CheckboxTemplate;

            {/eval}

Advantages Over HTML Elements

An effect similar to this can be accomplished by writing out an HTML <textarea>, <pre> or other element containing the text you want, and then reading that from the document using the element’s innerHTML property. However, this approach is harder than it at first seems. The text returned by innerHTML is not exactly the same as the text you put inside the element. Various browsers will remove quotes around some attributes, apply HTML escaping, eliminate or add tags and perform other modifications. This can lead to very difficult to detect bugs. {stringify} has none of these problems. There are also problems that, while solvable, make this approach unnecessarily difficult. You’ll be happier if you just use {stringify}.

Notes

{stringify} is especially well suited for use with the renderTemplate() function described elsewhere.