This will help you get started with Tapglue Elements on iOS step by step guide.
A more detailed documentation can be found on our documentation website.
Create User Profiles, Followers & Following Lists, Notifications Feeds & User Search.
To start using the Tapglue API you need an APP_TOKEN
. Visit our Dashboard and login with your credentials or create a new account.
In this section we'll explain how to integrate Tapglue Elements into your iOS app. Tapglue Elements goes one step beyond the SDK and includes a full set of screens and navigations.
#Cocoapods
To install elements with cocoapods add this line to your podfile:
pod 'TapglueElements', '0.1.2'
#Manual Installation
To install elements first install tapglue as explained in the ios sdk documentation, and then add elements as a submodule to your project by executing:
git submodule add https://github.com/tapglue/elements-ios.git externals/elements
then in your project add the elements folder to your project checking the targets you need.
To run the example project, clone the repo, and run pod install
from the Example directory first.
We want to make Elements as flexible as possible and allow you to customize it. You will need to set up Tapglue within your application, which will look something like this:
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
let tgConfig = TGConfiguration.defaultConfiguration()
Tapglue.setUpWithAppToken(YOUR_TOKEN, andConfig: tgConfig)
}
For further detail on how to configure the Tapglue SDK please refer to the installation section in the iOS guide. This is also the point where you should customize the appearance of Tapglue Elements. To customize it you need to provide a configuration JSON
to Elements.
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
let tgConfig = TGConfiguration.defaultConfiguration()
Tapglue.setUpWithAppToken(YOUR_TOKEN, andConfig: tgConfig)
if let path = NSBundle.mainBundle().pathForResource("config", ofType: "json"){
do {
let data = try NSData(contentsOfURL: NSURL(fileURLWithPath: path), options: NSDataReadingOptions.DataReadingMappedIfSafe)
try TapglueUI.setConfig(data)
} catch let error as NSError {
print("could not load config file! Error: \(error)")
}
}
return true
}
Integrate Elements with a single line of code for a fully fledged experience. The easiest way to use elements in your app is by simply segueing into our view controllers.
There are two segues you can perform, one is to the profile screen
import UIKit
import elements
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
TapglueUI.performSegueToProfile(self)
}
}
The other segue is to the notifications feed:
import UIKit
import elements
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
TapglueUI.performSegueToNotificationFeed(self)
}
}
With this approach we push our navigation controller on top of your view controller and thus replace your navigation with elements own navigation.
Integrate Elements into your existing experience and let us handle the social parts.
To get full control over the events that occur within elements we recommend using our view controllers as child view controllers in your own view controllers.
This way element seams into your app in a more natural way for the end user.
import UIKit
import elements
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
let vc = TapglueUI.profileViewController()
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
}
}
When using our view controllers like this the default behavior is to integrate our own navigation. This means when the user taps different actionable items we will navigate to our different screens.
If you need more flexibility we also provide delegates that can be implemented to get a deeper control of the events that can occur in the view controllers. For example, the notification screen has the following delegate protocol.
public protocol NotificationFeedViewDelegate{
func defaultNavigationEnabledInNotificationFeedViewController(notificationFeedViewController: NotificationFeedViewController) -> Bool
func notificationFeedViewController(noticationFeedViewController: NotificationFeedViewController, didSelectEvent event: TGEvent)
}
defaultNavigationEnabledInNotificationFeedViewController(notificationFeedViewController: NotificationFeedViewController) -> Bool
lets you decide if elements should navigate for you or not. You will find analogue methods to this in all our view controller delegates.
A practical example would be the following.
import UIKit
import elements
import Tapglue
class ViewController: UIViewController, NotificationFeedViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
let vc = TapglueUI.notificationFeedViewController()
vc.delegate = self
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
self.view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
}
func defaultNavigationEnabledInNotificationFeedViewController(notificationFeedViewController: NotificationFeedViewController) -> Bool {
return false
}
func notificationFeedViewController(noticationFeedViewController: NotificationFeedViewController, didSelectEvent event: TGEvent) {
//handle event tap
}
}
Here the navigation in elements is turned off, thus when the user taps a event cell you ideally want to navigate to some specific event screen.
To use the profile view controller add it as a child view controller and child view of your view controller.
let vc = TapglueUI.profileViewController()
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
If you want to make use of the delegate be sure to assign the profile view controllers delegate.
import UIKit
import elements
import Tapglue
class ViewController: UIViewController, ProfileViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
let vc = TapglueUI.profileViewController()
vc.delegate = self
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
}
func defaultNavigationEnabledInProfileViewController(profileViewController: ProfileViewController) -> Bool {
//answer if you want to override navigation or not
return false
}
func referenceUserInProfileViewController(profileViewController: ProfileViewController) -> TGUser {
//return user whos profile is to be displayed
return TGUser.currentUser()
}
func profileViewController(profileViewController: ProfileViewController, didSelectConnectionsOfType connectionType: ConnectionType, forUser user: TGUser) {
//add handling for when a connection type was selected for the displayed user
}
func profileViewController(profileViewcontroller: ProfileViewController, didSelectEvent event: TGEvent) {
//add handling for when an event was selected on the user profile
}
}
To use the connections view controller add it as a child view controller and sub view in your view controller
import UIKit
import elements
import Tapglue
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
let vc = TapglueUI.connectionsViewController()
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
}
}
If you want to make use of the delegate be sure to assign the connections view controllers delegate
import UIKit
import elements
import Tapglue
class ViewController: UIViewController, ConnectionsViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
let vc = TapglueUI.connectionsViewController()
vc.delegate = self
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
}
func defaultNavigationEnabledInConnectionsViewController(connectionsViewController: ConnectionsViewController) -> Bool {
//answer if you want to override navigation or not
return false
}
func referenceUserInConnectionsViewController(connectionsViewController: ConnectionsViewController) -> TGUser {
//return user whos connections is to be displayed
return TGUser.currentUser()
}
func connectionTypeInConnectionsViewController(connectionsViewController: ConnectionsViewController) -> ConnectionType {
//return the type of connections to be displayed, can be either
// ConnectionType.Followers or ConnectionType.Following
return ConnectionType.Followers
}
func connectionsViewController(connectionsViewController: ConnectionsViewController, didSelectUser user: TGUser) {
//handle event when a connection is tapped
}
}
To use the notification feed view controller add it as a child view controller and child view of your view controller.
import UIKit
import elements
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
let vc = TapglueUI.notificationFeedViewController()
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
}
}
If you want to make use of the delegate be sure to assign the notification feed view controllers delegate. For the notification screen this is specially interesting as we don't provide a news feed and this is the place where you can link back to posts.
import UIKit
import elements
import Tapglue
class ViewController: UIViewController, NotificationFeedViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
let vc = TapglueUI.notificationFeedViewController()
vc.delegate = self
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
}
func defaultNavigationEnabledInNotificationFeedViewController(notificationFeedViewController: NotificationFeedViewController) -> Bool {
//answer if you want to override navigation or not
return false
}
func notificationFeedViewController(noticationFeedViewController: NotificationFeedViewController, didSelectEvent event: TGEvent) {
//add handling for when an event was selected on the user profile
}
}
To use the user search view controller add it as a child view controller and child view of your view controller.
import UIKit
import elements
import Tapglue
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
let vc = TapglueUI.userSearchViewController()
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
}
}
If you want to make use of the delegate be sure to assign the user search view controllers delegate
import UIKit
import elements
import Tapglue
class ViewController2: UIViewController, UserSearchViewDelegate {
override func viewDidLoad() {
super.viewDidLoad()
let vc = TapglueUI.userSearchViewController()
vc.delegate = self
vc.view.frame = CGRectMake(0, 0, view.frame.size.width, view.frame.size.height)
self.addChildViewController(vc)
view.addSubview(vc.view)
vc.didMoveToParentViewController(self)
}
func defaultNavigationEnabledInUserSearchViewController(userSearchViewController: UserSearchViewController) -> Bool {
//answer if you want to override navigation or not
return false
}
func userSearchViewController(userSearchViewController: UserSearchViewController, didSelectUser user: TGUser) {
//handle event when a user is tapped
}
func didTapAddressBookInUserSearchViewController(userSearchViewController: UserSearchViewController) {
//handle event when address book search is requested
}
}