You just got word from management that your company is shifting to a mobile orientation. That means the user documentation has to become mobile too. What do you do?

The easy solution is to make your MadCap Flare project responsive. The formatting, layout, even the content will automatically change depending on the size of the display screen. Perfect! But management might want the user documentation recast as an app to make it available from the app stores or installable on users’ mobile devices via a single file download. Now what do you do?

Engineering can create the app if it can fit the work into its schedule. If not, you can buy app authoring tools that let non-programmers create the app. But that means learning a new tool and new concepts. Is there a mid-ground?

The mid-ground is to convert your Flare target to an app using a cloud-based tool called PhoneGap Build (https://build.phonegap.com). The result won’t look like Angry BirdsTM, but it will be a business app that will run on iOS, Android, or Windows (Phone). And the best part is that:

  • Most of your Flare project’s features will come though.
  • You can convert your Flare target to an app with little or no programming.
    NOTE: In prior versions of PhoneGap Build (which I’ll refer to as PGB from now on), all the work was point-and-click with no code. However, PGB recently changed with little warning, as cloud-based tools do, and simple tasks like renaming an app now require some coding. The work isn’t difficult but it can be intimidating if you’re new to XML. Depending on the level of interest that this blog post generates, I may write additional posts that go into more technical detail.

To demonstrate the process and the results, I created a little Flare project that contains a representative sample of features including a stylesheet, (but no index), and a simple table of contents:

flare-target-mobile-app-01

Along with topics that contain a graphic, a table (with a table stylesheet), text, and hyperlinks, cross-references, popups, dropdowns, expanding links, and togglers:

flare-target-mobile-app-02

flare-target-mobile-app-03

flare-target-mobile-app-04

flare-target-mobile-app-05

Generating HTML5 output with the responsive output features enabled and using a TopNav skin gives this result:

flare-target-mobile-app-06

Plain and simple but enough to test the conversion to an app.

How It’s Done

Follow these steps:

  1. Open the Target Editor for the target to convert to an app. On the General tab, type the name of the Output file with an extension of .html. (If you don’t type the extension, Flare gives it an .htm extension which PGB can’t use.)
  2. Generate your Flare target. Then zip up everything in the output folder, using WinZip, not Flare’s Zip Project feature. This zip file is what you’ll upload to PGB.
  3. Go to https://build.phonegap.com/plans to sign up. The free plan lets you build one private app but this is inconvenient if you’re experimenting because you’ll have to delete the last app you created in order to create a new one. I recommend the 25 private app plan for $9.99 per month.
  4. Go to https://build.phonegap.com and sign in. You’ll see a screen with a “+New App” button in the upper right (and a list of all your apps, if any).
    flare-target-mobile-app-07
    Note that I already created two apps. Each has its own QR code that users can scan with a QR code reader app to download to their mobile device.
  5. Click the “+ New App” button. A screen asks how you want to upload your app files. You can either pull them from a Git repository or upload a zip file, which is the simplest option.
  6. Click the “Upload a .Zip File” button. Windows’ Open dialog box displays.
  7. Select the zipped output to upload. After a few seconds, the upload ends and PhoneGap Build displays a screen where you can apparently assign the app name and add a description.
    flare-target-mobile-app-08
  8. Leave the settings as is. (In prior versions of PGB, you could change the title at this screen. But as I noted earlier, changes to PGB mean that changing the app name requires creating a file called config.xml.) For now, I’ll just click the Ready to Build button.
  9. When the build ends, I’ll see this screen:
    flare-target-mobile-app-09
  10. I’ll now scan the QR code to download the app and install it on my phone, in this case a Samsung Galaxy S5.
    NOTE: The download can be slow if you have less than 5-bar reception. It took ten minutes on my 2-bar reception in my home office. Wait for your mobile device to signal that the download has been completed. Be patient!

Once the app has been downloaded and installed, here’s what you’ll see. Starting with the app icon:

flare-target-mobile-app-10

Tapping the icon opens the app to the startup topic you specified on the General tab of the Target Editor in Flare:

Flare target as mobile app

Both the hyperlink and the cross-reference work. The table comes through with the settings from the table stylesheet:

flare target as mobile app

Popups convert to hyperlinks. All of the other link types – dropdown, toggler, and expanding – work. So almost everything in your Flare project comes across.

Summary

The process worked smoothly on the Flare side, which is to be expected because you’re simply creating a Flare project. Most of the work on the PGB side is straightforward point-and-click, except for a few features that will take you into code. (But the PGB site has examples of the code for the config.xml file that you can use for reference. It also has more information if you’re of a moderately techie bent.)

The biggest problem with the apps created by this conversion process is that they look like Flare projects on a mobile phone, not “true” apps. This means that they won’t have features like or look like apps that your users are used to seeing – e.g. it’s an issue of user perception. But if that’s not a major issue, or if you can add some of those app-like features by applying plug-ins, this is a quick and easy way to move Flare into the mobile app space and start breaking down the silos between the two.

Besides, it’s fun…

About The Author

Neil Perlin

About Neil Perlin

Neil Perlin is the president of Hyper/Word Services, an online content and app development firm based in Massachusetts. Neil is MadCap-certified in Flare and Mimic and a frequent speaker at MadWorld and other industry conferences. You can reach him at nperlin@nperlin.cnc.net, visit his web site at www.hyperword.com, or follow him on LinkedIn, Facebook, or Twitter (as NeilEric).

Last Modified: May 18, 2017

This entry was posted in MadCap Flare, Tips & Tricks, Tutorials. Bookmark the permalink.

Comments

  • Riley VanDyke May 18, 2017 at 10:03 AM

    Very interesting and informative — thanks Neil!

    Along the way I chuckled at the observation that “PGB recently changed with little warning, as cloud-based tools do.” Too true — and why is it that those unilateral changes seldom make things better?

    • Neil Perlin Neil Perlin May 18, 2017 at 12:29 PM

      Basically yes, although the programmers would of course disagree.

  • Shoab May 21, 2017 at 8:10 AM

    How can we changed the app name? You have mentioned that we need a config.xml file..Can you brief us about the same?

  • Sam May 29, 2017 at 6:40 AM

    Serendipity! It just so happens that I’m working on multimedia content for delivery through Google Play Store and the Apple Store. As a l follow up to Shoab’s query, and I don’t want to seem ungrateful to Adobe, but it would be
    necessary for my project to end up without an icon for the PGBuild App. Thanks Neil and more on the topic please!

    • Charles C Westphal June 6, 2017 at 9:52 AM

      You can change the icons but this is not done in Flare, you will have to decipher the PhoneGap documentation to do so. There are several icon size/resolutions to accommodate.

  • Garry May 31, 2017 at 6:16 AM

    Hi
    I really liked the article, maybe I’m daft or something, but I’m not sure what to change the setting in step one to. I get the .html part, but what filename would I use there? Thanks

  • Charles C Westphal June 6, 2017 at 9:51 AM

    Though a more complex way to go, you can use a local version of PhoneGap and XCode to do this. This is necessary if you do not want to constantly upload company confidential information to a third party server. Also, PGB has size limits that might be a problem for you eventually if your target is huge (our offline KB app has several hundred articles).

    • Candace Roberts September 27, 2017 at 9:36 AM

      Charles – do you know offhand what that file limit is for the cloud solution. I am considering PGB, but may need a local copy. Also is XCode needed as a tandem requirement? or is it optional?

  • Janette June 6, 2017 at 8:59 PM

    This is something I’m very keen on doing but when I try to upload my .zip file to the PGB website I’m getting an error message that says ‘Error index.html not found’. For the life of me I can’t work out how to proceed!

    • Janette June 6, 2017 at 9:43 PM

      Naturally I found the answer just after posting this. Just name the Flare Output file as index.html seems to do the trick.

  • Terry Huff June 22, 2017 at 9:23 AM

    Great article, something I will try…but in the meantime, do I have to convert a Responsive project to an app to get it to display on a phone or tablet? I just want to distribute a user manual to individuals, don’t need to have an app in any App Store. Just copy files to a mobile device and display the project.

    I tried simply to add my project folder to Dropbox on my desktop, and I can see it in Dropbox on my phone of course, but it doesn’t display well at all.

    Any guidance on simply putting a project folder locally onto a mobile device would be greatly appreciated!! Terry in San Diego

    • Neil Perlin Neil Perlin June 23, 2017 at 8:58 AM

      Hi Terry,

      Try putting your responsive output on a server and give the user the URL. Let me know if this does what you need.

      Regards,
      Neil

  • Trish Edwards June 26, 2017 at 1:38 PM

    Hi Neil, thanks for this article!

    It seems from your instructions that the app can be downloaded with the QR cide and *without* going through Google play. Is that just for testing? We will need apps for Windows Surfaces and *shudder* iPads both. I realize I’m dreaming, but I’d love to bypass having to publish to any store.

    Thanks in advance!
    Trish

    • Rachel Kim Rachel Kim June 28, 2017 at 8:53 AM

      Hi Trish, a response from Neil,

      Take a look at http://docs.phonegap.com/phonegap-build/faq/#submitting. Let me know if that does not answer your question

      Also, a question for you. The initial blog post didn’t go into great detail about the process of using PhoneGap Build. More of an overview. However, I’m trying to gauge the amount of interest out there to see if there’s demand for a follow-up post that goes into greater detail. Is this something you’d like to see?

      • Candace Roberts September 27, 2017 at 9:40 AM

        I find i have questions on this approach.

        • Rachel Kim Rachel Kim October 6, 2017 at 4:08 PM

          Hi Candace, let us know what questions you have. Thanks!

Have Something to Say?

Your email address will not be published. Required fields are marked *