Monthly Archives: June 2013

Clear a Flare HTML5 Search Field with the Escape Key

If you want the search field in Flare HTML5 output to clear when escape is pressed, add the following to the toolbar JavaScript.

If there is already a window.onload assignment, just add the inner part to the existing assignment.

Resources:

 

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.

Embellishing the jQuery Slides with Fade Effects

If you saw yesterday’s post, you may have asked, why include the function that does nothing in the parameters for the calls to slideUp() and slideDown()? For yesterday’s example, there is no good reason. The functions will work with no parameters. The first parameter passed is duration. Slow is a nice speed. According to slideUp() and slideDown() documentation, the duration is 600 milliseconds.

The second parameter is a deferred callback function. When included in the parameters, this ‘complete’ function is called at the end. For example other jQuery effects can be used to embellish the animation when the slide animation is completed.

By the way, slideToggle() would accomplish yesterday’s example more efficiently. But if we want to differentiate the slideUp() and slideDown() animations, the if..else comes in handy.

Here is yesterday’s example embellished with different animations after the completion of slideUp() and slideDown(). After slideUp(), the body of the topic will fade out with fadeOut() and back in with fadeIn(). After slideDown(), the sliding text will fade out and back in:

Here is the behavior:

fade-in-fade-out

And the new version of the topic:

 

Show and Hide with jQuery in HTML5 Output

MadCap Flare includes some show-and-hide controls for web-based outputs such as Togglers and Expanding Text. This blog has explored some alternatives for show-and-hide in the context of condition tags. Here is another option which uses jQuery to expand and collapse an element with a sliding animation.

Sliding show-and-hide actions are simple tasks with jQuery. Two such functions are slideUp() and slideDown(). Here is a function which uses both functions to show and hide an element given the element’s id attribute value.

You can add this script to many places in a Flare project. For simplicity in this example, here is an image of the script inserted into a topic and then edited.

insert-script

With the Attributes Window in Flare, you can set the value for an attribute of an element highlighted in the XML Editor. You can also edit the markup directly with the Text Editor. For this example the element to show and hide is given the value ‘show-hide’ for the id attribute.

id-attribute

The element to click is given the following value for the onclick attribute to call the JavaScript function. The value for id is passed to the function:

onclick-attribute

The final markup for the topic looks like this:

When the target is built and the output is opened, the click behavior looks like this:

expand-collapse

Other relevant concepts: