AloeStackView

A simple class for laying out a collection of views with a convenient API, while leveraging the power of Auto Layout.

Introduction

AloeStackView is a class that allows a collection of views to be laid out in a vertical or horizontal list. In a broad sense, it is similar to UITableView, however its implementation is quite different and it makes a different set of trade-offs.

AloeStackView focuses first and foremost on making UI very quick, simple, and straightforward to implement. It does this in two ways:

• It leverages the power of Auto Layout to automatically update the UI when making changes to views.

• It forgoes some features of UITableView, such as view recycling, in order to achieve a much simpler and safer API.

We've found AloeStackView to be a useful piece of infrastructure and hope you find it useful too!

Table of Contents

• Features
• System Requirements
• Example App
• Usage
  • Creating an AloeStackView
  • Adding, Removing, and Managing Rows
  • Handling User Interaction
  • Dynamically Changing Row Content
  • Styling and Controlling Separators
  • Extending AloeStackView
  • When to use AloeStackView
• Installation
• Contributions
• Maintainers
• Contributors
• License
• Why is it called AloeStackView?

Features

• Allows you to keep strong references to views and dynamically change their properties, while Auto Layout automatically keeps the UI up-to-date.

• Allows views to be dynamically added, removed, hidden and shown, with optional animation.

• Includes built-in support for customizable separators between views.

• Provides an extensible API, allowing specialized features to be added without modifying AloeStackView itself.

• Widely used and vetted in a highly-trafficked iOS app.

• Small, easy-to-understand codebase (under 600 lines of code) with no external dependencies keeps binary size increase to a minimum and makes code contributions and debugging painless.

System Requirements

• Deployment target iOS 9.0+
• Xcode 10.0+
• Swift 4.0+

Example App

The repository includes a simple example iOS app.

You can try it out by cloning the repo, opening AloeStackViewExample.xcworkspace, and running the app.

The example app shows a few ways AloeStackView can be used to implement a screen in an iOS app.

Usage

Creating an AloeStackView

The primary API is accessed via the AloeStackView class.

You can create an instance of AloeStackView quite easily in your code:

import AloeStackView

let stackView = AloeStackView()

AloeStackView is a UIView (specifically a UIScrollView), and thus can be used in the same way as any other view in your app.

Alternatively, if you want to build an entire UIViewController using AloeStackView, you can use the convenient AloeStackViewController class:

import AloeStackView

public class MyViewController: AloeStackViewController {

  public override func viewDidLoad() {
    super.viewDidLoad()
    stackView.addRow(...)
  }

}

AloeStackViewController is very similar to classes such as UITableViewController and UICollectionViewController in that it creates and manages an AloeStackView for you. You can access the AloeStackView via the stackView property. Using AloeStackViewController rather than creating your own AloeStackView inside a UIViewController simply saves you some typing.

Adding, Removing, and Managing Rows

The API of AloeStackView generally deals with "rows". A row can be any UIView that you want to use in your UI.

By default, rows are arranged in a vertical column, and each row stretches the full width of the AloeStackView.

The axis property on AloeStackView can be used to change the orientation. When axis is set to .horizontal, rows are arranged next to each other, left-to-right, and the AloeStackView scrolls horizontally, with each row stretching the full height of the AloeStackView.

To build a UI with AloeStackView, you generally begin by adding the rows that make up your UI:

for i in 1...3 {
  let label = UILabel()
  label.text = "Label \(i)"
  stackView.addRow(label)
}

If the length of an AloeStackView ever grows too long for the available screen space, the content automatically becomes scrollable.

AloeStackView provides a comprehensive set of methods for managing rows, including inserting rows at the beginning and end, inserting rows above or below other rows, hiding and showing rows, removing rows, and retrieving rows.

You can customize the spacing around a row with the rowInset property, and the setInset(forRow:) and setInset(forRows:) methods.

The class documentation in AloeStackView.swift provides full details of all the APIs available.

Handling User Interaction

AloeStackView provides support for handling tap gestures on a row:

stackView.setTapHandler(
  forRow: label,
  handler: { [weak self] label in
    self?.showAlert(title: "Row Tapped", message: "Tapped on: \(label.text ?? "")")
  })

label.isUserInteractionEnabled = true

A tap handler will only fire if isUserInteractionEnabled is true for a row.

Another way of handling tap gestures is to conform to the Tappable protocol:

public class ToggleLabel: UILabel, Tappable {

  public func didTapView() {
    textColor = textColor == .red ? .black : .red
  }

}

for i in 1...3 {
  let label = ToggleLabel()
  label.text = "Label \(i)"
  label.isUserInteractionEnabled = true
  stackView.addRow(label)
}

Conforming to Tappable allows common tap gesture handling behavior to be encapsulated inside a view. This way you can reuse a view in an AloeStackView many times, without writing the same tap gesture handling code each time.

Dynamically Changing Row Content

One of the advantages of using AloeStackView is that you can keep a strong reference to a view even after you've added it to an AloeStackView.

If you change a property of a view that affects the layout of the overall UI, AloeStackView will automatically relayout all of its rows:

stackView.setTapHandler(forRow: label, handler: { label in
  label.text = (label.text ?? "") + "\n\nSome more text!"
})

As you can see, there's no need to notify AloeStackView before or after making changes to a view. Auto Layout will ensure that the UI remains in an up-to-date state.

Styling and Controlling Separators

AloeStackView adds separators between rows by default:

Turning Separators On and Off

You can easily hide separators for any rows that are added to an AloeStackView:

stackView.hidesSeparatorsByDefault = true

The hidesSeparatorsByDefault property only applies to new rows that are added. Rows already in the AloeStackView won't be affected.

You can hide or show separators for existing rows with the hideSeparator(forRow:), hideSeparators(forRows:), showSeparator(forRow:), and showSeparators(forRows:) methods.

AloeStackView also provides a convenient property to automatically hide the last separator:

stackView.automaticallyHidesLastSeparator = true

Customizing Separators

You can change the spacing on the left and right of separators:

stackView.separatorInset = .zero

In vertical orientation, only the left and right properties of separatorInset are used.

In horizontal orientation, separators are displayed vertically between rows. In this case, only the top and bottom properties of separatorInset are used, and they control the spacing on the top and bottom of separators.

As with hidesSeparatorsByDefault, the separatorInset property only applies to new rows that are added. Rows already in the AloeStackView won't be affected.

You can change the separator inset for existing rows with the setSeparatorInset(forRow:) and setSeparatorInset(forRows:) methods.

AloeStackView also provides properties for customizing the color and width (or thickness) of separators:

stackView.separatorColor = .blue
stackView.separatorWidth = 2

These properties affect all of the separators in the AloeStackView.

Extending AloeStackView

AloeStackView is an open class, so it's easy to subclass to add custom functionality without changing the original source code. Additionally, AloeStackView provides two methods that can be used to further extend its capabilities.

configureCell(_:)

Every row in an AloeStackView is wrapped in a UIView subclass called StackViewCell. This view is used for