Eureka Tutorial – Start Building Easy iOS Forms

Eureka is a powerful library that allows developers to rapidly create form interfaces for user input.

This Eureka tutorial will teach you how to use Eureka’s essential building blocks by crafting the interface of a simple to-do app called EurekaToDo. You’ll see how Eureka makes it easy to set up various commonly-used user interface elements such as date pickers, text fields and segmented controls with no boilerplate UIKit code!

In addition:

• Eureka’s components are very flexible and extensible out-of-the-box and cover the majority of use cases. Eureka makes it easy to implement your custom components if your needs get more specific. Examples of community-generated plugins include a GooglePlacesRow and an ImageRow, which you’ll get to use in this Eureka tutorial.
• Eureka is a well-documented library with plenty of helpful tips and examples available through its official Github portal.

Getting Started

Download the starter project for EurekaToDo, the to-do list app you’ll be working with for this Eureka tutorial.

In addition to basic view controller transitions, the starter project includes the app’s model and view model layers. Open EurekaToDo.xcworkspace and take a few minutes to browse the project. Here’s a quick overview of important classes:

• ToDoListViewController: Manages the list of to-do items presented to the user.
• ToDoListViewModel: The presentation logic for ToDoListViewController.
• EditToDoItemViewController: Enables the user to add and edit to-do items — it currently doesn’t do much. All the work for this Eureka tutorial will be in this file.
• EditToDoItemViewModel: The presentation logic supporting EditToDoItemViewController.

You’ll notice the project doesn’t use a storyboard. While Eureka can leverage nib files for custom views, you’ll be amazed by how easy it is to programmatically create and customize common controls.

Note: For this Eureka tutorial, you will be passing values to and from a view model and not the model directly. Although Eureka does not require the use of the Model-View-ViewModel (MVVM) paradigm, MVVM encourages a cleaner, more testable app architecture. For this Eureka tutorial, the view model may be thought of as directly substituting for the app’s model. See the Further Reading section for more on this topic.

Build and run the application. You’ll see a to-do list pre-populated with a single item. Tapping the item takes you to a blank screen (controlled by EditToDoItemViewController) with Back and Save navigation items. Tap the Back button in the top left to return to the to-do list.

The edit screen currently leaves a lot to be desired. You probably recall EditToDoItemViewController didn’t have much in it. This is where you come in! By the time you’re done, the final project’s interface will look like the picture below:

Adding Eureka to our View Controller

Open EditToDoItemViewController.swift and replace the current import and class declaration with the following:

import Eureka
import UIKit

class EditToDoItemViewController: FormViewController {

Note: You may need to build the project if the Cocoapod module is not immediately visible to your project.

You’ve imported the Eureka framework and changed the superclass to be FormViewController.

FormViewController is a UIViewController subclass provided with Eureka. It includes a form property, which is an instance of Eureka’s Form class. The Form class is an abstraction of the UITableView object into which you’ll be adding various user interface elements.

A Form instance may contain one or more Section objects. Each section, in turn, may contain one or more Row objects. As you may have guessed from their names, these properties correspond to the sections and rows of the UITableView. Eureka’s Form, Section and Row abstractions provide some very powerful and flexible functionality.

Adding a Section and a Row

In order to add rows to a form, you will first need a Section object to contain them.

You’ll use Eureka’s custom +++ operator to add a Section to the form, and the <<< operator to add rows to a section. Add the following to viewDidLoad(), just beneath the call to super:

//1
form
  +++ Section()	//2
  <<< TextRow() { // 3
    $0.title = "Description" //4
    $0.placeholder = "e.g. Pick up my laundry" 
    $0.value = viewModel.title //5
    $0.onChange { [unowned self] row in //6
      self.viewModel.title = row.value
    }
}

Here's a look at what this code does:

1. Acts on the form object provided by FormViewControler.
2. Instantiates and adds a Section to the form using Eureka's +++ operator.
3. Adds a TextRow to the section. As you'd expect, this is a row that will contain some text. The initializer accepts a closure used to customize the row's appearance and events.
4. Adds a title and placeholder text to the textfield. The title is a left-justified label and the placeholder appears on the right until a value is added.
5. This sets the initial value of the row to show the to-do item's title.
6. Eureka's Row superclass comes with a host of callbacks that correspond to various interaction and view lifecycle events. The onChange(_ :) closure is triggered when the row's value property changes. When a change happens, this updates the viewModel's title property to the row's current value.

Build and run the application. When you tap the lone to-do item in the list, the EditToDoItemViewController screen should now look like the picture below. On the edit screen, tap the item, update the text and then Save. The model object updates with your form input!

In only 10 lines of code, you displayed a model-driven textfield in a tableview.

Now that you have an idea of how Eureka works, time to add some other elements!

Setting the Due Date with a Date Picker

Every to-do list needs to have due dates. Fortunately, Eureka has a row type that displays a date picker when tapped. Add the following to the bottom of viewDidLoad():

+++ Section()	
  <<< DateTimeRow() { 
    $0.dateFormatter = type(of: self).dateFormatter //1
    $0.title = "Due date" //2
    $0.value = viewModel.dueDate //3
    $0.minimumDate = Date() //4
    $0.onChange { [unowned self] row in //5
      if let date = row.value {
        self.viewModel.dueDate = date
      }
    }
  }

You've added another Section, this time with a DateTimeRow to display the picker. Here's a deeper look at how it's configured:

provided in the starter project.

1. To format the presentation of the date, set the row's dateFormatter to the static dateFormatter

provided in the starter project.

2. Most Eureka Row subclasses allow you to set their title property to make the purpose of the row clear to the user.
3. When the row is initially configured, set its value to the view model's due date.
4. Use today's date as the minimum date that can be accepted as user input.
5. Set the newly-selected date to the view model when onChange is triggered.

Build and run the project to confirm the new row is in its own section right below the item title. Tap the row, and a date picker will appear at the bottom of the screen. Note that you can't select a date prior to the present day.