Tag Archives: snippets

Snippet Parameterization for Flare HTML5 Output Using AngularJS

Wouldn’t it be nice to be able to do this with snippets?

This is content in a snippet. Every time this snippet is used, the content is the same except for here: x

This is content in a snippet. Every time this snippet is used, the content is the same except for here: y

This is content in a snippet. Every time this snippet is used, the content is the same except for here: z

The text is the same except for one part that varies. The above could be accomplished with condition tags. But each value (x, y, and z) would require a separate condition tag. Without condition tags, three separate snippets would be necessary, four if the repeated content is to be reused. This post describes how to do the above with one snippet and AngularJS.

Maybe this post could use a simpler title. But the point is that variables in Flare are applied globally in outputs. To introduce locally varying behavior with Flare, additional condition tags, snippets, or variables must be added for each desired local behavior. In other words, Flare variables are global and condition tags and snippets are not convenient replacements for variables, local or global.

This has been discussed in previous posts in the context of a Flare to MediaWiki to Flare round trip. MediaWiki enables transclusion of content with MediaWiki templates. MediaWiki templates can have parameters. So MediaWiki supports locally varying behavior in transcluded content.

This poses a problem for exporting to MediaWiki and importing from MediaWiki. The closest Flare comes to MediaWiki templates is Flare snippets. Flare snippets do allow for locally varying behavior via conditions and snippet conditions. But that does not quite meet the functionality of MediaWiki templates.

But that’s okay. Flare is a single-source, multi-channel authoring tool and MediaWiki is a platform for wikis. These are different animals. Parameterization of snippets would be nice to have. But then again, it would introduce complications.

One way to add parameterization of snippets is with scripting. Unfortunately, a JavaScript solution limits the use to web-based outputs. The example which follows is only effective with HTML5 output.

AngularJS comes from Google. It is a JavaScript library which can be referenced in Flare content such as a snippet, topic, or master page. This example references the library on a master page. Here is the markup for the master page:

The first script reference is to a public copy of the AngularJS library. The AngularJS documentation has some guidance about how to reference the library. Although there is guidance to place the reference at the bottom of the document for performance, this example places the reference at the top. Otherwise the variable content may briefly appear in the browser as it does in the snippet markup instead of as the parameter value.

The second script reference is to a JavaScript file which contains the AngularJS controllers and data used to implement parameters on snippets and to hold the values for those parameters. Keep in mind that this example is a simple use of AngularJS. The data and presentation concerns are separated in that the snippet lives in the markup and the controller and data (parameter values) live in a JavaScript file. But the idea behind AngularJS is to implement the Model View Controller pattern. This usage doesn’t go quite as far as building an application based on that pattern.

There is also an extra attribute in the body tag that tells AngularJS where to provide AngularJS functionality.

Now here is the topic:

There are two snippet references. Each is wrapped in a div tag. The attributes in these tags refer to controllers in the JavaScript file referenced on the master page. The controller cannot be applied to the snippet tag because that tag is replaced with the snippet when output is generated.

Remember, the point is there is only one snippet. Here is the snippet markup:

The snippet has some text and this: {{name}}. This is a data binding. You can read about this special AngularJS markup here: ngBind and in the hello world. On that note, this post’s example is almost as simple as the hello world. The main complication is how to organize the Flare and AngularJS pieces.

Every instance of {{name}} will be replaced with the value in the controller reference in the div attribute data-ng-controller. This example implements a single parameter of ‘name’ for the snippet.

Here are the controllers for the snippets:

These are located in a file in the path Content\Resources\Data\topic-parameter-controllers.js. This script is loaded on the master page.

Here is the output. In the first instance of the snippet the name is Jack. In the second instance the name is Jill.

angularjs-example

Snippet parameterization for HTML5 output has been implemented. A zipped sample is here: http://tregner.com/example-projects/angular-example.flprjzip.

Flare to MediaWiki to Flare (part 6, of wiki template articles and snippets)

A mapping effort chronicled in a blog is less than exciting to read. So let’s switch gears and lay some groundwork for the parser. We will use a Wikipedia article as the first test and as a guide for what parts of the markup to tackle firstly. Since wikis are moving targets, we will work with the markup at a specific point in time.

This discussion is going to become complicated very fast. It may seem overly complicated. But rest assured that the parser will be doing the work both ways and the complex structures created in Flare to solve the issues we encounter aren’t much more complex than the wiki markup itself.

The article is http://en.wikipedia.org/wiki/Data_mapping. We can see the source for the article by switching to the Edit tab at http://en.wikipedia.org/w/index.php?title=Data_mapping&action=edit. For my use, I copied the markup to a text file. But remember, we have already established that the markup can be retrieved with an API.

The markup begins with this line followed by an empty line:

{{Data transformation}}

The double curly braces indicate a template. Templates are described in http://en.wikipedia.org/wiki/Help:Template. The term, template, surprises me because templates are pages which can be used in other pages. Snippet or boilerplate would have made more sense to me. But with MediaWiki, templates are for content reuse.

How do we track down that template? Templates can be maintained in the Template namespace. Let’s see if that works. Look here: http://en.wikipedia.org/wiki/Template:Data_transformation.

The template is there. As of writing, it establishes a box in the upper right-hand corner of the article which provides links to data transformation topics. So we will need to pull that article over during import. At the moment, I’m leaning toward storing template articles as snippets and using a naming convention for the snippet files which indicates the file’s status as a Flare version of a wiki template.

Snippets help: http://webhelp.madcapsoftware.com/flare8/Content/Snippets/About_Snippets.htm

This popped up in a Google search: http://www.contentinsomnia.net/reusing-content-on-wikis-and-blogs/. I thought I would share the link since it confirms someone else equates Flare snippets with MediaWiki templates.

For the Flare markup, we can use this:

<MadCap:snippetBlock src=”../Snippets/Template_Data_transformation.flsnp” />

We could use a regular expression for this since the object is replace {{ with:

<MadCap:snippetBlock src=”../Snippets/Template_

And }} with:

.flsnp” />

We should also retain the line ending. This replacement is our rule A for now. Rule B is to record the template name for future export and import. By the way, there is an export option to include templates with http://www.mediawiki.org/wiki/Special:Export.

The third line in the markup is:

{{inline|date=June 2010}}

There are more curly braces. But the contents of the braces seem more complex. The first part indicates another template: http://en.wikipedia.org/wiki/Template:Inline. But the second part indicates to display a date. The template article includes instructions about how to use the Inline template. The template is an appeal to improve the article because the citations are insufficient. The date portion is a parameter: http://www.mediawiki.org/wiki/Help:Templates#Parameters. This must be why it is called a template and not a snippet. How are we going to handle parameters in a snippet? Conditions, variables, something else?

A condition applied to the markup for the snippet block is an attribute for the snippet block element. This makes a condition attractive. But imagine how many conditions we would introduce as we imported more templates with more parameters. Besides, the condition doesn’t influence the appearance of the content until a target is generated. What to include or exclude is set on targets. Similarly, variable values are set on targets. Conditions and variables don’t give us what we want.

What about styles?

That feels closer. But unfortunately, which style to use is established in the markup with a class attribute. An element only gets one of those. If class is used, every parameter value would have to be conveyed through that one attribute. We want class for styles and we don’t want hundreds of MediaWiki template parameter mapped styles.

We could also consider grouping the snippet block in a div element with other elements to represent the parameters. But unfortunately some parameters influence the text of the MediaWiki template article. With the Inline template, you can replace the word article with another word indicated in a parameter. How can we achieve parity with the wiki if this is the case? This is an important decision point. We should convey the parameters to Flare so we can make the round trip. But how concerned are we about the way the parameters are manifested in Flare? In this case, we are probably not very concerned. But the meaning of the template can be changed drastically with a parameter. We must address it.

We can address it with a new attribute. But if we do that, we will run into problems conveying the parameters if the snippet is used elsewhere with different parameters. We will convey the parameters within the name of the snippet itself.

<MadCap:snippetBlock src=”../Snippets/Template_Inline|date=June 2010.flsnp”  />

I’m not sure about the pipe character in the markup, I’ll have to check. Secondly, we can place the parameter information in the snippet so as to display in Flare as intended. We can use another snippet within the template snippet for the parameter.

Snippet propagation.

It can be named according to the template and the parameter and contain the appropriate value. When the round trip is completed, the snippet block for the parameter will be translated to the markup in the template which declares the parameter. But the parameter snippet content will not be conveyed. That content is just for Flare. We can see the markup for the Inline template here: http://en.wikipedia.org/w/index.php?title=Template:No_footnotes&action=edit.

Only one version of the snippet contents will be parsed back into wiki markup when the round trip is completed. But the parameter values will still be parsed from the template snippet names. But what if we want to edit a snippet for the template and have the changes propagate to other versions of the template? You guessed it.

More snippet propagation!

All of the content in between snippets for parameters can also be snippets. This way someone can drill down and make changes in Flare which will be reflected in each parameter set version for the snippet for the wiki template article.

The ground rules and guidelines are:

  1. Don’t rename these snippets. Renaming will change the parameter values returned to the wiki on completion of the round trip.
  2. Only create new snippets as needed. Name the template snippets and parameter snippets according to the template article name and parameter values. Follow the convention strictly. The new parameters will convey to the wiki.
  3. Consider that template changes in wikis are a big deal. Don’t take them lightly.

Wikis use bots and people to maintain things like parameters in transclusions. We are attempting to maintain a similar structure in Flare without the advantage of bots. It may be a good idea to create a validation algorithm to check these projects periodically or even constantly just to ensure the Flare side is maintained such that the wiki is respected.

And on to line 4 of the wiki markup…