Unverified Commit 95eca621 authored by Zach Knox's avatar Zach Knox
Browse files

Merged in API to the UI

parents eacfefed f117a6cb
# Contributing to What's Open iOS
We would love for you to contribute to What's Open iOS and help make it even better
than it is today! As a contributor, here are the guidelines we would like you to
follow:
- [Code of Conduct](#coc)
- [Question or Problem?](#question)
- [Issues and Bugs](#issue)
- [Feature Requests](#feature)
- [Submission Guidelines](#submit)
- [Coding Rules](#rules)
- [Commit Message Guidelines](#commit)
## <a name="coc"></a> Code of Conduct
Help us keep What's Open iOS open and inclusive. Please read and follow the
[GMU Student Code of Conduct][coc].
## <a name="question"></a> Got a Question or Problem?
Please, do not open issues for the general support questions as we want to keep
GitLab issues for bug reports and feature requests. You've got much better
chances of getting your question answered on [Slack Group][slack] where
questions should be asked in their respective channels.
## <a name="issue"></a> Found a Bug?
If you find a bug in the source code, you can help us by
[submitting an issue](#submit-issue) to our [GitLab Repository][gitlab]. Even
better, you can [submit a Merge Request](#submit-pr) with a fix.
## <a name="feature"></a> Missing a Feature?
You can *request* a new feature by [submitting an issue](#submit-issue) to our
GitLab Repository. If you would like to *implement* a new feature, please ensure
an issue already exists to be associated with your commits.
* For any **contribution**, first [open an issue](#submit-issue) and outline your proposal so that it can be
discussed. This will also allow us to better coordinate our efforts, prevent duplication of work,
and help you to craft the change so that it is successfully accepted into the project.
## <a name="submit"></a> Submission Guidelines
### <a name="submit-issue"></a> Submitting an Issue
Before you submit an issue, please search through open issues, maybe an issue for
your problem already exists and the discussion might inform you of workarounds
readily available.
We want to fix all the issues as soon as possible, but before fixing a bug we
need to reproduce and confirm it. In order to reproduce bugs we may
ask you to describe a use-case that fails to assist in the debugging process.
In GitLab there are issue templates that you can use which paste in a sample
format for you to use.
Check out the following issue for an example: [https://git.gmu.edu/srct/whats-open/issues/31](https://git.gmu.edu/srct/whats-open/issues/31)
You can file new issues by filling out our [new issue form][new-issue].
### <a name="submit-pr"></a> Steps to contribute and submit a Merge Request (MR)
Before you submit your Merge Request (MR) consider the following steps:
* Search [GitLab][merge-request] for an open or closed MR that relates to your
submission. You don't want to duplicate effort.
* Pull the latest commits from GitLab
```sh
git pull
```
* Check into the current development branch:
All new commits are merged into this development branch before going live on
the site in a tagged release (merge into master branch).
```sh
git checkout dev-0.0
```
* Create a new git branch:
```sh
git checkout -B ##-shortdescription
# Example
git checkout -B 31-contibution-guidelines-proposal
```
All branches need to follow the above convention (`##-shortdescription`) `##`
in this case represents the issue number that your branch is related to. Each
issue has one and only one branch and each branch has one and only one purpose:
to add, modify, or remove a feature/bug from the repo. `shortdescription` is
a few hyphon (`-`) seperated words that consisely describe the branch. This helps people
who may be unfamiliar with the issue number to know at a glance what the branch
* Now you're ready to write your code in your new branch! Make sure to follow
listed [style](#rules) & [commit](#commit) guidelines/rules when contributing
code.
* Unit tests are run at the CI (GitLab-CI) level once you push your code to GitLab.
We do this to ensure that the project builds properly and passes tests. In general,
if you are adding some new piece of code like a function you must **include
appropriate test cases**. _**DOES NOT WORK FOR iOS**_
For example if I compose the following function:
**_Test cases in iOS are different. Standby for documentation on that_**
```python
# file.py
def oneplus(num):
return num + 1
```
then I would additionally write the following test case:
```python
# test_file.py
def TestOneplus(TestCase):
assertEquals(oneplus(1), 2)
```
* Before you push your code to GitLab it is suggested that you run all unit tests locally.
* Commit your changes using a descriptive commit message that follows our
[commit message conventions](#commit). Adherence to these conventions is strongly
suggested as it makes it easier to determine what each commit does when, for example,
things break.
```sh
git add --all
git commit # first line is title, two newlines is description
```
* You will need to ask in the slack channel to be added to the GitLab repo. This
step is necessary such that you have the necessary permissions to push up your
branch.
* Push your branch to GitLab:
```sh
git push origin ##-shortdescription
# ex.
git push origin 31-contibution-guidelines-proposal
```
* In GitLab, send a merge request to the current development branch.
* If we suggest changes to your branch then:
* Make the required updates.
* Re-run the unit tests to ensure tests are still passing.
* Rebase your branch and force push to your GitLab repository (this will update
your Merge Request):
```sh
git rebase consolidation -i
git push -f
```
That's it! Thank you for your contribution! :tada:
#### After your merge request is merged
After your merge request is merged, you can safely delete your branch and merge
the changes from the main (upstream) repository:
* Delete the remote branch on GitLab either through the GitLab web UI or your
local shell as follows:
```sh
git push origin --delete ##-shortdescription
# ex.
git push origin --delete 31-contibution-guidelines-proposal
```
* Check out the current development branch:
```sh
git checkout consolidation -f
```
* Delete the local branch:
```sh
git branch -D ##-shortdescription
# ex.
git branch -D 31-contibution-guidelines-proposal
```
* Update your current development branch with the latest upstream version:
```sh
git l --ff upstream consolidation
```
## <a name="rules"></a> Coding Rules
To ensure consistency throughout the source code, keep these rules in mind as you
are working:
* All features or bug fixes **must be tested** by one or more specs (unit-tests).
## <a name="commit"></a> Commit Message Guidelines
Consistant commit messages are easier to follow when looking through the **project
history**.
### Commit Message Format
Each commit message consists of a **header**, a **body** and a **footer**. The
header has a special format that includes a **type** and a **subject**. The **header**
is mandatory.
Layout:
```
<type>: <subject> # this is the <header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```
Sample headers:
```
docs: update change log to beta.5
```
```
fix: need to depend on latest rxjs and zone.js
```
### <header> Type
Must be one of the following:
* **build**: Changes that affect the build system or external dependencies
(example scopes: gulp, broccoli, npm)
* **ci**: Changes to our gitlab-ci configuration files and scripts
* **docs**: Documentation only changes
* **feat**: A new feature
* **fix**: A bug fix
* **perf**: A code change that improves performance
* **refactor**: A code change that neither fixes a bug nor adds a feature
* **style**: Changes that do not affect the meaning of the code (white-space, formatting,
etc.)
* **test**: Adding missing tests or correcting existing tests
### <header> Subject
The subject contains succinct description of the change.
Sample Subject:
```
add in contributing guide
```
### Body
The body should include a brief description of the changes made in the commit to
provide additional detail.
Sample Body:
```
- Introduce my proposal for CONTRIBUTING.md
- Filled with the whats-open-web contributing guide but contains friendlier language
```
### Footer
The footer should contain any information about **Breaking Changes** (**Breaking
Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines.
The rest of the commit message is then used for this. and is also the place to
reference GitLab issues that this commit **Closes**.
Sample footers:
```
BREAKING CHANGE: remove outdated dependency from requirements.txt. be sure to
reinstall your packages in order for the project to build.
```
```
Closes #31
```
This "Closes" statement should only be incuded in commits that resolve an issue.
What's nice about the statement itself is that when the commit is merged, the issue
will auto close.
If neither of these situations are the case (breaking changes or issue closing)
then feel free to omit the footer.
[coc]: https://studentconduct.gmu.edu/wp-content/uploads/2011/09/2016-17-Code-of-Student-Conduct.pdf
[gitlab]: https://git.gmu.edu/srct/whats-open
[slack]:https://srct.slack.com/
[new-issue]:https://git.gmu.edu/srct/whats-open/issues/new
[merge-request]:https://git.gmu.edu/srct/whats-open/merge_requests
......@@ -16,7 +16,7 @@ There are many things that can be done with this project (see the "To Do" sectio
If you need help at all please contact and SRCT member. We want people to contribute, so if you are struggling, or just want to learn we are more than willing to help.
The project lead for this project is **Eyad Hasan**. *ehasan3@gmu.edu*
The project manager for this project is **Eyad Hasan**. *ehasan3@gmu.edu*
Please visit the [SRCT Wiki](http://wiki.srct.gmu.edu/) for more information on this and other SRCT projects, along with other helpful links and tutorials.
......@@ -24,7 +24,7 @@ Please visit the [SRCT Wiki](http://wiki.srct.gmu.edu/) for more information on
Setup
---
Requirements:
Requirements:
To get started, you'll need the following installed:
* [Git](http://git-scm.com/book/en/Getting-Started-Installing-Git)
......@@ -39,7 +39,7 @@ To get started, you'll need the following installed:
Open a terminal window and type in the following commands. This will create a local, workable copy of the project.
``bash``
``git clone [url]`` where the URL is the one listed at the top of the git repository for this project (preferrably using SSH)
Install the needed dependencies by running
``pod install``
inside the the WhatsOpen directory.
......@@ -55,7 +55,7 @@ clang: error: linker command failed with exit code 1 (use -v to see invocation)`
To-do
---
Check the issues list for things that need to be done.
Note-- this should also be on the wiki
About GMU SRCT
......
......@@ -5,19 +5,20 @@ use_frameworks!
target 'WhatsOpen' do
# pod 'RealmSwift'
# pod 'ObjectMapper+Realm', '~> 0.2'
pod 'RealmSwift'
# pod 'Segmentio', '~> 2.1'
pod 'ObjectMapper', '~> 2.2'
#pod 'Segmentio', '~> 2.1'
pod 'DeckTransition', '~> 1.0'
end
# post_install do |installer|
# installer.pods_project.targets.each do |target|
# target.build_configurations.each do |config|
# config.build_settings['SWIFT_VERSION'] = '3.0'
# end
# end
# end
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['SWIFT_VERSION'] = '3.1'
end
end
end
PODS:
- DeckTransition (1.2.0)
- ObjectMapper (2.2.8)
- Realm (2.10.1):
- Realm/Headers (= 2.10.1)
- Realm/Headers (2.10.1)
- RealmSwift (2.10.1):
- Realm (= 2.10.1)
DEPENDENCIES:
- DeckTransition (~> 1.0)
- ObjectMapper (~> 2.2)
- RealmSwift
SPEC CHECKSUMS:
DeckTransition: 23a2c7bdb24bf740a460da72cbb25f9dd28d0a51
ObjectMapper: 3d571bb5af471c779e1160828cd9ad5c4ef90958
Realm: fc7a317a5c2c9ba91f5f235ede4e2ea76e9eba0c
RealmSwift: 505ed6c15942a2e76f5cfa78a8667cfa997ee75b
PODFILE CHECKSUM: 0d945be0cf7bfa1e45899bb7bbb3730c684345e0
PODFILE CHECKSUM: 84f488897b7d96947925a9d04edb67bb66a2cde9
COCOAPODS: 1.2.1
COCOAPODS: 1.3.1
PODS:
- DeckTransition (1.2.0)
- ObjectMapper (2.2.8)
- Realm (2.10.1):
- Realm/Headers (= 2.10.1)
- Realm/Headers (2.10.1)
- RealmSwift (2.10.1):
- Realm (= 2.10.1)
DEPENDENCIES:
- DeckTransition (~> 1.0)
- ObjectMapper (~> 2.2)
- RealmSwift
SPEC CHECKSUMS:
DeckTransition: 23a2c7bdb24bf740a460da72cbb25f9dd28d0a51
ObjectMapper: 3d571bb5af471c779e1160828cd9ad5c4ef90958
Realm: fc7a317a5c2c9ba91f5f235ede4e2ea76e9eba0c
RealmSwift: 505ed6c15942a2e76f5cfa78a8667cfa997ee75b
PODFILE CHECKSUM: 0d945be0cf7bfa1e45899bb7bbb3730c684345e0
PODFILE CHECKSUM: 84f488897b7d96947925a9d04edb67bb66a2cde9
COCOAPODS: 1.2.1
COCOAPODS: 1.3.1
The MIT License (MIT)
Copyright (c) 2014 Hearst
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
# ObjectMapper-CN-Guide
> 文档由Swift老司机活动中心负责翻译,欢迎关注[@SwiftOldDriver](http://weibo.com/6062089411)。翻译有问题可以到 [ObjectMapper-CN-Guide](https://github.com/SwiftOldDriver/ObjectMapper-CN-Guide) 提 PR。
[ObjectMapper](https://github.com/Hearst-DD/ObjectMapper) 是一个使用 Swift 编写的用于 model 对象(类和结构体)和 JSON 之间转换的框架。
- [特性](#特性)
- [基础使用方法](#基础使用方法)
- [映射嵌套对象](#映射嵌套对象)
- [自定义转换规则](#自定义转换规则)
- [继承](#继承)
- [泛型对象](#泛型对象)
- [映射时的上下文对象](#映射时的上下文对象)
- [ObjectMapper + Alamofire](#objectmapper--alamofire)
- [ObjectMapper + Realm](#objectmapper--realm)
- [待完成](#待完成)
- [安装](#安装)
# 特性:
- 把 JSON 映射成对象
- 把对象映射 JSON
- 支持嵌套对象 (单独的成员变量、在数组或字典中都可以)
- 在转换过程支持自定义规则
- 支持结构体( Struct )
- [Immutable support](#immutablemappable-protocol-beta) (目前还在 beta )
# 基础使用方法
为了支持映射,类或者结构体只需要实现```Mappable```协议。这个协议包含以下方法:
```swift
init?(map: Map)
mutating func mapping(map: Map)
```
ObjectMapper使用自定义的```<-``` 运算符来声明成员变量和 JSON 的映射关系。
```swift
class User: Mappable {
var username: String?
var age: Int?
var weight: Double!
var array: [AnyObject]?
var dictionary: [String : AnyObject] = [:]
var bestFriend: User? // 嵌套的 User 对象
var friends: [User]? // Users 的数组
var birthday: NSDate?
required init?(map: Map) {
}
// Mappable
func mapping(map: Map) {
username <- map["username"]
age <- map["age"]
weight <- map["weight"]
array <- map["arr"]
dictionary <- map["dict"]
bestFriend <- map["best_friend"]
friends <- map["friends"]
birthday <- (map["birthday"], DateTransform())
}
}
struct Temperature: Mappable {
var celsius: Double?
var fahrenheit: Double?
init?(map: Map) {
}
mutating func mapping(map: Map) {
celsius <- map["celsius"]
fahrenheit <- map["fahrenheit"]
}
}
```
一旦你的对象实现了 `Mappable`, ObjectMapper就可以让你轻松的实现和 JSON 之间的转换。
把 JSON 字符串转成 model 对象:
```swift
let user = User(JSONString: JSONString)
```
把一个 model 转成 JSON 字符串:
```swift
let JSONString = user.toJSONString(prettyPrint: true)
```
也可以使用`Mapper.swift`类来完成转换(这个类还额外提供了一些函数来处理一些特殊的情况:
```swift
// 把 JSON 字符串转成 Model
let user = Mapper<User>().map(JSONString: JSONString)
// 根据 Model 生成 JSON 字符串
let JSONString = Mapper().toJSONString(user, prettyPrint: true)
```
ObjectMapper支持以下的类型映射到对象中:
- `Int`
- `Bool`
- `Double`
- `Float`
- `String`
- `RawRepresentable` (枚举)
- `Array<AnyObject>`
- `Dictionary<String, AnyObject>`
- `Object<T: Mappable>`
- `Array<T: Mappable>`
- `Array<Array<T: Mappable>>`
- `Set<T: Mappable>`
- `Dictionary<String, T: Mappable>`
- `Dictionary<String, Array<T: Mappable>>`
- 以上所有的 Optional 类型
- 以上所有的隐式强制解包类型(Implicitly Unwrapped Optional)
## `Mappable` 协议
#### `mutating func mapping(map: Map)`
所有的映射最后都会调用到这个函数。当解析 JSON 时,这个函数会在对象创建成功后被执行。当生成 JSON 时就只有这个函数会被对象调用。
#### `init?(map: Map)`
这个可失败的初始化函数是 ObjectMapper 创建对象的时候使用的。开发者可以通过这个函数在映射前校验 JSON 。如果在这个方法里返回 nil 就不会执行 `mapping` 函数。可以通过传入的保存着 JSON 的 `Map` 对象进行校验:
```swift
required init?(map: Map){
// 检查 JSON 里是否有一定要有的 "name" 属性
if map.JSONDictionary["name"] == nil {
return nil
}
}
```
## `StaticMappable` 协议
`StaticMappable``Mappable` 之外的另一种选择。 这个协议可以让开发者通过一个静态函数初始化对象而不是通过 `init?(map: Map)`
注意: `StaticMappable``Mappable` 都继承了 `BaseMappable` 协议。 `BaseMappable` 协议声明了 `mapping(map: Map)` 函数。
#### `static func objectForMapping(map: Map) -> BaseMappable?`
ObjectMapper 使用这个函数获取对象后进行映射。开发者需要在这个函数里返回一个实现 `BaseMappable` 对象的实例。这个函数也可以用于:
- 在对象进行映射前校验 JSON
- 提供一个缓存过的对象用于映射
- 返回另外一种类型的对象(当然是必须实现了 BaseMappable)用于映射。比如你可能通过检查 JSON 推断出用于映射的对象 ([看这个例子](https://github.com/Hearst-DD/ObjectMapper/blob/master/ObjectMapperTests/ClassClusterTests.swift#L62))。
如果你需要在 extension 里实现 ObjectMapper,你需要选择这个协议而不是 `Mappable`
## `ImmutableMappable` Protocol (Beta)
> ⚠️ 这个特性还处于 Beta 阶段。正式发布时 API 可能会完全不同。
使用 `ImmutableMappable` 可以映射不可变的属性。下面的表格展示了 `ImmutableMappable``Mappable` 的不同:
<table>
<tr>
<th>ImmutableMappable</th>
<th>Mappable</th>
</tr>
<tr>
<th colspan="2">Properties</th>
</tr>
<tr>
<td>
<pre>
<strong>let</strong> id: Int
<strong>let</strong> name: String?
</pre>
</td>
<td>
<pre>
var id: Int!
var name: String?
</pre>
</td>
</tr>
<tr>
<th colspan="2">JSON -> Model</th>
</tr>
<tr>
<td>
<pre>
init(map: Map) <strong>throws</strong> {
id = <strong>try</strong> map.value("id")
name = <strong>try?</strong> map.value("name")
}
</pre>
</td>
<td>
<pre>
mutating func mapping(map: Map) {
id <- map["id"]
name <- map["name"]
}
</pre>
</td>
</tr>
<tr>
<th colspan="2">Model -> JSON</th>
</tr>
<tr>
<td>
<pre>
mutating func mapping(map: Map) {
id <strong>>>></strong> map["id"]
name <strong>>>></strong> map["name"]
}
<