Author Archives: Thomas Tregner

Automating Imports

If you work with more than a few projects that import from a common project, you may want to automate importing from that project. Automating imports can be as simple as scheduling this command:

 How does that work? Isn’t madbuild.exe for generating output content?

Yes. But some other things happen when a target is built.

Flare targets have an Auto-Sync feature that enables running an import prior to generating content. Auto-Sync can be disabled for a target from the Target Editor. The setting is on the General tab, under Auto-Sync: Disable auto-sync of all import files. When not checked, the option is specified in the target file markup as a DisableAutoSync=”false” attribute and value on the CatapultTarget element. The value is true when the box is checked.

Flare imports have a setting on the Source Project tab called Auto-reimport before “Generate Output”.  Targets with Auto-Sync enabled will prompt an import specified by the import files with the Auto-reimport before “Generate Output” option selected. The markup for this option is AutoSync=”true” on the CatapultProjectImport element.

The command line executable that enables starting builds outside of the Flare user interface is called madbuild.exe. It is located in the folder where Flare is installed. When a target is built with madbuild.exe, Auto-Sync is still run if specified. However if the project is under source control, madbuild.exe does not prompt for a checkout as happens in the Flare interface. But more about that later.

By the way, this post is a follow-up to a previous discussion about batch files called Batch Files, madbuild.exe, and commands.

Setting up automated imports is accomplished by scheduling builds of targets that cause an import with Auto-Sync. Builds can be scheduled by placing build commands in a batch file and scheduling a call to the batch file with Windows Scheduler.

The target can be a throw-away that builds a one topic TOC. The output doesn’t matter. The target is just a means to get madbuild.exe to cause an import.

But I use source control and madbuild.exe does not prompt me to check files in or out.

Depending on your source control solution, you can automate that also. For example with Team Foundation Server and Visual Studio (Team Explorer), the executable is tf.exe and it is located in a Visual Studio folder.

One thing to watch out for is that not every file in a project should be checked in and out of source control. Some folders are local such as the Output folder in the root of the project and Users folders in the Project folder. The second example that follows shows this.

Build Commands

 

Build with TFS Source Control Commands

 

Create a Java Application That Uses Flare HTML5 Help

This post describes the creation of a simple Java application and Flare project and HTML5 output to demonstrate opening a Flare HTML5 help topic with a button click or an F1 keypress from a Java application. This is a “hello world” level example.

Downloads:

Java Application and Flare HTML5 Help

MadCap provides conceptual information and instructions for programmers and authors about how to configure applications to use context sensitive help with Flare HTML5 outputs. This post covers some of that workflow. The example is less complicated but not as flexible as MadCap’s suggested workflows. However this post goes into greater detail about how to connect an application to HTML5 help in the context of a Java application.

MadCap Software: CSH Calls for HTML5 Output (WebHelp 2.0)

The example Java and Flare projects are configured such that the application opens a URL for the Flare HTML5 output using the CSHID number in the URL For simplicity, the CSHID number value used is 1 and the topic is Topic.htm (topic.htm in the sample output). Additional calls to open help can be added with the same technique. For more information about CSHID and CSH calls, see the preceding link.

With the arrangement established by the samples in this post, a Flare author would manage the mapping of ID numbers to topics. A programmer would call the same function for every help button click or F1 press and pass the desired ID number. No lookup is necessary on the Java application side. A programmer only needs to know which values to use for actions and UI locations in the application. There is no need to supply a properties file to a programmer with this setup. One possible workflow is the author informs a programmer which IDs to use and the programmer implements those. Another workflow is a programmer assigns IDs and the author updates the Flare project to map those IDs to the topics. Either way the mapping is managed through the Flare HTML5 system.

Other scenarios may be explored in subsequent posts. The Flare documentation describes a workflow in which a copy of a header or a properties file is used by the application so that the application is aware of the mapping between the ID name and number. That workflow adds some flexibility. But that workflow is not demonstrated in this post.

Create a Java Application with NetBeans

This example uses NetBeans to create the Java sample. The steps use the IDE options so that those who do not program regularly with Java can replicate the steps more easily. However designing forms in an IDE such as NetBeans involves a reliance on the mechanisms the IDE uses to generate code. For example a NetBeans project with a JFrame form may contain an additional XML file with a .form extension to facilitate form building. The Java class for the JFrame is sufficient to run the program. But the .form file is required for the form designer in NetBeans.

NetBeans wiki: What is the .form file?

  1. Install NetBeans. This example was created on a computer running Windows 8 with Java, the Java Development Kit, and NetBeans installed. https://netbeans.org/
    netbeans-ide
  2. From the menu, select File > New ProjectThe New Project screen appears.
    new-project-screen
  3. Select Java Application.
  4. Click Next.
  5. Enter a project name such as JavaAppFlareHtml5Help.
  6. Click Finish.

Add a JFrame Form to the Application

The window user interface for this example is implemented with a JFrame. The steps which follow describe adding a a JFrame to a Java project in NetBeans.

  1. Right-click the package and select New > JFrame form.
    new-jframe-form-menu-option
    The New JFrame Form screen appears.
  2. Enter a class name such as JFrameHtml5Example.
    new-jframe-form-screen
  3. Click Finish.
  4. The JFrame designer appears in NetBeans.
    new-jframe-in-designer

Add a JLabel and a Help JButton to the JFrame

The JLabel is just an embellishment for this example to place some text on the JFrame. The JButton provides an interface to click to show a help topic.

  1. Drag a JLabel from the palette to the designer. JLabel is located under Swing Controls on the palette and is indicated as Label. This and the next step are not necessary to demonstrate opening help.
  2. From the properties screen for the JLabel, change the text to Flare HTML5 Help Example.
    label-in-jframe-designer
  3. Drag a JButton from the palette to the designer. JButton is located under Swing Controls and is indicated as Button.
  4. From the properties screen for the JButton, change the text to Help.
    button-in-jframe-designer
  5. Double-click the button in the designer. The code for the action event appears in the code editor. Call a yet-to-be-defined function called showHelp and pass a string value of 1.

     

Add F1 Events

To create F1 behavior, a handler must be added for every control on the form which should cause help to open when F1 is pressed. In this case the only control to worry about is the JButton since it is the only control which can be active. By default, JLabels cannot be activated. A handler is also added to the JFrame itself.

  1. To add a keyPressed event for the JFrame and the JButton, from the properties screen for each, click the ellipses next to keyPressed under Events. The Handlers for keyPressed screen appears. The screen shot shows the screen after the event has been added.
    handlers-for-keypressed-screen
  2. Click Add.
  3. The Add Handler screen appears.
    add-handler-screen
  4. Enter a name such as jFrameKeyPressed and click OK.
  5. The handler code appears in the code editor. Call the yet-to-be-defined showHelp method from the handler for the case where F1 is pressed. The constant value for the F1 keycode in Java is 112. Wrap the call to showHelp in a conditional that checks for that value.

     

Add Methods to Open Help

The technique employed in this example relies on a call to a showHelp method within every event and handler that should cause help to open. The context for the help comes from the ID passed to showHelp. The showHelp method appends the ID to a base URL for the help system. The base URL is the path to the main help file followed by #cshid=. Once the URL is built, it is passed to a method to open a web page.

Stack Overflow: Open a Link in Browser with Java Button

  1. Add methods to open a web page from the Java application. You can paste these into the class for the JFrame.
  2. If the above code is pasted into the class file and there are not imports for the classes on which the methods depend, the Import Classes screen appears. These are the imports required for the example:

    import-classes-screen

     

  3. Click OK.
  4. Save the project files.

Code the Main Method to Open the JFrame

Open the java file that contains the main method. For this example, the file is JavaAppFlareHtml5Help.java. The main method should create and show an instance of the JFrame. Change the main method to this:

 

Create a Flare Project to Build the Help

Create a new Flare project with the Empty template. Use HTML5 as the default target.

  1. Select File > New Project. The Start New Project Wizard appears.
  2. For the name, enter java-example.
  3. Click Next.
  4. Under Source, select New from template and select Empty.
  5. Click Next.
  6. For the primary target, select HTML5.
  7. Click Finish.

Add an extra topic named extra-topic.htm and set that as the default topic on the HTML5 target. This ensures the default topic is not the topic opened by the application. That demonstrates the application opens a specific topic and not just the default.

  1. Right-click the Content folder in Content Explorer and select New > Topic. The Add File screen appears.
  2. In the File Name field, enter extra-topic.
  3. Click Add.
  4. Save the topic.
  5. In the Project Organizer within the Targets folder, double-click the HTML5 target to open it in the Target Editor.
  6. On the General tab in the Startup Topic field, select extra-topic.
  7. Save the target.

Set the topic alias. Open the alias file and assign Topic.htm to the identifier in the alias file. The header file will update when the alias file is saved.

  1. From the Project Organizer within the Advanced > CSH folder, double-click the AliasFile.flali file. The alias file appears in an editor.
  2. In the alias file editor, navigate to the Topic.htm file and right-click the file.
  3. From the menu, select Assign topic to selected identifier.
  4. Save the alias file.
  5. In the Target Editor for the HTML5 target on the General tab, change the name of the output file to java-app-help.
  6. In the Target Editor for the HTML5 target on the General tab, change the Startup Topic to extra-topic.htm.

MadCap Software: Creating and Assigning Identifiers

A handful of changes were made to the template for this example. Some of the changes are shown in the screen shot that follows. The order of items in the screen shot is:

  • Project Organizer
  • Content Explorer
  • Topic.htm in XML Editor
  • HeaderFile.h in Header Editor
  • AliasFile.flali in Alias Editor

everything-for-hello-world-csh

Test the Application and Help

Build the target an place the output somewhere. Adjust the path in the showHelp method to reflect the location of the help files.

To run the program from the IDE, with the project open and active, select Run > Run Project.

Downloads:

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:

 

Hide Some Flare HTML5 Output Glossary Tab Entries

This example uses JavaScript, JSON, and jQuery.

In a response to a forum post, I suggested a rules-based approach to removing plural terms from the Glossary tab in Flare HTML5 output. The sample I provided tackled a few common English rules.

Rules-based Example to Remove Glossary Tab Entries with JavaScript

Rules are one way to approach the problem. Another way is to keep a list of items to remove or hide. What follows is another example which hides three terms on a Glossary tab when the function in the example fires. You can adjust the list of terms in the JSON object which holds the list of terms. You can also adjust when the function is called. In the example project, there is a toolbar button. But you can add an event listener to some other object to call the function if you do not want to be tied to the toolbar.

The sample project is configured as follows. There is a glossary with three glossary terms consisting of a plural term and a singular term: Child/Children, Apple/Apples, and Goose/Geese.

GlossaryEditor

There is a JSON object and a JavaScript function in the Toolbar Javascript.

ToolbarJavaScript

The skin has a custom toolbar button called HideEntries. When that button is clicked, hideEntries() from the Toolbar JavaScript is fired.

HTML5SkinEditorToolbar

HTML5SkinEditorStyles

The Glossary tab appears this way when initially viewed:

GlossaryTabBefore

After the HideEntries toolbar button (the blank one) is clicked, the three terms in the JSON object are removed from the list.

GlossaryTabAfter

A sample project is here: HideTerms.flprjzip

 

 

Review of MadCap Flare Version 9.0

Having spent some more time with MadCap Flare 9.0, I’m ready to offer some opinions.

Disclosure

MadCap Software has provided me with a copy of MadCap Flare 9.0 for the purposes of review on this blog and to keep as my personal copy. MadCap Software has also covered my travel and boarding expenses for the purposes of presenting at the MadWorld 2013 conference. The opinions expressed on this blog are my own. Any details about products and services discussed on this blog should be verified with the manufacturer or provider.

I probably wouldn’t blog about something I didn’t like.

Review

MadCap’s What’s New In this Version documentation for Flare 9.0 describes Major New Features and Additional New Features. This is a blog about markup, programming, scripting, and automating in the context of MadCap Flare. But I’ll give my two cents about some of those listed as Major New Features.

Right-to-Left

If you use a right-to-left language, right-to-left support is THE new feature. I wish I could speak and write Arabic, Hebrew, or Persian to offer more insight. I can’t. But I am happy to see a wider market for the product. The more users, the more enhancements we can expect in the future.

Print Enhancements

Although I enjoy styling print output, I can’t remember the last time I intentionally read a PDF if the content was available as HTML. But if you actually want to print your print output, bleed, crop marks, and registration marks, and support for the CMYK color model are almost essential. Those are new additions. There are more print-related enhancements and I agree with most of those.

Removing the gray from the frame in the page layout editor may be my favorite print-related change. Small things make a difference as Kai Weber expressed in this post.

But the big four for me are…

Split View

This is cool.

split-view

You can now see the semi-WYSIWYG right next to the markup. I wish there was a split view for every type of XML file in a Flare project. For those, I still right-click the files and open those in Notepad++. For topics, I now find myself using the structure bars, the text in the XML Editor, and the Text Editor. Each works well for different tasks. The synchronization between each editor is pretty good. You can still trick it. But I think that will improve with minor releases. For heavy writing, you may find yourself turning this off because displaying two views at the same time doubles the screen real estate.

Advanced Conditional Expressions

“AND” makes an appearance!

Previously, the limitations of conditional expressions necessitated source content replication in certain scenarios. With the previous model, now called Basic, an Include would override an Exclude every time. Those limitations go away now because in addition to “OR” and “NOT” (derived from Include and Exclude), you can specify “AND.”

When editing in Basic mode, one or two clicks of the Include and Exclude column headers can wipe out your Basic settings. Read about how the Basic and Advanced modes work before you make changes. The settings are stored independently which may not be obvious at first.

advanced-conditional-expressions

Plug-In API

If read this blog, you can probably guess that this is my favorite new feature. I’m going to dive deeper into the API in future posts. My first blog post about the Plug-In API is here. The focus of the API is on adding menus, topic editors, and text selections.

Performance Improvements with HTML5

This produced some initial complications for me which were quickly addressed by MadCap’s technical support. Thank you to Lori and Joey for addressing those issues.

I am glad MadCap is working on performance in the output.

If you examine the TOC files in the Data folder of your HTML5 output, you will notice the XML is gone and only the JS files remain. And if you look at those, you can see that the TOC information is now encoded as JSON instead of an XML string.

This means that if you were using the TOC XML in the output for something else, you will now have to switch to reading the JSON. For example, this technique does not work with version 9.0 HTML5 output anymore. But it can be reworked to consume the new JavaScript files.

There are more new features which I haven’t covered. These are the highlights for me. What are your thoughts on the new release?

A First Flare Plug-In

Note (3/13/2014): A change to the API for version 10 requires adjusting the code in this sample if the plug-in is to be used with version 10. The change is explained in Adjusting Flare 9 Plug-ins for Flare 10.

With the release of MadCap Flare 9.0, Flare has a Plug-In API. With the API, you can add new Toolstrip and Ribbon menus. There are some hooks for the topic editor, the active document, and the current selection.

MadCap has posted documentation for the Plug-In API as a zipped HTML5 help system at: Download MadCap Flare API Documentation 9.0.

This post will go just a step beyond a “Hello World” example and describe a Plug-In to help you as you build other Plug-Ins. The Plug-In creates Toolstrip and Ribbon menus each with a single button. When you press the button, details returned by the API about the open topic editors, active document, and the current selection are shown on a Windows Form.

The reason there are two menus is because Flare can be configured to have either a Toolbar or a Ribbon user interface. A Plug-In doesn’t have to create a menu for each. But it would be frustrating to have an option in only one of two possible user interfaces.

Flare Plug-Ins are Windows application extensions for the Flare application. Application extensions are housed in files with a DLL extension. DLL stands for Dynamic-Link Library. To create a Flare Plug-In, you will have to be familiar with .NET, dynamic-link libraries, Windows APIs, and C# or possibly Visual Basic .NET.

The documentation provided by MadCap is a good starting point. For your first Plug-In, you will probably create a C# class project, reference the Plug-In DLL, implement the interfaces indicated in the documentation, and use the API and Windows APIs to create the behavior you want. A walk-through of those first steps will make a good future blog post. But for now, let’s see one in action.

Download this zipped project (PluginApiDetails.zip) which contains this first example Plug-In. A discussion for those not familiar with .NET development may also be a good future post. But for now, the assumption is you know how to open the project in Visual Studio, fix the references, and build the project.

The result of building the project is a DLL file. Once you have the DLL, you can follow the steps provided by MadCap to deploy the Plug-In. When all of that is complete, here is what the Plug-In looks like in Flare 9.0. Firstly the new Ribbon with a single button:

first-plugin-ribbon

Highlighting some text in a topic…

first-plugin-ribbon-highlighted-text

And clicking the new button. Information returned by API methods appears on a Windows Form called Details…

first-plugin-ribbon-details-screen

Clicking the Text button on the form shows the text of the topic in a message box…

first-plugin-ribbon-details-screen-text-messagebox

Having closed that instance of the form, a different selection is made and another instance of the form is opened by pressing the new button…

first-plugin-ribbon-small-selection

I hope that helps you to get started with your first Flare Plug-In. The sample in this post is intended to give you a tool to examine the results of many of the API properties and methods. You can install it and use it to test what is returned when you select different ranges of text.

What else would you like to know about the API? Let me know in the comments.

 

Quick Search Form for HTML5 Output

Here is a quick search form you can use on another page to open an HTML5 output search in the skin. To use it, change the value for uri (third line) to the URL for your Flare HTML5 help system’s main file. Then place the script and markup in the page markup where you want the form to appear on a web page.

search-form

search-form-with-term

search-results