GitHub - cely-tools/Cely: Plug-n-Play login system for iOS written in Swift

Prounounced Cell-Lee

Cely’s goal is to add a login system into your app in under 30 seconds!

Overview
Requirements
Usage
API
Installation
License

Overview

Cely's goal is to add a login system into your app in under 30 seconds!

Background

Whether you're building an app for a client or for a hackathon, building a login system, no matter how basic it is, can be very tedious and time-consuming. Cely's architecture has been battle tested on countless apps, and Cely guarantees you a fully functional login system in a fraction of the time. You can trust Cely is handling login credentials correctly as well since Cely is built on top of Locksmith, swift's most popular Keychain wrapper.

Details:

What does Cely does for you?

Simple API to store user creditials and information securely

Cely.save("SUPER_SECRET_STRING", forKey: "token", securely: true)

Manages switching between your app's Home Screen and Login Screen with:

Cely.changeStatus(to: .loggedIn) // or .loggedOut

Customizable starter Login screen(or you can use your login screen)

What Cely does not do for you?

Network requests
Handle Network errors
Anything with the network

Requirements

iOS 11.0+
Xcode 9.0+
Swift 4.0+

Usage

Setup(30 seconds)

User Model (`User.swift`)

Let's start by creating a User model that conforms to the CelyUser Protocol:

// User.swift

import Cely

struct User: CelyUser {

  enum Property: CelyProperty {
    case token = "token"
  }
}

Login redirect(`AppDelegate.swift`)

Cely's Simple Setup function will get you up and running in a matter of seconds. Inside of your AppDelegate.swift simply import Cely and call the setup(_:) function inside of your didFinishLaunchingWithOptions method.

// AppDelegate.swift

import Cely

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: Any]?) -> Bool {
  
  Cely.setup(with: window, forModel: User(), requiredProperties: [.token])
  
  ...
}

Hit RUN!!

CelyOptions

Handle Login Credentials

Now how do we get the username and password from Cely's default LoginViewController? It's easy, just pass in a completion block for the .loginCompletionBlock. Check out CelyOptions for more info.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    Cely.setup(with: window!, forModel: User(), requiredProperties: [.token], withOptions: [
        .loginCompletionBlock: { (username: String, password: String) in
            if username == "asdf" && password == "asdf" {
                Cely.save(username, forKey: "username")
                Cely.save("FAKETOKEN:\(username)\(password)", forKey: "token", securely: true)
                Cely.changeStatus(to: .loggedIn)
            }
        }
    ])

    return true
}

Customize Default Login Screen

Create an object that conforms to the CelyStyle protocol and set it to .loginStyle inside of the CelyOptions dictionary when calling Cely's setup(_:) method.

// LoginStyles.swift
struct CottonCandy: CelyStyle {
    func backgroundColor() -> UIColor {
        return UIColor(red: 86/255, green: 203/255, blue: 249/255, alpha: 1) // Changing Color
    }
    func buttonTextColor() -> UIColor {
        return .white
    }
    func buttonBackgroundColor() -> UIColor {
       return UIColor(red: 253/255, green: 108/255, blue: 179/255, alpha: 1) // Changing Color
    }
    func textFieldBackgroundColor() -> UIColor {
        return UIColor.white.withAlphaComponent(0.4)
    }
    func appLogo() -> UIImage? {
        return UIImage(named: "CelyLogo")
    }
}

...

// AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    Cely.setup(with: window!, forModel: User.ref, requiredProperties: [.token], withOptions: [
        .loginStyle: CottonCandy(), // <--- HERE!!
        .loginCompletionBlock: { ... }        
    ])

    return true
}

Customize Transitions

In order to create a custom transition, create an object that conforms to CelyAnimator protocol and set it to .celyAnimator inside of the CelyOption dictionary when calling Cely's setup(_:) method.

struct DefaultAnimator: CelyAnimator {
    func loginTransition(to destinationVC: UIViewController?, with celyWindow: UIWindow) {
        guard let snapshot = celyWindow.snapshotView(afterScreenUpdates: true) else {
            return
        }

        destinationVC?.view.addSubview(snapshot)
        // Set the rootViewController of the `celyWindow` object
        celyWindow.setCurrentViewController(to: destinationVC)

        // Below here is where you can create your own animations
        UIView.animate(withDuration: 0.5, animations: {
            // Slide login screen to left
            snapshot.transform = CGAffineTransform(translationX: 600.0, y: 0.0)
        }, completion: {
            (value: Bool) in
            snapshot.removeFromSuperview()
        })
    }

    func logoutTransition(to destinationVC: UIViewController?, with celyWindow: UIWindow) {
        guard let snapshot = celyWindow.snapshotView(afterScreenUpdates: true) else {
            return
        }

        destinationVC?.view.addSubview(snapshot)
        // Set the rootViewController of the `celyWindow` object
        celyWindow.setCurrentViewController(to: destinationVC)

        // Below here is where you can create your own animations
        UIView.animate(withDuration: 0.5, animations: {
            // Slide home screen to right
            snapshot.transform = CGAffineTransform(translationX: -600.0, y: 0.0)
        }, completion: {
            (value: Bool) in
            snapshot.removeFromSuperview()
        })
    }
}

...

// AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    Cely.setup(with: window!, forModel: User.ref, requiredProperties: [.token], withOptions: [
    .celyAnimator: CustomAnimator(), // <--- HERE!!
    .loginCompletionBlock: { ... }        
    ])

    return true
}

Use your own Screens

To use your own login screen, simply create a storyboard that contains your login screen and pass that in as .loginStoryboard inside of the CelyOptions dictionary when calling Cely's setup(_:) method.

Lastly, if your app uses a different storyboard other than Main.storyboard, you can pass that in as .homeStoryboard.

⚠️⚠️⚠️⚠️ Be sure to make your Login screen as the InitialViewController inside of your storyboard!⚠️⚠️⚠️⚠️

// AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    Cely.setup(with: window!, forModel: User.ref, requiredProperties: [.token], withOptions: [
        .loginStoryboard: UIStoryboard(name: "MyCustomLogin", bundle: nil),
        .homeStoryboard: UIStoryboard(name: "NonMain", bundle: nil)
    ])

    return true
}

Recommended User Pattern

import Cely

struct User: CelyUser {

    enum Property: CelyProperty {
        case username = "username"
        case email = "email"
        case token = "token"

        func securely() -> Bool {
            switch self {
            case .token:
                return true
            default:
                return false
            }
        }

        func persisted() -> Bool {
            switch self {
            case .username:
                return true
            default:
                return false
            }
        }

        func save(_ value: Any) {
            Cely.save(value, forKey: rawValue, securely: securely(), persisted: persisted())
        }

        func get() -> Any? {
            return Cely.get(key: rawValue)
        }
    }
}

// MARK: - Save/Get User Properties

extension User {

    static func save(_ value: Any, as property: Property) {
        property.save(value: value)
    }

    static func save(_ data: [Property : Any]) {
        data.forEach { property, value in
            property.save(value)
        }
    }

    static func get(_ property: Property) -> Any? {
        return property.get()
    }
}

The reason for this pattern is to make saving data as easy as:

// Pseudo network code, NOT REAL CODE!!!
ApiManager.logUserIn("username", "password") { json in
  let apiToken = json["token"].string
  
  // REAL CODE!!!
  User.save(apiToken, as: .token)
}

and getting data as simple as:

let token = User.get(.token)

API

Cely

Cely was made to help handle user credentials and handling login with ease. Below you will find documentation for Cely's Framework. Please do not hesitate to open an issue if something is unclear or is missing.

Variables

`store`

A class that conforms to the CelyStorageProtocol protocol. By default is set to a singleton instance of CelyStorage.

Methods

`setup(with:forModel:requiredProperties:withOptions:)`

Sets up Cely within your application

Example

Cely.setup(with: window, forModel: User(), requiredProperties:[.token])

// or 

Cely.setup(with: window, forModel: User(), requiredProperties:[.token], withOptions:[
  .loginStoryboard: UIStoryboard(name: "MyCustomLogin", bundle: nil),
  .HomeStoryboard: UIStoryboard(name: "My_NonMain_Storyboard", bundle: nil),
  .loginCompletionBlock: { (username: String, password: String) in
        if username == "asdf" && password == "asdf" {
            print("username: \(username): password: \(password)")
        }
    }
])

Parameters

Key	Type	Required?	Description
`window`	`UIWindow`	✅	window of your application.
`forModel`	`CelyUser`	✅	The model Cely will be using to store data.
`requiredProperties`	`[CelyProperty]`	no	The properties that cely tests against to determine if a user is logged in. Default value: empty array.
`options`	`[CelyOption]`	no	An array of `CelyOptions` to pass in additional customizations to cely.

`currentLoginStatus(requiredProperties:fromStorage:)`

Will return the CelyStatus of the current user.

Example

let status = Cely.currentLoginStatus()

Parameters

Key	Type	Required?	Description
`properties`	[`CelyProperty`]	no	Array of required properties that need to be in store.
`store`	`CelyStorage`	no	Storage `Cely` will be using. Defaulted to `CelyStorage`

Returns

Type	Description
`CelyStatus`	If `requiredProperties` are all in store, it will return `.loggedIn`, else `.loggedOut`

`get(_:fromStorage:)`

Returns stored data for key.

Example

let username = Cely.get(key: "username")

Parameters

Key	Type	Required?	Description
`key`	String	✅	The key to the value you want to retrieve.
`store`	CelyStorage	no	Storage `Cely` will be using. Defaulted to `CelyStorage`

Returns

Type	Description
`Any?`	Returns an `Any?` object in the case the value nil(not found).

`save(_:forKey:toStorage:securely:persisted:)`

Saves data in store

Example

Cely.save("test@email.com", forKey: "email")
Cely.save("testUsername", forKey: "username", persisted: true)
Cely.save("token123", forKey: "token", securely: true)

Parameters

Key	Type	Required?	Description
`value`	`Any?`	✅	The value you want to save to storage.
`key`	`String`	✅	The key to the value you want to save.
`store`	`CelyStorage`	no	Storage `Cely` will be using. Defaulted to `CelyStorage`.
`secure`	`Boolean`	no	If you want to store the value securely.
`persisted`	`Boolean`	no	Keep data after logout.

Returns

Type	Description
`StorageResult`	Whether or not your value was successfully set.

`changeStatus(to:)`

Perform action like LoggedIn or LoggedOut.

Example

changeStatus(to: .loggedOut)

Parameters

Key	Type	Required?	Description
`status`	`CelyStatus`	✅	enum value

`logout(usesStorage:)`

Convenience method to logout user. Is equivalent to changeStatus(to: .loggedOut)

Example

Cely.logout()

Parameters

Key	Type	Required?	Description
`store`	`CelyStorage`	no	Storage `Cely` will be using. Defaulted to `CelyStorage`.

`isLoggedIn()`

Returns whether or not the user is logged in

Example

Cely.isLoggedIn()

Returns

Type	Description
`Boolean`	Returns whether or not the user is logged in

Constants

Protocols

`CelyUser`

protocol for model class to implements

Example

import Cely

struct User: CelyUser {

  enum Property: CelyProperty {
    case token = "token"
  }
}

Required

value	Type	Description
`Property`	`associatedtype`	Enum of all the properties you would like to save for a model

`CelyStorageProtocol`

protocol a storage class must abide by in order for Cely to use it

Required

func set(_ value: Any?, forKey key: String, securely secure: Bool, persisted: Bool) -> StorageResult
func get(_ key: String) -> Any?  
func removeAllData()

`CelyStyle`

The protocol an object must conform to in order to customize Cely's default login screen. Since all methods are optional, Cely will use the default value for any unimplemented methods.

Methods

func backgroundColor() -> UIColor
func textFieldBackgroundColor() -> UIColor
func buttonBackgroundColor() -> UIColor
func buttonTextColor() -> UIColor
func appLogo() -> UIImage?

`CelyAnimator`

The protocol an object must conform to in order to customize transitions between home and login screens.

Methods

func loginTransition(to destinationVC: UIViewController?, with celyWindow: UIWindow)
func logoutTransition(to destinationVC: UIViewController?, with celyWindow: UIWindow)

Typealias

`CelyProperty`

String type alias. Is used in User model

`CelyCommands`

String type alias. Command for cely to execute

enums

`CelyOptions`

enum Options that you can pass into Cely on setup(with:forModel:requiredProperties:withOptions:)

Options

Case	Description
`storage`	Pass in you're own storage class if you wish not to use Cely's default storage. Class must conform to the `CelyStorage` protocol.
`homeStoryboard`	Pass in your app's default storyboard if it is not named "Main"
`loginStoryboard`	Pass in your own login storyboard.
`loginStyle`	Pass in an object that conforms to `CelyStyle` to customize the default login screen.
`loginCompletionBlock`	`(String,String) -> Void` block of code that will run once the Login button is pressed on Cely's default login Controller
`celyAnimator`	Pass in an object that conforms to `CelyAnimator` to customize the default login screen.

`CelyStatus`

enum Statuses for Cely to perform actions on

Statuses

Case	Description
`loggedIn`	Indicates user is now logged in.
`loggedOut`	Indicates user is now logged out.

`StorageResult`

enum result on whether or not Cely successfully saved your data.

Results

Case	Description
`success`	Successfully saved your data
`fail(error)`	Failed to save data along with a `LocksmithError`.

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

CocoaPods 1.1.0+ is required to build Cely 2.0.0+.

To integrate Cely into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

pod 'Cely', '~> 2.1'

Then, run the following command:

$ pod install

Carthage

Carthage is a decentralized dependency manager that automates the process of adding frameworks to your Cocoa application.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate Cely into your Xcode project using Carthage, specify it in your Cartfile:

github "initFabian/Cely" ~> 2.1

Manually

If you prefer not to use either of the aforementioned dependency managers, you can integrate Cely into your project manually.

Git Submodules

Open up Terminal, cd into your top-level project directory, and run the following command "if" your project is not initialized as a git repository:

$ git init

Add Cely as a git submodule by running the following command:

$ git submodule add https://github.com/initFabian/Cely.git
$ git submodule update --init --recursive

Open the new Cely folder, and drag the Cely.xcodeproj into the Project Navigator of your application's Xcode project.

It should appear nested underneath your application's blue project icon. Whether it is above or below all the other Xcode groups does not matter.
Select the Cely.xcodeproj in the Project Navigator and verify the deployment target matches that of your application target.
Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
In the tab bar at the top of that window, open the "General" panel.
Click on the + button under the "Embedded Binaries" section.
You will see two different Cely.xcodeproj folders each with two different versions of the Cely.framework nested inside a Products folder.

It does not matter which Products folder you choose from.
Select the Cely.framework.
And that's it!

The Cely.framework is automagically added as a target dependency, linked framework and embedded framework in a copy files build phase which is all you need to build on the simulator and a device.

Embeded Binaries

Download the latest release from https://github.com/initFabian/Cely/releases
Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
In the tab bar at the top of that window, open the "General" panel.
Click on the + button under the "Embedded Binaries" section.
Add the downloaded Cely.framework.
And that's it!

License

Cely is available under the MIT license. See the LICENSE file for more info.

Name		Name	Last commit message	Last commit date
Latest commit History 119 Commits
Cely Demo		Cely Demo
Cely.xcodeproj		Cely.xcodeproj
Cely.xcworkspace		Cely.xcworkspace
Images		Images
Sources		Sources
Tests		Tests
fastlane		fastlane
scripts		scripts
.gitignore		.gitignore
.swift-version		.swift-version
.swiftlint.yml		.swiftlint.yml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
Cely.podspec		Cely.podspec
DEPLOY_STEPS.md		DEPLOY_STEPS.md
LICENSE		LICENSE
README.md		README.md

License

cely-tools/Cely

Folders and files

Latest commit

History

Repository files navigation

Overview

Background

Details:

Requirements

Usage

Setup(30 seconds)

User Model (User.swift)

Login redirect(AppDelegate.swift)

Hit RUN!!

CelyOptions

Handle Login Credentials

Customize Default Login Screen

Customize Transitions

Use your own Screens

Recommended User Pattern

API

Cely

Variables

store

Methods

setup(with:forModel:requiredProperties:withOptions:)

currentLoginStatus(requiredProperties:fromStorage:)

get(_:fromStorage:)

save(_:forKey:toStorage:securely:persisted:)

changeStatus(to:)

logout(usesStorage:)

isLoggedIn()

Constants

Protocols

CelyUser

CelyStorageProtocol

CelyStyle

CelyAnimator

Typealias

CelyProperty

CelyCommands

enums

CelyOptions

CelyStatus

StorageResult

Installation

CocoaPods

Carthage

Manually

Git Submodules

Embeded Binaries

License

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 11

Packages 0

Contributors 3

Languages

User Model (`User.swift`)

Login redirect(`AppDelegate.swift`)

`store`

`setup(with:forModel:requiredProperties:withOptions:)`

`currentLoginStatus(requiredProperties:fromStorage:)`

`get(_:fromStorage:)`

`save(_:forKey:toStorage:securely:persisted:)`

`changeStatus(to:)`

`logout(usesStorage:)`

`isLoggedIn()`

`CelyUser`

`CelyStorageProtocol`

`CelyStyle`

`CelyAnimator`

`CelyProperty`

`CelyCommands`

`CelyOptions`

`CelyStatus`

`StorageResult`

Packages