Home

Awesome

Bamboots: Extension 4 Alamofire

CI Status Version Platform Language Codebeat License Gitter Weibo <3

Bamboots is a network request framework based on Alamofire , aiming at making network request easier for business development.

Protocols

Bamboots has made advantages of protocol-oriented programming and abstracted everything that relevant to network request into protocol. Here is the protocol list:

Mostly you don't need to care much about these protocols, because we already have many DEFAULT implementations for them. However if you want to customize something, you just need to conform to these protocols and do what you want. Here is some default implementations for these protcols:

Features

  1. There is no need to inherit any object to get the features it has, and you can extend any features you want without changing the code of Bamboots itself.
  2. We have Default extension for most of the protocol, so you can easily startup.
  3. And if you have special needs, extend or conform to it.
  4. The API was designed with the principles of Alamofire, So you can also extend it as Bamboots already have done for you.
  5. Mainly focus on things between business development and Alamofire, not network request itself.

Requirements

Usage

Create a form

For business development, most of the requests' headers are the same, so you can extend it only for once.

extension Formable {
    public func headers() -> [String: String] {
        return ["accessToken":"xxx"];
    }
}

And you can also have extension for specified protocol


extension Formable where Self: UploadFormable {
    public func headers() -> [String: String] {
        return ["accessToken":"xxx", "file":"xxx"];
    }
}

And for other parameters such as url, method, parameters etc. Each request will has it's own value, So we create an object and make it conforms to the protocol

struct WeatherForm: RequestFormable {
    var city = "shanghai"
    
    public func parameters() -> [String: Any] {
        return ["city": city]
    }

    var url = "https://raw.githubusercontent.com/tristanhimmelman/AlamofireObjectMapper/2ee8f34d21e8febfdefb2b3a403f18a43818d70a/sample_keypath_json"
    var method = Alamofire.HTTPMethod.get
}

Make a request

All you have to do is conforming to Requestable protocol, in this protocol, we've already implement some methods for you:

Here is the usage of request method:

class LoadableViewController: UIViewController, Requestable {
    override func viewDidLoad() {
        super.viewDidLoad()

        // Do any additional setup after loading the view.
        request(WeatherForm())
    }
}

Show mask when requesting

We have extended DataRequest class of Alamofire and added a load method to it.

func load(load: Loadable = LoadType.none) -> Self

Show mask on UIViewController

request(WeatherForm()).load(load: LoadType.default(container: self))

Show mask on UIButton

request(WeatherForm()).load(load: button)

Notice: The color of UIActivityIndicatorView is the tintColor of UIButton

Show customized mask

Firstly, we create a LoadConfig class conforms to Loadable protocol.

class LoadConfig: Loadable {
    init(container: Containable? = nil, mask: Maskable? = MaskView(), inset: UIEdgeInsets = UIEdgeInsets.zero) {
        insetMine = inset
        maskMine = mask
        containerMine = container
    }
    
    func mask() -> Maskable? {
        return maskMine
    }
    
    func inset() -> UIEdgeInsets {
        return insetMine
    }
    
    func maskContainer() -> Containable? {
        return containerMine
    }
    
    func begin() {
        show()
    }
    
    func end() {
        hide()
    }
    
    var insetMine: UIEdgeInsets
    var maskMine: Maskable?
    var containerMine: Containable?
}

Then we can use it as followed:

let load = LoadConfig(container: view, mask:EyeLoading(), inset: UIEdgeInsetsMake(30+64, 15, UIScreen.main.bounds.height-64-(44*4+30+15*3), 15))
request(WeatherForm()).load(load: load)

This is the most powerful usage of the Loadable protocol. In this way you can customized everything the Loadable protocol has.

Show mask on UITableView & UIScrollView


let load = LoadConfig(container:self.tableView, mask: ActivityIndicator(), inset: UIEdgeInsetsMake(UIScreen.main.bounds.width - self.tableView.contentOffset.y > 0 ? UIScreen.main.bounds.width - self.tableView.contentOffset.y : 0, 0, 0, 0))
request(WeatherForm()).load(load: load)

Show mask on UITableViewCell (PS: Still in development)

refresh.attributedTitle = NSAttributedString(string: "Loadable UIRefreshControl")
refresh.addTarget(self, action: #selector(LoadableTableViewController.refresh(refresh:)), for: .valueChanged)
tableView.addSubview(refresh)
     
func refresh(refresh: UIRefreshControl) {
    request(WeatherForm()).load(load: refresh)
}

Loadable UIRefreshControl

override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
    tableView .deselectRow(at: indexPath, animated: false)
    let cell = tableView.cellForRow(at: indexPath)
    request(WeatherForm()).load(load: cell!)
}

We can also support other refresh control such as MJRefresh.

Show progress when requesting

We have extended DownloadRequest and UploadRequest class of Alamofire and added a progress method to it.

func progress(progress: Progressable) -> Self

And then we can use it as followed:

download(ImageDownloadForm()).progress(progress: progress)

Show warning message if fail

We have extended DataRequest class of Alamofire and added a warn method to it.

func warn<T: JSONErrorable>(error: T, warn: Warnable, completionHandler: ((JSONErrorable) -> Void)? = nil) -> Self

And then we can use it as followed:

let alert = UIAlertController(title: "Warning", message: "Network unavailable", preferredStyle: .alert)
alert.addAction(UIAlertAction(title: "Ok", style: UIAlertActionStyle.cancel, handler: nil))
        
request(WeatherForm()).warn(
    error: WeatherError(),
    warn: alert
)

Notice: We only have warn for JSON format response now.

Show inform message if success

We have extended DataRequest class of Alamofire and added a inform method to it.

func inform<T: JSONErrorable>(error: T, inform: Informable) -> Self

And then we can use it as followed:

let alert = UIAlertController(title: "Notice", message: "Load successfully", preferredStyle: .alert)
alert.addAction(UIAlertAction(title: "Ok", style: UIAlertActionStyle.cancel, handler: nil))
request(WeatherForm()).inform(
    error: WeatherInformError(),
    inform: alert
)

Notice: We only have inform for JSON format response now.

JSON to Object

request(WeatherForm()).responseObject(keyPath: "data") { (response: DataResponse<WeatherResponse>) in
    if let value = response.result.value {
        self.weatherResponse = value
        self.tableView.reloadData()
    }
}

For more information, see AlamofireCodable.

Chained calls

All the method mentioned above can be called in a chained manner, such as followed:

let load = LoadConfig(container: view, mask:EyeLoading(), inset: UIEdgeInsetsMake(30+64, 15, UIScreen.main.bounds.height-64-(44*4+30+15*3), 15))

let warn = UIAlertController(title: "Warning", message: "Network unavailable", preferredStyle: .alert)
warn.addAction(UIAlertAction(title: "Ok", style: UIAlertActionStyle.cancel, handler: nil))

let inform = UIAlertController(title: "Notice", message: "Load successfully", preferredStyle: .alert)
inform.addAction(UIAlertAction(title: "Ok", style: UIAlertActionStyle.cancel, handler: nil))

request(WeatherForm()).load(load:load).progress(progress: progress).warn(error: WeatherError(), warn: warn).inform(error: WeatherInformError(), inform: inform)

Bonus

Eyeloading

We've written this motion effect when implementing the customized loading, and it's all implemented with CAAnimationGroup.

If interested, you can check the file Eyeloading in example project.

Example

To run the example project, clone the repo, and run pod install from the Example directory first.

Installation

Bamboots is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'Bamboots'

Protobuf Support

pod 'Bamboots/BambootsProtobuf'

Author

mmoaay, mm@swift.gg

License

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