MBNetwork
MBNetwork is a network request framework based on Alamofire and ObjectMapper, aiming at making network request easier for business development.
- Protocols
- Features
- Requirements
- Usage
- Chained calls
- Bonus
- Example
- Installation
- Usage
- Author
- License
Protocols
MBNetwork has made advantages of protocol-oriented programming and abstracted everything that relevant to network request into protocol. Here is the protocol list:
-
: Network request protocol, object conforms to this protocol can make network request.MBRequestable
-
: Form protocol. Object conforms to this protocol can be used by theMBFormable
,request
,download
method inupload
protocol.MBRequestable
-
: Upload Form protocol, Base protocol for upload request form.MBUploadFormable
-
: Conforming to this protocol to create an upload form that contains a stream object.MBUploadStreamFormable
-
: Conforming to this protocol to create an upload form that contains a data object.MBUploadDataFormable
-
: Conforming to this protocol to create an upload form that contains a file.MBUploadFileFormable
-
: Conforming to this protocol to create an upload form that contains multiformdata.MBUploadMultiFormDataFormable
-
-
: Download Form protocol, Base protocol for download request form.MBDownloadFormable
-
: Conforming to this protocol to create a download form that can resume a download task.MBDownloadResumeFormable
-
-
: Conforming to this protocol to create a request form.MBRequestFormable
-
-
: Protocol used for showing mask on specified container when requesting (such as addMBLoadable
onUIActivityIndicatorView
’s view when request begins, and remove it when request ends). Object conforms to this protocol can be used byUIViewcontroller
method ofload
.DataRequest
-
: Mask protocol forMBMaskable
, View that conforms to this protocol will be treated as mask.MBLoadable
-
: Container protocol forMBContainable
, Objects conforms to this protocol can be used as container for the mask.MBLoadable
-
: Progress protocol for request, Objects conforms to this protocol can get the progress of the request. Object conforms to this protocol can be used byMBProgressable
method ofprogress
.DataRequest
-
-
: Message protocol.MBMessageable
-
: Warn protocol. Conforming to this protocol to customize the way of warning messages displayed when error occured.MBWarnable
-
: Inform protocol. Conforming to this protocol to customize the way of inform messages displayed when request done successfullyMBInformable
-
-
: Error protocol. Conforming to this protocol to customize the error configuration.MBErrorable
-
: Error protocol for JSON data. Conforming to this protocol to customize the error configuration for JSON data.MBJSONErrorable
-
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:
-
: Enum that conforms toMBLoadType
protocol, usingMBLoadable
case to showcase default(container:MBContainable)
on the container when requesting.MBMaskView
-
: Enum that conforms toMBMessageType
protocol, usingMBMessageable
case to show alertController.alertController(title: String, message: String? , actions: [UIAlertAction], container: MBContainable)
-
: With this extension, you can pass a button directly into theUIButton+MBLoadable
method ofload
.DataRequest
-
: With this extension, you can pass a cell directly into theUITableViewCell+MBLoadable
method ofload
.DataRequest
-
: With this extension, you can pass a UIRefreshControl directly into theUIRefreshControl+MBLoadable
method ofload
.DataRequest
-
: With this extension, you can pass a UIProgressView directly into theUIProgressView+MBProgressable
method ofprogress
.DataRequest
-
: Extending UIScrollView to conform toUIScrollView+MBContainable
protocol.MBContainable
-
: Extending UITableViewCell to conform toUITableViewCell+MBContainable
protocol.MBContainable
-
: Extending UIViewController to conform toUIViewController+MBContainable
protocol.MBContainable
-
: Default mask for UITableViewCell and UIButtonMBActivityIndicator
-
: Default mask for others.MBMaskView
Features
- 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 MBNetwork itself.
- We have Default extension for most of the protocol, so you can easily startup.
- And if you have special needs, extend or conform to it.
- The API was designed with the principles of Alamofire, So you can also extend it as MBNetwork already have done for you.
- Mainly focus on things between business development and Alamofire, not network request itself.
Requirements
- Alamofire: Elegant HTTP Networking in Swift
- ObjectMapper: Simple JSON Object mapping written in Swift
- AlamofireObjectMapper: An Alamofire extension which converts JSON response data into swift objects using ObjectMapper
Usage
Create a form
For business development, most of the requests’ headers are the same, so you can extend it only for once.
extension MBFormable {
public func headers() -> [String: String] {
return ["accessToken":"xxx"];
}
}
And you can also have extension for specified protocol
extension MBFormable where Self: MBUploadFormable {
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: MBRequestFormable {
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
MBRequestable
protocol, in this protocol, we’ve already implement some methods for you:
-
func request(_ form: MBRequestFormable) -> DataRequest
-
func download(_ form: MBDownloadFormable) -> DownloadRequest
-
func download(_ form: MBDownloadResumeFormable) -> DownloadRequest
-
func upload(_ form: MBUploadDataFormable) -> UploadRequest
-
func upload(_ form: MBUploadFileFormable) -> UploadRequest
-
func upload(_ form: MBUploadStreamFormable) -> UploadRequest
-
func upload(_ form: MBUploadMultiFormDataFormable, completion: ((UploadRequest) -> Void)?)
Here is the usage of request method:
class LoadableViewController: UIViewController, MBRequestable {
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: MBLoadable = MBLoadType.none) -> Self
Show mask on UIViewController
UIViewController
Show mask on UIButton
UIButton
Notice: The color ofis the
UIActivityIndicatorView
of
tintColor
UIButton
Show customized mask
Firstly, we create a
LoadConfig
class conforms to
MBLoadable
protocol.
class LoadConfig: MBLoadable {
init(container: MBContainable? = nil, mask: MBMaskable? = MBMaskView(), inset: UIEdgeInsets = UIEdgeInsets.zero) {
insetMine = inset
maskMine = mask
containerMine = container
}
func mask() -> MBMaskable? {
return maskMine
}
func inset() -> UIEdgeInsets {
return insetMine
}
func maskContainer() -> MBContainable? {
return containerMine
}
func begin() {
show()
}
func end() {
hide()
}
var insetMine: UIEdgeInsets
var maskMine: MBMaskable?
var containerMine: MBContainable?
}
Then we can use it as followed:
let load = LoadConfig(container: view, mask:MBEyeLoading(), inset: UIEdgeInsetsMake(+, , UIScreen.main.bounds.height--(*++*), ))
request(WeatherForm()).load(load: load)
This is the most powerful usage of the
MBLoadable
protocol. In this way you can customized everything the
MBLoadable
protocol has.
Show mask on UITableView
& UIScrollView
UITableView
UIScrollView
let load = LoadConfig(container:self.tableView, mask: MBActivityIndicator(), inset: UIEdgeInsetsMake(UIScreen.main.bounds.width - self.tableView.contentOffset.y > ? UIScreen.main.bounds.width - self.tableView.contentOffset.y : , , , ))
request(WeatherForm()).load(load: load)
Show mask on UITableViewCell
(PS: Still in development)
UITableViewCell
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
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: MBProgressable) -> Self
And then we can use it as followed:
Show warning message if fail
We have extended
DataRequest
class of Alamofire and added a
warn
method to it.
func warn<T: MBJSONErrorable>(error: T, warn: MBWarnable = MBMessageType.none, completionHandler: ((MBJSONErrorable) -> Void)? = nil) -> Self
And then we can use it as followed:
request(WeatherForm()).warn(error: WeatherError(), warn: MBMessageType.alertController(title: "Warning", message: "Network unavailable", actions: [UIAlertAction(title: "Ok", style: UIAlertActionStyle.cancel, handler: nil)], container: self))
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: MBJSONErrorable>(error: T, inform: MBInformable = MBMessageType.none) -> Self
And then we can use it as followed:
request(WeatherForm()).inform(error: WeatherInformError(), inform: MBMessageType.alertController(title: "Notice", message: "Load successfully", actions: [UIAlertAction(title: "Ok", style: UIAlertActionStyle.cancel, handler: nil)], container: self))
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 AlamofireObjectMapper.
Chained calls
All the method mentioned above can be called in a chained manner, such as followed:
let load = LoadConfig(container: view, mask:MBEyeLoading(), inset: UIEdgeInsetsMake(+, , UIScreen.main.bounds.height--(*++*), ))
let warn = MBMessageType.alertController(title: "Warning", message: "Network unavailable", actions: [UIAlertAction(title: "Ok", style: UIAlertActionStyle.cancel, handler: nil)], container: self)
let inform = MBMessageType.alertController(title: "Notice", message: "Load successfully", actions: [UIAlertAction(title: "Ok", style: UIAlertActionStyle.cancel, handler: nil)], container: self)
request(WeatherForm()).load(load:load).progress(progress: progress).warn(error: WeatherError(), warn: warn).inform(error: WeatherInformError(), inform: inform)
Bonus
MBEyeloading
MBEyeloading
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
MBEyeloading
in example project.
Example
To run the example project, clone the repo, and run
pod install
from the Example directory first.
Installation
MBNetwork is available through CocoaPods. To install
it, simply add the following line to your Podfile:
Author
mmoaay, [email protected]
License
MBNetwork is available under the MIT license. See the LICENSE file for more info.