TripGo Card View Controller

This is a repo for providing the card-based design for TripGo as well as the TripKitUI SDK by SkedGo.

Specs

1. Basic functionality of cards

Behaviour:

• Card positions (!3):
  1. collapsed: Only shows header of card
  2. peaking: Shows half of card's content and the map content
  3. extended: Shows card fully, map shows a little bit on top but is greyed out
• Pushing a card from another card
  • Adds (x) button unless it’s the root card
  • Card has a preferred position which is used when pushing (!3)
  • Animation: Slide up from the bottom; fading black view on card below with alpha from 0% to 25%
  • Pass on appearance callbacks appropriately to involved cards
• Popping a card
  • Tap (x) to pop card
  • When popping top card, restore card position of card below when something got pushed on it (!3)
  • Animation: Slide back down; fading out black view on card below with alpha from 25% to 0%
  • Pass on appearance callbacks appropriately to involved cards
• Cards are draggable
  • Snap to collapsed (only title), peaking (near half-way showing both map and card content), extended (still shows a bit of the map on top, but darkened) (!3)
  • Cards can be dragged up and down anywhere on the card
  • Tap title when collapsed: go to peaking (!3)
  • Tap title when peaking: go to extended (!3)
  • Tap title when extended: do nothing
  • Tap map when extended: go to peaking (!3)
• Cards are scrollable
  • Cards typically have scrolling content: when scrolling down the card's header stays at the top and a bit of the map still keeps peaking through at the top.
  • When scrolling down show a thin separator line between the card's scrolling content and the card's header (!18)
  • When scrolling to the top and keeping to scroll, start dragging card (!12)

Styles:

• Animation curve for push and pop (!1)
• Blurry view under status bar (like Maps app) (!1)
• When rotating device and card is collapsed, make sure card ends up in correct position (!1)

2. Card content and gestures

Card types:

• Plain card
  • On top: Title, (x), optional subtitle and optional accessory view
  • Add accessory view (!11)
  • Content can be scrollable and size adjusts to content. If it fits, it shouldn’t be scrollable
  • Add optional floaty button (!14)
• Table card
  • Same as plain card, but with a table view as its content
  • Allow specifying plain (e.g., for departures) or grouped style (e.g., for profile) (!13)
• Collection card
  • Same as plain card, but with a collection view as its content
  • Allow specifying collection view layout
• Paging card (!5)
  • Handles list of child cards on the same hierarchical level which can be paged programatically and through gestures
  • Has header view: Used for titles (child cards shouldn't show them then) and navigation; Header view is separate from sticky bar, i.e., you can have both.
  • Re-uses the top card's map manager
  • Pass on appearance callbacks appropriately to child cards

Card styles:

• Rounded corners to cards (!2)
• Grab handle for cards (!2)
• Nice close buttons (and next button for paging cards) (!5)
• Title and subtitle styling
• Add mini drop shadow to card views (!2)
• Bottom view (!4)

3. Map content

Map content:

• Cards can optionally have map content
• When showing the content, the insets should be respected to account for the card overlapping the map
• If there’s no map content: Show card always extended and don't allow dragging it down (or just snap back up when using tries) (!3)

Map buttons:

• Optional list of buttons that float on the right above the card or in the top right corner (when collapsed or peaking) (!27)
• When dragging up the card to extended, the buttons fade away (!27)

4. Large width (iPad + iPhone in landscape)

• Move card to the side with min (iPhone Plus) and max (iPad) width (!9)
• Make sure transitions work when changing size and traits (!9)

5. UIKit features

• State restoration
• VoiceOver Accessibility (!38)
• NSUserActivity
• Keyboard shortcuts (#30)

Installation and usage

Install

Via CocoaPods:

1. Check out the repo and make it accessible to your project, e.g., as a git submodule

2. Add it to your Podfile, e.g.:

   pod 'TGCardViewController', path: 'Libraries/TGCardViewController'

3. Run pod update

Via Carthage

1. Add it to your Cartfile, e.g.:

   git "[email protected]:SkedGo/tripgo-cards-ios.git" "master"

2. Run carthage update and follow the usual instructions to add it to your project.

Add it to your app

1. Create a TGCardViewController subclass and use it in your storyboard

2. Override init(coder:) so that the instance from the storyboard isn't used, but instead TGCardViewController.xib:

   import TGCardViewController
   
   class CardViewController: TGCardViewController {
   
     required init(coder aDecoder: NSCoder) {
       // When loading from the storyboard we don't want to use the controller
       // as defined in the storyboard but instead use the TGCardViewController.xib
       super.init(nibName: "TGCardViewController", bundle: TGCardViewController.bundle)
     }
   
     ...
   }

3. Create a TGCard subclass, that represents the card at the top level, and add then push that in your view controller's viewDidLoad:

     override func viewDidLoad() {
       rootCard = MyRootCard()
       super.viewDidLoad()
     }

End-user documentation

Keyboard shortcuts

• Card controller
  • ⌃+↑: Expand card
  • ⌃+↓: Expand/collapse card
  • ⌘+w: Pop card or dismiss modal
• Table view cards
  • ↑: Highlight previous item
  • ↓: Highlight next item
  • ⌘+↑: Highlight item at start of list
  • ⌘+↓: Highlight item at end of list
  • Space or enter: select item
  • Esc: deselect
• Paging cards
  • ⌃+←: Previous card
  • ⌃+→: Next card