Adding Help to your iOS App
I have 9 apps in the app store now and every one of them has a “Help” component. The first few apps simply present a UIWebView with some linked html pages. Not at all contextual.
I have now developed some code that lets me easily add view-specific help with only adding a few lines of code for each view where I wish to display help.
At the risk of putting myself out there and bearing the wrath of seasoned developers who may criticize my code, I am inspired by the open sharing of the Swift development community to make the code freely available and to document how I use it.
YouTube Tutorial
If you prefer to watch how the installation and configuration is done, please watch check out https://www.youtube.com/watch?v=WcUkahx3j8s
Installation
You can get CTHelp and the sample application from my GitHub page at https://github.com/StewartLynch/CTHelp
If you clone or download CTHelp from GitHub you will be able to see the and test out the sample application. To integrate it into your project, all you have to do is make sure you have initialized CocoaPods for your application and then add the following to your podfile.
And run pod Install
You can now open the .xcworkspace for your project
Adding Help to a ViewController
For any ViewController that you wish to add help to, you can do the following:
- Import CTHelp in your ViewController
- Create a button that will make the request to display the help through its action.
- Within the action, either implement the following code, or write a function that will implement the code and call that function within the action.
The Code
The easiest way to implement is to start your code off with the following by creating a new instance of CTHelp:
let ctHelp = CTHelp()
Now, you can Option-Click on the CTHelp() class name to bring up the Quick Help. Copy all of the code after the declaration and paste it into your function.
Example
This is what your action will look like.
The single instance of the CTHelp class does most of the work for you. There are some things however that are incomplete. Each CTHelpItem references an image that does not exist, and your company name, email address, logo and website are simply put in as placeholders. Keep reading to see how you can update and change the code.
There are 4 class functions that you can use.
Creating a HelpCard
You can use the sample code to get you started, What I do is modify each of the three parameters on each ctHelp.new(CTHelpItem(….) functions to get the kind of card that I wish to display. If I need more, I just copy and paste.
Here is a description of what each function does.
CTHelp.new
The “new” function adds a new CTHelpItem to an array of CTHelpItems that are used to present the card when you present the help.
ctHelp.new(ctHelpItem: CTHelpItem)
CTHelpItem
Each CTHelpItem has three required parameters.
CTHelpItem(title: String, helpText: String>, imageName: String)
If helpText is left as an empty string “”, the image will take up the entire view. If imageName is left as an empty string, the helpText will take up the entire view. If both exist, then the image view presents the image with that name and scales it to a maximum of 240px X 230px. The height remaining will be taken up by the helpText. It is therefore best to design your images so that to the width of 240 px with a height that will allow for the display of your helpText within the view. If the text is larger than that which will fit in the textview, the view will scroll.
Note: Images with the names specified must be added to the assets of your project
CTHelp.appendDefaults
There are two optional cards that can be displayed at the end of the help card stack. If you choose not to use the appendDefaults function, no additional cards will be added.
ctHelp.appendDefaults(companyName:String, emailAddress:String?, data:Data?, webSite:String?, companyImageName:String?)
emailAddress
If you assign a value to emailAddress, a new card will be created and presented, asking the users if he/she wishes to contact the developer. The email address specified will be the address to which the email is sent.
If, prior to calling the appendDefaults function, you gather data for your application and assign it to a Data() object, you can assign that to the data parameter. If this is not nil, the user will also be asked if he/she would like to attach application data to the email.
Note: See the sample project for an example of how I gather and encode the data.
The wording of the email is configured in the CTHelp/CTEmailFunctions.swift file and is the sendEmail() function. You will note that the body of the message also includes user information such as the device type, version of iOS and the app version.
website
If you assign a value to webSite, a card is displayed with an image using the name specified in companyImageName along with some text that asks the user to click on a button that will take the user to the company website defined in the webSite address. The wording for the text is defined in the CTHelp/Models/CTHelp.swift file itself within the appendDefaults function. The image you use must be available as one of your assets.
Displaying the Help ViewController
CTHelp.present(from:UIViewController)
Always use self as the presenting viewController. in our case, the instance of CTHelp is called ctHelp, so we can present the CTHelp cards using
ctHelp.presentHelp(from: self)
Changing Colors to match your theme
If you want to modify the colors of the card, you can change them by using the optional variables that are provided as part of the sample code.
Uncomment whichever ones you want and change the colors to match your theme.
By changing your colors, you can change the look and appearance of your help card.
Thanks and appreciation
I would like to give thanks and appreciation to the following people in the Swift Community. I have never met any of these gentlemen, but their tireless contributions and guidance through text, podcasts and YouTube videos have inspired and encouraged me to share what little I know and I hope that you find this useful and helpful. I strongly recommend that you check out their twitter accounts, websites, videos and podcasts. You will recognize a lot of them in me.
Paul Hudson (Paul Hudson) @twostraws
Hacking With Swift author, YouTuber, conference presenter and Swift Over Coffee podcaster.
Sean Allen (@seanallen_dev)
YouTuber and Swift Over Coffee podcaster
Mark Moeykens (@bigmtnstudio)
YouTuber
John Sundell (@swiftbysundell)
Author and weekly podcaster.
FireSide Swift (@fireside_swift)
A weekly podcast with Stephen and Zack.
Last but not least
I would be remiss if I did not also thank (Aurimas Mixas P.)
He saw this post and suggested that it would be better if it were a cocoapod install. I had no idea how to do that and he was gracious enough to stick with me for a few days as I did my research. He worked along with me (and corrected my errors and omissions) and I finally got it to be accepted.
Finally, I would love for you to provide me with feedback and follow me on twitter. I am @StewartLynch
If you want to find out a bit more about my journey, please check out my first blog here on Medium.
Can I call myself a software developer?
https://medium.com/@stewartlynch/can-i-call-myself-a-software-developer-ca03ac3f37aa
