Fields on A+ programming moments

Modeling form field

Tue, 17 Sep 2019 09:40:00 +0000

Let’s go back to example from previous intro post – regular one-line text field.

First, let’s build a simple FieldCell subclass, which contains UILabel for the title and UITextField for the value.

final class TextFieldCell: FieldCell {
	//	UI
	@IBOutlet private var titleLabel: UILabel!
	@IBOutlet private var textField: UITextField!
}

Nothing unusual here: both controls are private for the cell, as they should be.

Now, let’s build a (view)model object to supply the required values. First, we need a unique ID for this field:

/// Model that corresponds to TextFieldCell instance.
class TextFieldModel: FieldModel {
	///	unique identifier (across the containing form) for this field
	let id: String
}

Next, we need few strings that corresponds to values shown in label and text field:

///	String to display in the title label
var title: String?

///	Value to show inside the textField
var value: String?

///	Placeholder value to show inside the textField
var placeholder: String?

Notice that value is plain String. Your form data source object, whatever that may be, is responsible to convert application’s model objects into TextFieldModel.

Now comes the fun part. Text field can be used to input unlimited variety of values: username, password, street name, email, city name, phone number, card number…anything, really. Some of these uses require custom configurations.

For passwords, you need to setup the UITextField to be secure text field.
For the iOS’ password auto-fill feature, you need to set textContentType to .password (similar for username).
If you are inputting phone numbers, you should set keyboardType to .phonePad.
Similar for email fields. On and on.

There’s an ever increasing array of possible configuration options. Making a model property for each one is fool’s errand. Instead, let’s expose the UITextField through custom closure:

///	Custom configuration for the textField.
///
///	Default implementation does nothing.
var customSetup: (UITextField) -> Void = {_ in}

This way, the model stays really clean and endlessly expandable while the field itself is still private and encapsulated inside the TextFieldCell component. If you have custom config, supply the closure and it will be executed at the end of the cell.populate(_ model:TextFieldModel) method.

Finally, we need a way to receive the final edited value back. For that, we use the similar closure approach:

///	Method called when editing is done.
///
///	Default implementation does nothing.
var valueChanged: (String?, TextFieldCell) -> Void = {_, _ in}

This is the minimal setup for the field. You can expand this to whatever you want, depending on the cell design. Let’s say that you want to show some glyph icon that suggest when a particular cell is mandatory + each field has an icon in-front of it:

class TextFieldModel: FieldModel {
	...
	var isMandatory: Bool = false
	var icon: UImage
}

Now adjust the cell design to use these new properties and…done. There are really no design limits with this approach and there is nothing left unused; you adapt the Cell + Model for your intended design and then go on and just build your forms by creating instances of these model objects.

Ok, going back now to the cell. When it’s instantiated from its .xib file, first clean any contents (set in Interface Builder) and then process edited value when editing ends:

override func awakeFromNib() {
	super.awakeFromNib()
	cleanup()

	textField.addTarget(self, action: #selector(editText), for: .editingDidEnd)
	textField.addTarget(self, action: #selector(editText), for: .editingDidEndOnExit)
}

private	@objc func editText(_ sender: UITextField) {
	valueChanged(sender.text, self)
}

editText() method has to call model’s valueChanged() closure. In order to call it, we need to save it locally as the cell’s property. We do this in the same method that populates the cell:

func populate(with model: TextFieldModel) {
	valueChanged = model.valueChanged
	render(model)
}

private func render(_ model: TextFieldModel) {
	titleLabel.text = model.title
	textField.text = model.value
	textField.placeholder = model.placeholder
	model.customSetup( textField )
}

And that’s about it. The very same approach is applied to all other models, like ButtonModel, ToggleModel, TextViewModel etc. They are fairly self explanatory, I hope.

Not all fields are this straight-forward thus in next post I’ll look at the PickerCell and its model.

Trouble with form fields in iOS apps

Thu, 05 Sep 2019 14:22:00 +0000

Data models driving the forms are different from one app to another. Form designs tend to be different. Input methods change over time, accessibility is always looming as task you should not forget. On top of that, each app aims to distinguish itself from the pack and thus designers are aiming to infuse the input fields with some life and offer small wins for the end customer using them.

Such a variety and open goals are nightmare for developers. We love stuff that can be fully modeled, rendered using pre-defined rules. And we love to use and re-use existing code without much modifications.

All together, it makes the task of building declarative, easy-to-expand and free-to-augment form libraries next to impossible. iOS world is not lacking in attempts, some better than others.

Eureka has near 10k stars on GitHub. It has neat interactions and supports the largest variety of cells, including ability to add your own custom ones. But it uses a home grown syntax using custom Swift operators which increases learning curve. It has validations built-in which is conceptually wrong in light of my preferred application architecture — validations are defined by business rules, thus they should live in middleware, not UI. That’s a lot of features, which translates to huge dependency when introduced into your project.

Former has an advanced DSL of its own. You need to learn its template syntax in order to build a form. Plus it’s rather old now, layout is built purely in code using AutoLayout’s old visual syntax. Both of those are big turn-offs. However, it has really wide range of pre-built cells and excellent implementation of inline-field editing, including date pickers, multi-value pickers etc.

iZettle’s Form is another huge layout framework based on reactive programming concepts. Forms are just one part of it all; on first glance, I don’t think you can use just the Forms bit without the rest. A framework like this is really not my cup of tea but it deserves to be mentioned if you are into signals and observers.

SwiftForms is another attempt with rather weird approach to styling. It has custom selection handlers that you need to learn but other than that it’s fairly simple to pick up. Not much magic under the hood, which is a plus for me.

SwiftTalk duo built a very modern Form Library based on somewhat advanced usage of Swift generics. Code is rather hard to comprehend unless you are really proficient in Swift. I both like and don’t like how it can create multiple forms, spread out over multiple VCs, using one data-source (they call it state) declaration. Quite smart, if you are willing to extend it further and learn how it works internally so you can actually adapt it to your needs.

Lastly: all of these libraries are using table view cells. I know the reason; self-expanding layouts are quite easy to implement with table rows. It scrolls as much as needed and adapts to input methods. UITableViewController handles the keyboard appearance and scrolling stuff into view, for free.

I have built so many forms in last 5 years, I honestly believe it’s impossible to create a forms library that will work out of box if you care about design consistency across your app. I tried as well. There will always be the need to tweak and adjust, add custom information here and there. For every single library I tried or built, it turned out that I needed to adjust either its behavior or look&feel or both.

Plus, iOS screens are ever expanding and single-column forms may not be enough anymore. Even with single column, you may have some data which are looking better when shown side by side (state / post code / city of an address, for example).

Let’s look at the simplest possible form that you may need in any app: login, with just username and password.

You need something like TextFieldCell, populated using title and optional string value and be done with it. Simple, eh?

Here’s some challenges for you:

setup custom configuration like isSecure for the password field
show mandatory mark, only on some fields
show/hide per-field error messages / validation rules
add arbitrary textual or image hints above or below the form field
looks too bland — designers want to have the title labels appear over the field when no value is present but to appear like on the picture when value is set
when person activates the text field, that hovering label should slide upwards
it should also slide back if you activate and deactivate the field without entering value
what about cute icons? maybe in front of the field? maybe behind the field? maybe inside the field, before the text?

I could go on and on, just continue with design requests I had to handle in last 10 years or so. This is wild west territory. The amount of customization points for the model driving such display counts in dozens.

That’s just user/pass using one type of field; imagine what other model data can be shown in text fields: address parts, person names, phone numbers etc. Addresses have things like state/province, zip/post-codes and city names - which can be short (say Richmond, NY 12322) thus it makes sense to show them side-by-side instead of in separate rows. Etc.

That’s just a minor set of possible customizations related to field display. Getting values back and re-connecting them with your model objects is another set of challenges if you want to have a declarative way to setup the form.

I’ve come to believe the right approach is:

cover just the basics, don’t even attempt to model everything in advance
make the model truly expanding by not making any assumptions about the look and feel
build Cells’ look & feel on case-by-case basis then alter its corresponding Model to support it
base all of it on some variant of self-sizing UICollectionView(Flow)Layout

=> it can’t be neither a library nor framework.

You start with bare cell/model combination then adjust it to the design at hand. You then build each of your form data sources independently by transforming your actual model objects into TextFieldModel, ToggleModel etc. These are then used to populate their corresponding cells. While this inevitably leads to more work per form you will still be able to fairly quickly build any kind of form, with lots of easy copy/paste.

Over the last year or so, I was slowly building Fields which you can plow however you like (all puns intended). I gave up trying to make it perfect, gave up trying to handle all possible cases out of the box and just wanted to have a solid base to adapt for each and every form I have to build.

Thus the cell design is really, really simple – on purpose. I have field title and the field itself with corresponding value. There’s no hints, explanation, per-field error messages, mandatory glyphs or anything like it. I add them as I need them in each specific implementation. Plus, each field is designed in Interface Builder, making it easy to preview behavior when the cell, as container, is too small or too large. Lastly — entire form uses vertically self-sizing cells, thus you can put as much content inside as you want.

There’ll be more details in upcoming post(s).