Latest | 0.0.3 |
---|---|
Homepage | https://github.com/wangrq/iSwiftForm |
License | MIT |
Platforms | ios 8.0, requires ARC |
Authors |
iSwiftForm is a lightweight framework to build iOS Forms. It’s written in Swift, simple to use and easy to customize!
- Requirement:
- XCode 10.2.1+, Swift 5.0+
- Features:
- Support iOS 8.0+, iPhone and iPad devices
- Auto-complete input field
- Support bluetooth keyboard
![]() |
![]() |
---|
Contents
Setup
Use Podfile
[To be updated]
Copy source files to your project directly
-
Download the repo.
-
Copy all the source files under iSwiftForm/iSwiftForm/Sources/ to your project.
- Now it’s ready to use.
import iSwiftForm
[Your code]
Run the Examples App
You can run the Examples App on your simulator or your devices:
- Download the repo.
- Open the iSwiftForm.xcworkspace file.
- Click the target iSwiftForm and Examples, config your development team in the General – Signing section.
- Click the scheme Examples on the top-left corner, and hit the RUN triangle button.
Example usage
Basic usage
- Create your form class and extends FormBaseDataHolder
class DataHolder: FormBaseDataHolder { // Config the form override func fillFormData() { // } // Form controls callback override func valueChanged(sectionNumber: Int, rowNumber: Int, value: String, formData: FormData) -> Bool { // } }
2. Override the necessary methods:
```swift
class DataHolder: FormBaseDataHolder {
var rawData: [String: String] = [:]
// Config the form
override func fillFormData() {
// Create a form group
var group = FormDataGroup("Basic Info")
// Add a Input form control
group += FormData(CellType.Input).config(title: "Name", textSuggestions: ["John Snow", "John Green"]).itemKey("name", self)
// Add a Segmented form control
group += FormData(CellType.SegmentedControl).config(title: "Gender", textSuggestions: ["Male", "Female"]).itemKey("gender", self)
// Add a Date Time form control
group += FormData(CellType.DateTime).config(title: "Birth").itemKey("birth", self).options(["mode": "date"])
// Append this form group
self.append(group)
// Create another form group
group = FormDataGroup("More Info")
// Add a Single Select form control
group += FormData(CellType.ExpandTable).config(title: "Mood", textSuggestions: ["😝", "😭", "☹️"]).itemKey("mood", self)
// Add a Multiple Select form control
group += FormData(CellType.ExpandTable).config(title: "Favorite Foods", textSuggestions: ["🍔", "🍜", "🌽"]).options(["type": "multiple"]).itemKey("food", self)
// Append this form group
self.append(group)
// Create the third form group
group = FormDataGroup()
// Add a Big Button form control
group += FormData(CellType.ButtonBig).config(title: "Submit").options(["color": "none"]).itemKey("submit")
// Append this form group
self.append(group)
}
// Form controls callback
override func valueChanged(sectionNumber: Int, rowNumber: Int, value: String, formData: FormData) -> Bool {
// save the latest form value
self.rawData[formData.key] = value
return true;
}
}
- Present the form UI:
// Your ViewController class ViewController: UIViewController { override func viewDidAppear(_ animated: Bool) { // Create the form data holder, and attach it to the base form viewcontroller let vc = DataHolder().attach(FormBaseController()); // Show it self.present(vc, animated: true, completion: nil); } }
Button to open a QR Scanner
class DataHolder: FormBaseDataHolder, QRScannerCallback {
// Config the form
override func fillFormData() {
... some form data here ...
// Add an Input form control
group += FormData(CellType.Input).config(title: "ID Number", value: self.myFormData["idnumber"])
// Add a Button form control
group += FormData(CellType.Button).config(title: "Scan a bar code").itemKey("scan")
}
// Form controls callback
override func valueChanged(sectionNumber: Int, rowNumber: Int, value: String, formData: FormData) -> Bool {
if (formData.key == "scan") {
Utils.scanBarcode(key: "idnumber", callback: self, from: self.page)
}
return true;
}
// QR Scanner Callback
func qrScannerResult(key: String, value: String) {
self.myFormData[key] = value
// Refresh the form
self.requestUpdate()
}
}
Full APIs
Global configuration
FormConfigs
FormConfigs has some static properties for global form configuration.
- tableViewSectionColor: UIColor (default value: 0xF0F0F5)
- form view controller background color
- selectedColor: UIColor (default value: 0x024172)
- form cell title color (focused)
- defaultSelectedColor: UIColor (default value: 0xd9d9d9)
- form cell background color (focused)
- buttonTextColor: UIColor (default value: 0x005aa0)
- default text color of Button
- bigButtonTextColor: UIColor (default value: 0x0C8E11)
- default text color of Big Button
- editBackgroundColor: UIColor (default value: 0xd0d0d0)
- used in editable Text, the background color of the edit text
-
editBorderNokColor: UIColor (default value: 0xE25859)
- used in editable Text, the border color if the edit text isn’t validated
- fillCellWithOKColor: Bool (default value: false)
- should the validated cell be filled with a background color
- okLightGreenColor: UIColor (default value: 0xd1e9d2)
- the background color of the validated cell (only show it if fillCellWithOKColor = true)
-
okLightGreenColorFocused: UIColor (default value: 0xbedfbf)
- the background color of the focused validated cell (only show it if fillCellWithOKColor = true)
- headerAlignment: NSTextAlignment (default value: .center)
- form group header text alignment
- headerPadding: UIEdgeInsets? (default value: UIEdgeInsets(top: 18, left: 18, bottom: 0, right: 0))
- form group header text paddings
FormBaseDataHolder
- page: FormBaseController
- the form view controller
- requestUpdate()
- reload the form data
- append(_ formDataGroup: FormDataGroup)
- add a new form group
-
attach(_ page: FormBaseController) -> FormBaseController
- attach the data holder to a view controller, return the new view controller
- fillFormData()
- override method. configure the form data
- valueChanged(sectionNumber: Int, rowNumber: Int, value: String, formData: FormData) -> Bool
- override method. form controls callback. return value isn’t used for now
- shouldUpdateWhenAppear() -> Bool
- override method. should the form data reloaded when base view controller’s viewDidAppear() method called
FormDataGroup
FormDataGroup is a group of form controls, it shows an optional header text above all the form controls.
- init()
- init(_ name: String)
- constructor, create a new form data group (with a header text)
- append(_ formData: FormData)
- +=(left: inout FormDataGroup, right: FormData)
- append a new form data
FormData
FormData is the basic unit to describe a form control.
- init(_ type: String)
- init(_ type: CellType)
- construcor, create a new form control
-
config(title: String, value: String? = nil) -> FormData
- set the title and the value of the form control
- config(title: String, textSuggestions: [String], value: String? = nil) -> FormData
- set the text suggestions as string array. (for Input auto-complete, Select)
- config(title: String, textSuggestionSource: TextSuggestionSource, value: String? = nil) -> FormData
- set the text suggestions as class. (for Input auto-complete, Select)
-
itemKey( key: String, rawData: [String: String]? = nil) -> FormData
- set a key for the form control. the rawData[key] will be used as the value if rawData is not nil
- options(_ options: [String: String]) -> FormData
- set some options for the form control. Please refer to the bellow CellType for details
- enable(_ enable: Bool) -> FormData
- is the form control enabled (for Input, Button, etc…)
- valuePlaceHolder(_ valuePlaceHolder: String) -> FormData
- set the placeholder of the input text
- contentOptions(_ contentOptions: [String: Any]) -> FormData
- set the content options. this isn’t used for now
-
inputType(_ type: InputType) -> FormData
- set the keyboard input type
- validator(_ validator: Validator?) -> FormData
- set a custom validator
-
validator( type: Validators, options: [String: Any]? = nil) -> FormData
- set a preset validator, with some options
- validate() -> Bool
- is the form control pass the validation
When the options(_ options: [String: String]) is called, these options will be passed to the Form Cell. Each Cell is controlled by different options, here is a list of them:
Input (CellType.Input)
- options: ["bold": "true"]
- is the input field use bold texts
Text (CellType.Text)
- options: ["type": "edit"]
- is the form control editable
Select (CellType.ExpandTable)
-
options: ["type": "multiple"]
- is the form control support multiple selection
- options: ["allowDeselect": "true"]
- is the form control allow deselect items
Date Picker (CellType.DateTime)
-
options: ["futureDays": "XX"]
- allow maximum XX days in future to be selected
-
options: ["mode": "date | time"]
- set the data picker mode. the default mode is date and time when the ‘mode’ option isn’t present
- options: ["oneDayAfter": "baseDay, format yyyy-MM-dd HH:mm"]
- set the selectable date [baseDay, baseDay + 1 day]
Button (CellType.Button)
- options: ["style": "delete"]
- show a different button style
Radio Button (CellType.SegmentedControl)
- options: ["disabledSegement": "index, type is Int"]
- disable certain radio button
Big Button (CellType.ButtonBig)
- options: ["color": "red | gray"]
- show a different button style
Signature (CellType.Signature)
- options: ["disableEditIfNotEmpty": "true"]
- disable the edit once it’s signed
Extend the framework
Add a new form control
- call CellType.register(_ newType: String) to register a new form control type
- add FormXXCell.swift and FormXX.xib source file to discribe the view and behaviour
- now you can use the FormData.init(_ type: String) to create your own form control
Contribute
PRs are welcomed. Any ideas please contact me via Email
Latest podspec
{ "name": "iSwiftForm", "version": "0.0.3", "license": "MIT", "summary": "A lightweight framework to build iOS Forms.", "homepage": "https://github.com/wangrq/iSwiftForm", "authors": { "Renquan Wang": "[email protected]" }, "source": { "git": "https://github.com/wangrq/iSwiftForm.git", "tag": "0.0.3" }, "platforms": { "ios": "8.0" }, "ios": { "frameworks": [ "UIKit", "Foundation" ] }, "source_files": "iSwiftForm/Sources/**/*.swift", "resources": [ "iSwiftForm/Sources/**/*.xcassets", "iSwiftForm/Sources/**/*.xib" ], "requires_arc": true, "swift_versions": "5.0", "swift_version": "5.0" }
Wed, 29 May 2019 10:27:07 +0000