Bamboots

by mmoaay

mmoaay /Bamboots

Bamboots - Extension 4 Alamofire

433 Stars 38 Forks Last release: almost 3 years ago (0.5.0) MIT License 129 Commits 6 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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:

  • Requestable
    : Network request protocol, object conforms to this protocol can make network request.
  • Formable
    : Form protocol. Object conforms to this protocol can be used by the
    request
    ,
    download
    ,
    upload
    method in
    Requestable
    protocol.
    • UploadFormable
      : Upload Form protocol, Base protocol for upload request form.
      • UploadStreamFormable
        : Conforming to this protocol to create an upload form that contains a stream object.
      • UploadDataFormable
        : Conforming to this protocol to create an upload form that contains a data object.
      • UploadFileFormable
        : Conforming to this protocol to create an upload form that contains a file.
      • UploadMultiFormDataFormable
        : Conforming to this protocol to create an upload form that contains multiformdata.
    • DownloadFormable
      : Download Form protocol, Base protocol for download request form.
      • DownloadResumeFormable
        : Conforming to this protocol to create a download form that can resume a download task.
    • RequestFormable
      : Conforming to this protocol to create a request form.
  • Loadable
    : Protocol used for showing mask on specified container when requesting (such as add
    UIActivityIndicatorView
    on
    UIViewcontroller
    's view when request begins, and remove it when request ends). Object conforms to this protocol can be used by
    load
    method of
    DataRequest
    .
    • Maskable
      : Mask protocol for
      Loadable
      , View that conforms to this protocol will be treated as mask.
    • Containable
      : Container protocol for
      Loadable
      , Objects conforms to this protocol can be used as container for the mask.
    • Progressable
      : Progress protocol for request, Objects conforms to this protocol can get the progress of the request. Object conforms to this protocol can be used by
      progress
      method of
      DataRequest
      .
  • Messageable
    : Message protocol.
    • Warnable
      : Warn protocol. Conforming to this protocol to customize the way of warning messages displayed when error occured.
    • Informable
      : Inform protocol. Conforming to this protocol to customize the way of inform messages displayed when request done successfully
  • Errorable
    : Error protocol. Conforming to this protocol to customize the error configuration.
    • JSONErrorable
      : Error protocol for JSON data. Conforming to this protocol to customize the error configuration for JSON data.

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:

  • LoadType
    : Enum that conforms to
    Loadable
    protocol, using
    case default(container:Containable)
    case to show
    MaskView
    on the container when requesting.
  • UIAlertController+Messageable
    : With this extension, you can pass a UIAlertController directly into the
    warn
    and
    inform
    method of
    DataRequest
    .
  • UIButton+Loadable
    : With this extension, you can pass a button directly into the
    load
    method of
    DataRequest
    .
  • UITableViewCell+Loadable
    : With this extension, you can pass a cell directly into the
    load
    method of
    DataRequest
    .
  • UIRefreshControl+Loadable
    : With this extension, you can pass a UIRefreshControl directly into the
    load
    method of
    DataRequest
    .
  • UIProgressView+Progressable
    : With this extension, you can pass a UIProgressView directly into the
    progress
    method of
    DataRequest
    .
  • UIScrollView+Containable
    : Extending UIScrollView to conform to
    Containable
    protocol.
  • UITableViewCell+Containable
    : Extending UITableViewCell to conform to
    Containable
    protocol.
  • UIViewController+Containable
    : Extending UIViewController to conform to
    Containable
    protocol.
  • ActivityIndicator
    : Default mask for UITableViewCell and UIButton
  • MaskView
    : Default mask for others.

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

  • Alamofire: Elegant HTTP Networking in Swift
  • AlamofireCodable: An Alamofire extension which converts JSON response data into swift objects using Codable

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() -&gt; [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:
  • func request(_ form: RequestFormable) -> DataRequest
  • func download(_ form: DownloadFormable) -> DownloadRequest
  • func download(_ form: DownloadResumeFormable) -> DownloadRequest
  • func upload(_ form: UploadDataFormable) -> UploadRequest
  • func upload(_ form: UploadFileFormable) -> UploadRequest
  • func upload(_ form: UploadStreamFormable) -> UploadRequest
  • func upload(_ form: UploadMultiFormDataFormable, completion: ((UploadRequest) -> Void)?)

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() -&gt; Maskable? {
    return maskMine
}

func inset() -&gt; UIEdgeInsets {
    return insetMine
}

func maskContainer() -&gt; 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(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(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) 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'
  • Use apple/swift-protobuf as protobuf data deserialization
  • run protobuf test
    • fist run
      Example/Protobuf/pbdemo
    • open
      Example/Bamboots.xcworkspace
    • run
      command + u

Author

mmoaay, [email protected]

License

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.