A drop-in solution for displaying a user guide in an iOS app, based on a JSON template.
- Compatible with iOS 8.4 and above.
- Provide a plain JSON file for content.
- Deep-link to articles for contextual help.
- User search with query highlighting.
- Built in feedback mechanisms for email and Twitter.
- Customize colors, and optionally provide a
UITableViewCellsubclass to use.
Swift Package Manager (for Apple platforms only)
In Xcode, select File > Swift Packages > Add Package Dependency and enter the repository URL:
Add the following line to your
Add the following line to your
How to Use
Sherpa uses a JSON file as the source of its content, which allows you to provide a file in your app bundle, download a file from a server, or both! It handles parsing of the JSON for you, all you need to do is give it the local URL to the document, and it will handle the rest. You don't even need to wrap the view controller in a
UINavigationController, as this is done automatically; just present the
SherpaViewController directly and you're good to go.
let viewController = SherpaViewController(fileAtURL: fileURL) self.presentViewController(viewController, animated: true, completion: nil)
To deep link to a specific article for contextual help, you can optionally provide an
articleKey that matches the key on the article you would like to link to. Sherpa will present with the selected article open, and allow users to navigate back to the full list of articles to find additional help if they want to.
let viewController = SherpaViewController(fileAtURL: fileURL) viewController.articleKey = "related-articles" self.presentViewController(viewController, animated: true, completion: nil)
If you'd like to push Sherpa into an existing
UINavigationController stack, this is handled gracefully without any additional configuration required. Simply push the
let viewController = SherpaViewController(fileAtURL: fileURL) viewController.articleKey = "related-articles" self.navigationController?.pushViewController(viewController, animated: true)
More information about setting up the JSON document can be found within the example application's UserGuide.json file. You can read this user guide and see the examples in action by taking the example application itself for a spin. CocoaPods makes this easy with the
pod try Sherpa command, which can be run from Terminal if you have CocoaPods installed.
To generate documentation locally, run
make documentation or
sh ./scripts/documentation.sh from the repo's root directory. The output will be generated in the docs folder, and should not be included with commits (as the online documentation is automatically generated and updated).
Get in Touch
Released under the BSD License
Copyright © 2019 Daniel Farrelly
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
You may find interesting
0.2.1 Unit tests - 2017-01-05 23:29:11
- Added: Unit tests for model code.
- Fixed: Crash that could occur when deep-linking an article.
- Improved: JSON parsing.
N.B. This is the final release to support Swift 2.3.
0.2 Swift 2.3 - 2016-12-06 23:38:40
- Improvement: Update to Swift 2.3 syntax.
- Fixed: Respond to keyboard notifications in article list.
0.1.1 Bug fixes - 2016-06-02 23:26:01
- Fixed: Highlights are not removed when search is cleared.
- Fixed: Navigation bar is hidden when opening an article from search.
- Fixed: Rows are sometimes not deselected when returning from an article.
- Improved: Fade surrounding text slightly to accentuate search highlights a little more.
- Improved: Links should match
tintColorand open the URL when tapped.
- Improved: Code tags (
<code>) should be presented in an appropriate font.
0.1.0 Initial Release - 2016-05-25 04:39:07
- JSON-based file format.
- Article search.
- List of related articles.
- Open articles directly.
- Automatically embeds within a UINavigationController as required.
- Feedback via email or Twitter using built-in iOS mechanisms.