InApp Web Help A Little HTML Goes a Long Way

Last Updated on Wed, 15 Jun 2022 | Marketing Apps

Even if you don't have the resources to produce a tutorial video or demo, if your application needs a little documentation for revealing extras such as advanced features, then create your own in-app help by providing the information in a help screen. A dedicated help view is extremely easy to set up with every little work and should be made accessible from your app's Settings or Info panel. But don't settle for plain text. Present the information in an appealing format. By using a UIWebView, you can utilize HTML to display stylized text and images!

The beauty of HTML is that it's easy to create and maintain. Just add a UIWebView to your Help View Controller and have it load the HTML page or HTML string you want displayed. You can even include the HTML help page within your compiled app so that there's nothing to fetch remotely—perfect for devices that are not connected to the Net, such as an iPod touch without WiFi or an iPhone in airplane mode. And during development, modifying the documentation only requires a few simple text changes to the HTML—no need to fiddle with Objective-C code.

But what if you're building a sophisticated productivity app that requires multiple pages of information? If you really feel that extensive documentation is needed, then just remember that your target is a mobile handheld device, so the primary objective should always be simplicity and ease of use. With many users navigating your in-app help with single thumb taps, take great care to keep the help content tightly organized.

Most developers groan at the thought of writing documentation of any kind, and if there's a lack of web design skills, then having to create an HTML set of pages makes matters even worse. But not to worry, there are some amazing third-party iPhone web kit frameworks that you can use to streamline this process. Here a just a few:

■ iUI, an iPhone UI web framework: http://code.google.com/p/iui/

■ jQTouch, a jQuery plug-in for iPhone web development: http://www.jqtouch.com/

■ iWebKit, an iPhone web site toolkit: http://iwebkit.net/

■ WebApp.Net, an iPhone web development framework:: http://webapp-net.com/

■ Magic Framework, an iPhone HTML5 framework: http://www.jeffmcfadden.com/projects/Magic Framework/

■ SaFire, an iPhone web app framework: http://code.rememberthisguy.com/safire/

■ UiUIKit, a universal iPhone UI kit: http://code.google.com/pZiphone-universal/

Not only are these toolkits specifically optimized for the iPhone screen size, but they also provide timesaving templates that mimic native iPhone UI controls and behavior. This is beneficial for two major reasons: first, the web design looks like an iPhone interface, so it blends well with the rest of your app, and second, the UI is familiar, so there's absolutely no learning curve for the user. An instant help system that works like an iPhone app! All you have to do is write the text.

So, which one should you use? They all have their own unique benefits and strengths, so check out all the web sites listed to see which offering best suits your specific needs. All of the frameworks include full source code and are available as free downloads. If you're a fan of the jQuery JavaScript library, then you'll love David Kaneda's jQTouch. iWebKit, WebApp.Net, and Magic Framework are also impressive. These four toolkits are offered as donationware, so if you end up using one of them, please consider supporting their hard work by sending a PayPal donation. And just as worthy of your attention are the open source solutions: iUI, SaFire, and UiUIKit.

The popular iUI, which was originally created by the well-respected iPhone and web app developer, Joe Hewitt, is one of my favorites. Most of you know Joe for his work on Firefox, Firebug, and the Facebook iPhone app.

To show you how easy it is to add in-app web help to your iPhone application, let's run through a quick little example project. Open the InAppHelp Xcode project, located in this book's companion examples folder. If you don't have those files, you can download them from the book's web site at http://www.iphonebusinessbook.com/

The InAppHelp example is a modified version of Xcode's Utility Application template. I simply changed all of the FlipsideView and FlipsideViewController references to HelpView and HelpViewController, respectively. I also deleted the default Info button, which will soon be replaced with a Rounded Rectangle Button with the title In-App Help. Next, I added a line of code to the MainViewController.h header file for the button's IBAction:

#import "HelpViewController.h"

@interface MainViewController : UIViewController <HelpViewControllerDelegate> { }

- (IBAction)showHelp;

@end

Then I inserted the code for that showHelp function in the MainViewController.m implementation file:

#import "MainViewController.h" #import "MainView.h"

@implementation MainViewController

- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {

if (self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil]) { // Custom initialization

return self;

- (void)helpViewControllerDidFinish:(HelpViewController *)controller {

[self dismissModalViewControllerAnimated:YES];

- (IBAction)showHelp {

// The Help button was tapped, so display the Help View. HelpViewController *controller = [[HelpViewController alloc] initWithNibName:@"HelpView" bundle:nil]; controller.delegate = self;

controller.modalTransitionStyle = UIModalTransitionStyleCoverVertical; [self presentModalViewController:controller animated:YES]; [controller release];

- (void)didReceiveMemoryWarning {

// Releases the view if it doesn't have a superview. [super didReceiveMemoryWarning];

// Release any cached data, images, etc that aren't in use.

- (void)viewDidUnload {

// Release any retained subviews of the main view. // e.g. self.myOutlet = nil;

[super dealloc];

@end

The Utility Application template uses a default animation that flips the view horizontally to the Info panel by setting the controller's modalTransitionStyle to UIModalTransitionStyleFlipHorizontal. For in-app help, I wanted the help view to slide up from the bottom, so I changed that setting to UIModalTransitionStyleCoverVertical.

Now that the button's code was in place, the next step was to launch MainView.xib in Interface Builder, add the In-App Help Rounded Rectangle Button, and then wire up the button's Touch Up Inside connector to the File Owner's showHelp connector.

Switching back to Xcode, I added @interface and @property references for UlWebView, as well as IBAction code for done and contactSupport to the HelpViewController.h header file (see highlighted code):

^protocol HelpViewControllerDelegate;

^interface HelpViewController : UIViewController { id <HelpViewControllerDelegate> delegate; UIWebView *webView;

^property (nonatomic, assign) id <HelpViewControllerDelegate> delegate; @property (nonatomic, retain) IBOutlet UIWebView *webView;

- (IBAction)done;

- (IBAction)contactSupport;

@end

@protocol HelpViewControllerDelegate

- (void)helpViewControllerDidFinish:(HelpViewController *)controller; @end

Then I moved to the HelpViewController.m implementation file and added a @synthesize reference for webView, inserted the done and contactSupport functions, and released webView when dealloc is called (see the bold code):

#import "HelpViewController.h"

@implementation HelpViewController

@synthesize delegate; ^synthesize webView;

- (void)viewDidLoad {

[super viewDidLoad];

// The Done button was tapped, so close Help View. [self.delegate helpViewControllerDidFinish:self];

- (IBAction)contactSupport {

// The Contact Support button was tapped, so go to // the online customer support web site in Mobile Safari. NSURL *url = [NSURL URLWithString:@"http://www.apress.com/"]; [[UIApplication sharedApplication] openURL:url];

// An alternative option is to implement In-App Email instead, // enabling the user to send feedback directly to you via email.

- (void)didReceiveMemoryWarning {

// Releases the view if it doesn't have a superview. [super didReceiveMemoryWarning];

// Release any cached data, images, etc that aren't in use.

- (void)viewDidUnload {

// Release any retained subviews of the main view. // e.g. self.myOutlet = nil;

[webView release]; [super dealloc];

@end

The done function merely performs the same action as the one in the default Utility Application template. When the Done button is tapped on the Help View (see Figure 7-6), the panel will revert to the Main View. Since I had changed the transition style to roll up from the bottom, when dismissed, the Help View will slide back down off the screen.

The contactSupport function is a new addition. If users can't find the answer they're looking for from your help content, don't let them vent their frustration in the App Store. Instead, give them convenient access to contacting you directly by providing a Contact Support button at the bottom of your Help View (next to the Done button).


Done		Contact Support

Figure 7-6. Creating an effective Help View in Interface Builder, using only a toolbar, two buttons, and a UIWebView

Open the project's HelpView.xib in Interface Builder, and you'll see the simple help viewer panel. Across the bottom is a standard toolbar with the Done button and the Customer Support button. As you would expect, the Done button is wired to the File Owner's done connector, and the Customer Support button is wired to the File Owner's customerSupport connector.

When run, if the Customer Support button is tapped, the current code in the customerSupport function simply launches a designated URL in Mobile Safari. This should be your online support page with a web form for requesting assistance. You could just as easily replace this code with your own implementation of In-App Email, enabling users to submit support queries directly from within your app. If this appeals to you, you could grab the relevant code from Chapter 4's Tell A Friend In-App Email example project.

The last thing added to the Help View window was the UIWebView. Since it is being used only to display read-only HTML content with no interaction with the app itself, there was no need to assign a UIWebView delegate. The only required task was wiring the UIWebView to the File Owner's webView connector.

But what shall you display in the UIWebView? For the purposes of this example, I opted to use the open source iUI as the framework for my help content. The iUI download includes several templates, so I cobbled together the elements I liked to suit my needs. By modifying the existing templates, I was able to simplify my documentation into a basic list of topics. Tap on a topic row to read the related content. And because I'm using the iUI framework, its built-in system emulates the interface and animations of native UIKit controls for a seamless user experience within the app (see Figure 7-7).

: Figure 7-7. The open source iUI web framework presents the HTML-based help content to look and feel like native iPhone interface components.

That's not a real UINavigationBar or UITableView in Figure 7-7. Everything you see in that screenshot is powered by iUI's framework of sophisticated CSS and JavaScript code. All I had to do was insert my help text into a single HTML file, using specific iUI-centric HTML tags. Here's what my help content looks like within the HTML body:

<li><a href="#howtouse">How to Use</a></li> <li><a href="#general">General Settings</a></li> <li><a href="#advanced">Advanced Options</a></li> <li><a href="#tipstricks">Tips & Tricks</a></li> <li><a href="#troubleshoot">Troubleshooting</a></li> </ul>

<p>This help page explains the basics of how to use this app.</p> </div>

<div id="general" title="Settings"> <h2>General Settings</h2>

<p>This help page explains how to configure the general settings for this app.</p> </div>

<div id="advanced" title="Advanced"> <h2>Advanced Options</h2>

<p>This help page explains how to configure the advanced options for this app.</p> </div>

<div id="tipstricks" title="Tips & Tricks"> <h2>Tips & Tricks</h2>

<p>This help page reveals all of the app's cool tips and tricks.</p> </div>

<div id="troubleshoot" title="Troubleshoot"> <h2>Troubleshooting</h2>

<p>Having problems with this app? This help page includes troubleshooting tips for resolving common issues.</p> </div>

At a glance, you can immediately see that each "page" is contained within its own <div> tag, and the Table View list is nothing more than a simple HTML List. Since I'll be including the HTML and related image files within my Xcode project, the one worry is that relative path hyperlinks may break after compiling the app. There's a distinct advantage to storing all your help content within a single HTML file to avoid that potential issue. In fact, I even went so far as to remove all dependencies on links to external JavaScript and CSS files. I copied and pasted all of the required code directly into my one HTML file.

After finishing the modifications, I tested my help system in the Mac OS X version of the Safari browser, since it uses the same WebKit engine as the iPhone. Happy with the result, I then added it to my project by dragging the HTML file and related images onto the main Xcode window, placing them in the Resources folder (see Figure 7-8).

Breakpoints Build and Run Tasks Info

Qr String Matching

• htmlHelp.html:! Î <No selected symbol> Î

<p>This help page explains the basics of how to use this app.</p>

<div id="general" title="Settings"> <h2>General Settings</h2>

<p>This help page explains how to configure the general settings for

<div id="advanced" title="Advanced"> <h2>Advanced 0ptions</h2>

<p>This help page explains how to configure the advanced options for

<div id="tipstricks" title="Tips & Tricks"> <h2>Tips & Tricks</h2>

<p>This help page reveals all of the app's cool tips and tricks.</p> </div>

<div id="troubleshoot" title="Troubleshoot"> <h2>Troubleshooting</h2>

<p>Having problems with this app? This help page includes troubleshoi

Figure 7-8. Adding the HTML help page and related image files to your Xcode project's Resources folder

You're almost done. The last step is to program the app to load the HTML help page within the UIWebView. In the HelpViewController.m implementation file, I added the following code to the viewDidLoad event:

- (void)viewDidLoad {

// Load the htmlHelp.html file into the UIWebView.

NSString *path = [[NSBundle mainBundle] pathForResource:@"htmlHelp" ofType:@"html"]; NSURL *url = [NSURL fileURLWithPath:path]; NSURLRequest *request = [NSURLRequest requestWithURL:url]; [self.webView loadRequest:request];

[super viewDidLoad];

In a nutshell, this new code fetches the HTML page from within the app bundle and loads it as a local URL into the UIWebView (see Figure 7-9).

..ill Carrier 11:35 PM B>

How to Use General Settings Advanced Options Tips & Tricks Troubleshooting

Figure 7-9. Loading the HTML page into the UIWebView via code in HelpViewController.m

Surprised at how good it looks? I was too. If you hadn't known it was an HTML page, you might have assumed you were looking at a native UINavigationBar and UITableView. You're probably wondering: why go to all the trouble of embedding HTML-based help if you're simply going to mimic native UIKit controls? Sure, I could have built the same thing in Interface Builder, but by using the open source iUI web framework, I was able to construct a custom Help View for my app in very little time and with much less code.

Another powerful advantage is that it gives me the option to host the help content remotely on a web server if desired. For apps that require a constant Internet connection for their core functionality, the Help panel's UIWebView could just as easily load an URL of an external web site. This gives you the flexibility to update your help content without needing to modify or recompile the actual iPhone app.

Remotely hosting the help content is especially useful if you receive a lot of feedback from users. You can continuously update your help page with additional answers to frequently asked questions, improving the support within your existing iPhone app. This also allows you to maintain a single source of help content on your web server that gets accessed by multiple platforms. On the iPhone, the help is fetched and displayed within the iUI framework or a similar toolkit. A different set of CSS styles are employed when that same help content is rendered in a web browser on a desktop computer.

Whichever method you choose, including some form of in-app help can only improve your application's overall user experience.

Continue reading here: Step 3 Launch the Online Development Provisioning Assistant

Was this article helpful?

InApp Web Help A Little HTML Goes a Long Way

Recommended Programs

Related Posts