Eureka
Elegant iOS form builder in Swift
Install / Use
/learn @xmartlabs/EurekaREADME
Made with ❤️ by XMARTLABS. This is the re-creation of [XLForm] in Swift.
Overview
<table> <tr> <th> <img src="Example/Media/EurekaExample1.gif" width="220"/> </th> <th> <img src="Example/Media/EurekaExample2.gif" width="220"/> </th> <th> <img src="Example/Media/EurekaExample3.gif" width="220"/> </th> </tr> </table>Contents
- [Requirements]
- [Usage]
- [How to create a Form]
- [Getting row values]
- [Operators]
- [Using the callbacks]
- [Section Header and Footer]
- [Dynamically hide and show rows (or sections)]
- [List sections]
- [Multivalued sections]
- [Validations]
- [Swipe Actions]
- [Custom rows]
- [Basic custom rows]
- [Custom inline rows]
- [Custom presenter rows]
- [Row catalog]
- [Installation]
- [FAQ]
For more information look at [our blog post] that introduces Eureka.
Requirements (for latest release)
- Xcode 11+
- Swift 5.0+
Example project
You can clone and run the Example project to see examples of most of Eureka's features.
<table> <tr> <th> <img src="Example/Media/EurekaNavigation.gif" width="200"/> </th> <th> <img src="Example/Media/EurekaRows.gif" width="200"/> </th> </tr> </table>Usage
How to create a form
By extending FormViewController you can then simply add sections and rows to the form variable.
import Eureka
class MyFormViewController: FormViewController {
override func viewDidLoad() {
super.viewDidLoad()
form +++ Section("Section1")
<<< TextRow(){ row in
row.title = "Text Row"
row.placeholder = "Enter text here"
}
<<< PhoneRow(){
$0.title = "Phone Row"
$0.placeholder = "And numbers here"
}
+++ Section("Section2")
<<< DateRow(){
$0.title = "Date Row"
$0.value = Date(timeIntervalSinceReferenceDate: 0)
}
}
}
In the example we create two sections with standard rows, the result is this:
<center> <img src="Example/Media/EurekaHowTo.gif" width="200" alt="Screenshot of Custom Cells"/> </center>You could create a form by just setting up the form property by yourself without extending from FormViewController but this method is typically more convenient.
Configuring the keyboard navigation accesory
To change the behaviour of this you should set the navigation options of your controller. The FormViewController has a navigationOptions variable which is an enum and can have one or more of the following values:
- disabled: no view at all
- enabled: enable view at the bottom
- stopDisabledRow: if the navigation should stop when the next row is disabled
- skipCanNotBecomeFirstResponderRow: if the navigation should skip the rows that return false to
canBecomeFirstResponder()
The default value is enabled & skipCanNotBecomeFirstResponderRow
To enable smooth scrolling to off-screen rows, enable it via the animateScroll property. By default, the FormViewController jumps immediately between rows when the user hits the next or previous buttons in the keyboard navigation accesory, including when the next row is off screen.
To set the amount of space between the keyboard and the highlighted row following a navigation event, set the rowKeyboardSpacing property. By default, when the form scrolls to an offscreen view no space will be left between the top of the keyboard and the bottom of the row.
class MyFormViewController: FormViewController {
override func viewDidLoad() {
super.viewDidLoad()
form = ...
// Enables the navigation accessory and stops navigation when a disabled row is encountered
navigationOptions = RowNavigationOptions.Enabled.union(.StopDisabledRow)
// Enables smooth scrolling on navigation to off-screen rows
animateScroll = true
// Leaves 20pt of space between the keyboard and the highlighted row after scrolling to an off screen row
rowKeyboardSpacing = 20
}
}
If you want to change the whole navigation accessory view, you will have to override the navigationAccessoryView variable in your subclass of FormViewController.
Getting row values
The Row object holds a value of a specific type.
For example, a SwitchRow holds a Bool value, while a TextRow holds a String value.
// Get the value of a single row
let row: TextRow? = form.rowBy(tag: "MyRowTag")
let value = row.value
// Get the value of all rows which have a Tag assigned
// The dictionary contains the 'rowTag':value pairs.
let valuesDictionary = form.values()
Operators
Eureka includes custom operators to make form creation easy:
+++ Add a section
form +++ Section()
// Chain it to add multiple Sections
form +++ Section("First Section") +++ Section("Another Section")
// Or use it with rows and get a blank section for free
form +++ TextRow()
+++ TextRow() // Each row will be on a separate section
<<< Insert a row
form +++ Section()
<<< TextRow()
<<< DateRow()
// Or implicitly create the Section
form +++ TextRow()
<<< DateRow()
+= Append an array
// Append Sections into a Form
form += [Section("A"), Section("B"), Section("C")]
// Append Rows into a Section
section += [TextRow(), DateRow()]
Result builders
Eureka includes result builders to make form creation easy:
@SectionBuilder
// Section + Section
form = (Section("A") +++ {
URLRow("UrlRow_f1") { $0.title = "Url" }
if something {
TwitterRow("TwitterRow_f2") { $0.title = "Twitter" }
} else {
TwitterRow("TwitterRow_f1") { $0.title = "Twitter" }
}
AccountRow("AccountRow_f1") { $0.title = "Account" }
})
// Form + Section
form +++ {
if something {
PhoneRow("PhoneRow_f1") { $0.title = "Phone" }
} else {
PhoneRow("PhoneRow_f2") { $0.title = "Phone" }
}
PasswordRow("PasswordRow_f1") { $0.title = "Password" }
}
@FormBuilder
@FormBuilder
var form: Form {
Section("Section A") { section in
section.tag = "Section_A"
}
if true {
Section("Section B") { section in
section.tag = "Section_B"
}
}
NameRow("NameRow_f1") { $0.title = "Name" }
}
Using the callbacks
Eureka includes callbacks to change the appearance and behavior of a row.
Understanding Row and Cell
A Row is an abstraction Eureka uses which holds a value and contains the view Cell. The Cell manages the view and subclasses UITableViewCell.
Here is an example:
let row = SwitchRow("SwitchRow") { row in // initializer
row.title = "The title"
}.onChange { row in
row.title = (row.value ?? false) ? "The title expands when on" : "The title"
row.updateCell()
}.cellSetup { cell, row in
cell.backgroundColor = .lightGray
}.cellUpdate { cell, row in
cell.textLabel?.font = .italicSystemFont(ofSize: 18.0)
}
Callbacks list
-
onChange()
Called when the value of a row changes. You might be interested in adjusting some parameters here or even make some other rows appear or disappear.
-
onCellSelection()
Called each time the user taps on the row and it gets selected. Note that this will also get called for disabled rows so you should start your code inside this callback with something like
guard !row.isDisabled else { return } -
cellSetup()
Called only once when the cell is first configured. Set permanent settings here.
-
cellUpdate()
Called each time the cell appears on screen. You can change the appearance here using variables that may not be present on cellSetup().
-
onCellHighlightChanged()
Called whenever the cell or any subview become or resign the first responder.
-
onRowValidationChanged()
Called whenever the the validation errors associated with a row changes.
-
onExpandInlineRow()
Called before expanding the inline row. Applies to rows conforming
InlineRowTypeprotocol. -
onCollapseInlineRow()
Called before collapsing the inline row. Applies to rows conforming
InlineRowTypeprotocol. -
onPresent()
Called by a row just before presenting another view controller. Applies to rows conforming
PresenterRowTypeprotocol. Use it to set up the presente
Related Skills
node-connect
342.5kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
frontend-design
85.3kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
342.5kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
qqbot-media
342.5kQQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。
