Tutorial

The usage pattern is as follows:

• Use the MarkupGen_html_newElem function to generate as many HTML elements as needed.
  • This produces an intermediate representation.
  • Elements may be nested.
  • For the contents of an element, you may pass another element, an Appian primitive such as text or number, or an array combining any of those.
• As a final step, use MarkupGen_html_toText. This produces text with all the content.
  • For input, you may provide an element, an Appian primitive such as text or number, or an array combining any of those.

For XML generation, the pattern is the same. All you need to do is to use the functions that start with MarkupGen_xml instead.

Creating an element

MarkupGen_html_newElem("a", {href: "www.wikipedia.org"},
   "Click here for more details"
)

This produces an intermediate representation that includes the following HTML content:

<a href="www.wikipedia.org">Click here for more details</a>

The function arguments we provided were:

1. The name of the HTML element. In this case we used an anchor, "a".
2. The attributes of the HTML element. Use an Appian dictionary for this: surround key-value pairs with curly braces. In the example,we assigned href a value of www.wikipedia.org. When you don't need any attributes for an element, you may provide a value of null.
3. The contents of the element. In this case we passed a text value.

Automatic escaping of text values

Consider the following example, similar to the previous one:

MarkupGen_html_newElem("a", {href: "www.wikipedia.org"},
    "Go to <Wikipedia>"
)

The contents passed as text will be escaped automatically:

<a href="www.wikipedia.org">Go to &lt;Wikipedia&gt;</a>

Although not explicitly mentioned in other examples, text values are always HTML-escaped when using the plugin functions. This means that there's no need to call functions such as toHtml.

Caution: although contents are HTML escaped, if you needed to generate dynamic JavaScript that was introduced inside HTML elements or attributes, then you need to also use explicit mechanisms for escaping/encoded not covered by this plugin.

Passing more than one value

MarkupGen_html_newElem("a", {href: "www.wikipedia.org"},  
   {
     "Click here ",
     "for more details"
   }
)

This will produce the same output as the first example. There's no real need to split two text values but this exemplifies passing in more than one value, which is important for upcoming examples.

Notice that to pass multiple values we use an Appian array in curly braces.

As a reminder, in Appian, both arrays and dictionaries are represented with curly braces around them. The difference is that dictionaries contain key-value pairs, e.g. {x:5, y:10}. Arrays contain a comma-separated list, e.g. {2,4,6}.

Passing a nested element

We will now nest a <b> element inside an <a> element.

MarkupGen_html_newElem("a", {href: "www.wikipedia.org"},  
   {
     "Click ",
     MarkupGen_html_newElem("b", null, "here"),
     " for more details"
   }
)

The intermediate representation will contain:

<a href="www.wikipedia.org">Click <b>here</b> for more details</a>

Producing HTML output

Going back to our first example, notice that if you call MarkupGen_html_newElem this way:

MarkupGen_html_newElem("a", {href: "www.wikipedia.org"}, 
     "Click here for more details"
)

it actually returns an object of type MarkupGen_HtmlPart with a value of

internalHtmlVal: 
   "/HTML/=<a href="www.wikipedia.org">Click here for more details</a>"

Internal values are meant to be opaque. The value itself can be seen but it's not meant to be accessed by anything other than functions of this plugin. For example, don't try to get a substring of internalHtmlVal in order to get the HTML content. Futhermore, don't expect the object attribute name or value pattern to remain the same between plugin versions.

To actually produce HTML output, it's necessary to call MarkupGen_html_toText. So, if in our previous example the final result we wanted to produce was only that <a> element, then we would use the following code:

markupgen_html_totext(
    MarkupGen_html_newElem("a", {href: "www.wikipedia.org"},
        "Click here for more details"
    )
)

which would produce Text with exactly the following value:

<a href="www.wikipedia.org">Click here for more details</a>