Eureka travis-ci CocoaPods

Elegant iOS form builder in Swift 2

3 years after

Eureka: Elegant form builder in Swift

Build status Platform iOS Swift 2 compatible Carthage compatible CocoaPods compatible License: MIT

By XMARTLABS. This is the re-creation of [XLForm] in Swift 2.

  • [Introduction]
  • [Requirements]
  • [Examples]
  • [Usage]
    • [How to create a Form]
    • [Operators]
    • [Rows]
    • [Customization]
    • [Section Header and Footer]
    • [How to dynamically hide and show rows (or sections)]
  • [Extensibility]
    • [How to create custom rows and cells]
    • [How to create custom inline rows]
    • [Implementing a custom Presenter row]
    • [Custom rows catalog]
  • [Installation]
  • [FAQ]

Introduction

Eureka! is a library to create dynamic table-view forms from a [DSL] specification in Swift. This DSL basically consists of Rows, Sections and Forms. A Form is a collection of Sections and a Section is a collection of Rows.

If you have been using XLForm then many terms will result familiar to you.

Both Form and Section classes conform to MutableCollectionType and RangeReplaceableCollectionType protocols. This makes a whole bunch of functions available to be executed on them.

For more information look at [our blog post] that introduces Eureka!.

Requirements

  • iOS 8.0+
  • Xcode 7.0+

Getting involved

  • If you want to contribute please feel free to submit pull requests.
  • If you have a feature request please open an issue.
  • If you found a bug or need help please check older issues or threads on [StackOverflow] before submitting an issue.

If you use Eureka in your app We would love to hear about it! Drop us a line on [twitter].

Examples

Follow these 3 steps to run Example project: Clone Eureka repository, open Eureka workspace and run the Example project.

You can also experiment and learn with the Eureka Playground which is contained in Eureka.workspace.

Usage

How to create a form

It is quite simple to create a form, just like this:

import Eureka

class CustomCellsController : FormViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        form +++ Section("Custom cells")
                    <<< WeekDayRow(){
                        $0.value = [.Monday, .Wednesday, .Friday]
                    }
                    <<< TextFloatLabelRow() {
                        $0.title = "Float Label Row, type something to see.."
                    }
    }
}

In this example we create a [CustomCellsController] and then simply add a section with two custom rows to the form variable.

And this is the product:

Screenshot of Custom Cells

As you may have noticed CustomCellsController extends from FormViewController which has a form property that can be used to declare the form as the example shows. WeekDayRow and TextFloatLabelRow are non-standard rows included in the example project, but the standard rows usage is analog. You can create a form by just setting up the form property without extending from FormViewController but typically it is more convenient to create a custom view controller that extends from it.

Operators

We declared a series of custom operators to make the creation and modification of forms more readable and appealing.

+++=

This operator is used to append a row or section to a form. In case you are appending a row, then a section will be created that contains that row and that section will be appended to the form.

// Will append a section at the end of the 'form' Form.
form +++= Section()

// Will internally create a Section containing a PhoneRow and append it to the 'form' variable:
form +++= PhoneRow()

+++

Lets you add a Section to a Form or create a Form by adding two sections. For example:

// Will add two sections at the end of the 'form' Form.
form +++ Section("Custom cells") +++ Section("Another section")

// Will create and assign a Form to the 'form' variable (containing the two sections):
form = Section("Custom cells") +++ Section("Another section")

<<<

This one is used to append rows to sections or to create a Section by appending two rows. For example:

// Will append a Check row to the last section of the 'form' Form.
form.last! <<< CheckRow()

// Will implicitly create a Section and add it to the 'form' (containing the two rows):
form +++ PhoneRow("Phone"){ $0.title = "Phone"}
         <<< IntRow("IntRow"){ $0.title = "Int"; $0.value = 5 }

+=

This operator just invokes the corresponding appendContentsOf method which means that it can be used to append arrays of elements to either a Form or a Section like this:

// Will append three sections to form.
form += [Section("A"), Section("B"), Section("C")]
To learn more about these operators try them out in Eureka Playground.

Rows

This is a list of the rows that are provided by default:

  • Field Rows This rows have a textfield on the right side of the cell. The difference between each one of them consists in a different capitalization, autocorrection and keyboard type configuration.

    • TextRow
    • NameRow
    • UrlRow
    • IntRow
    • PhoneRow
    • PasswordRow
    • EmailRow
    • DecimalRow
    • TwitterRow
    • AccountRow
    • ZipCodeRow
  • Date Rows Date Rows hold a NSDate and allow us to set up a new value through UIDatePicker control. The mode of the UIDatePicker and the way how the date picker view is shown is what changes between them.

    • DateRow
    • DateInlineRow
    • TimeRow
    • TimeInlineRow
    • DateTimeRow
    • DateTimeInlineRow
    • CountDownRow
    • CountDownInlineRow
    • DatePickerRow
    • TimePickerRow
    • DateTimePickerRow
    • CountDownPickerRow
  • Options Selector Rows These are rows with a list of options associated from which the user must choose. You can see them in the examples above.

    • AlertRow
    Screenshot of Custom Cells
    • ActionSheetRow

      The ActionSheetRow will show an action sheet with options to choose from.

    • SegmentedRow

    Screenshot of Segment Row
    • PushRow

      This row will push to a new controller from where to choose options listed using Check rows.

    • ImageRow

      Will let the user pick a photo

    • MultipleSelectorRow

      This row allows the selection of multiple options

    • PickerRow

      This row allows you to present options of a generic type through a picker view

    • PickerInlineRow

      This row uses the PickerRow row as its inline row

    • LocationRow (Included as custom row in the example project)

    Screenshot of Location Row
  • Other Rows These are other rows that might be useful

    • ButtonRow
    • CheckRow
    • LabelRow
    • SwitchRow
    • TextAreaRow

There are also some custom rows in the examples project.

Customization

A row holds the basic information that will be displayed on a cell like title, value, options (if present), etc. All the stuff that has to do with appearance like colors, fonts, text alignments, etc. normally go in the cell. Both, the row and the cell hold a reference to each other.

You will often want to customize how a row behaves when it is tapped on or when its value changes and you might be interested in changing its appearance as well. There are many callbacks to change the default appearance and behaviour of a row.

  • onChange()

    This will be 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()

    This one will be called each time the user taps on the row and it gets selected.

  • cellSetup()

    The cellSetup will be called once when the cell is first configured. Here you should set up your cell with its permanent settings.

  • cellUpdate()

    The cellUpdate will be called each time the cell appears on screen. Here you can change how the title and value of your row is set or change the appearance (colors, fonts, etc) depending on variables that might not be present at cell creation time.

  • onCellHighlight()

    The onCellHighlight will be invoked whenever the cell or any subview become the first responder.

  • onCellUnHighlight()

    The onCellUnHighlight will be invoked whenever the cell or any subview resign the first responder.

  • onExpandInlineRow()

    The onExpandInlineRow will be invoked before expand the inline row. This does only apply to the rows conforming to the InlineRowType protocol.

  • onCollapseInlineRow()

    The onCollapseInlineRow will be invoked before collapse the inline row. This does only apply to the rows conforming to the InlineRowType protocol.

  • onPresent()

    This method will be called by a row just before presenting another view controller. This does only apply to the rows conforming to the PresenterRowType protocol. You can use this to set up the presented controller.

Each row also has an initializer where you should set the basic attributes of the row.

Here is an example:

let row  = CheckRow("set_disabled") { // initializer
              $0.title = "Stop at disabled row"
              $0.value = self.navigationOptions?.contains(.StopDisabledRow)
           }.onChange { [weak self] row in
              if row.value ?? false {
                  self?.navigationOptions = self?.navigationOptions?.union(.StopDisabledRow)
              }
              else{
                  self?.navigationOptions = self?.navigationOptions?.subtract(.StopDisabledRow)
              }
           }.cellSetup { cell, row in
              cell.backgroundColor = .lightGrayColor()
           }.cellUpdate { cell, row in
              cell.textLabel?.font = .italicSystemFontOfSize(18.0)
           }

Now it would look like this:

Screenshot of Disabled Row

Section Header and Footer

The UITableView accepts two ways of setting the headers and footers for its sections, one is by using tableView(tableView: UITableView, viewForHeaderInSection section: Int) -> UIView? where you have to return a view and the other is tableView(tableView: UITableView, titleForHeaderInSection section: Int) -> String? where you return a String. Eureka works the same way, you can set a String or a view as header or footer for a Section.

The easiest way of setting a header or a footer is by setting them as a String. This can be done using the following Section initializers:

init(_ header: String, @noescape _ initializer: Section -> () = { _ in })
init(header: String, footer: String, @noescape _ initializer: Section -> () = { _ in })
init(footer: String, @noescape _ initializer: Section -> () = { _ in })

Using this you can instantiate a Section like Section("Title") or Section(header: "Title", footer: "Footnote") for example.

You can also set the header or footer using a custom view. This is best done by setting the header or footer variable of the section. This variables must conform the HeaderFooterViewRepresentable protocol. This can be done by using the HeaderFooterView class. An example follows:

Section() { section in
    var header = HeaderFooterView<MyHeaderNibFile>(.NibFile(name: "MyHeaderNibFile", bundle: nil))        
    header.onSetupView = { view, _, _ in
         // customize header
     }
    header.height = { 100 }

    section.header = header
}

The HeaderFooterView is a StringLiteralConvertible and requires a String or a HeaderFooterProvider that will generate the view to show. There are 3 ways a HeaderFooterProvider can create a view: from a nibfile (like in the example), from a class (it will just instantiate that class) or from a block (you can pass a block to the HeaderFooterProvider that returns the view).

public enum HeaderFooterProvider<ViewType: UIView> {
    case Class
    case Callback(()->ViewType)
    case NibFile(name: String, bundle: NSBundle?)
}

How to dynamically hide and show rows (or sections)

Many forms have conditional rows, I mean rows that might appear on screen depending on the values of other rows. You might want to have a SegmentedRow at the top of your screen and depending on the chosen value ask different questions:

Screenshot of Hidden Rows
In this case we are hiding and showing whole sections

To accomplish this each row has an hidden variable that is of optional type Condition.

public enum Condition {
    case Predicate(NSPredicate)
    case Function([String], (Form?)->Bool)
}

The hidden variable might be set with a function that takes the form the row belongs to and returns a Bool that indicates whether the row should be hidden or not. This is the most powerful way of setting up this variable as there are no explicit limitations as to what can be done in the function.

Along with the function you have to pass an array with all the tags of the rows this row depends on. This is important so that Eureka can reevaluate the function each time a value changes that may change the result of this function. In fact that will be the only time the function is reevaluated. You can define it like this:


<<< AlertRow<Emoji>("tag1") {
        $0.title = "AlertRow"
        $0.optionTitle = "Who is there?"
        $0.options = [

Related Repositories

eureka-js-client

eureka-js-client

JS implementation of a client for Eureka (https://github.com/Netflix/eureka), th ...

Eureka-ROM

Eureka-ROM

These are the source files for Team Eureka's Chromecast ROM ...

Eureka-Panel

Eureka-Panel

A CGI based Web Portal application for configuring Eureka-ROM ...

eureka-client

eureka-client

A Clojure client for Netflix Eureka service discovery servers ...


Top Contributors

mtnbarreto mats-claassen dernster HiromichiYamada ffittschen m-revetria yuuki1224 mikaoj creister colinmorelli davidrothera jasonnam zenkimoto pedrovereza rlaferla dalbin estebansotoara jechol sotozaki

Releases

-   1.3.1 zip tar
-   1.3.0 zip tar
-   1.2.0 zip tar
-   1.1.0 zip tar
-   1.0.0 zip tar