Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/stevestreza/Relayout

Swift microframework for declaring Auto Layout constraints functionally
https://github.com/stevestreza/Relayout

Last synced: 8 days ago
JSON representation

Swift microframework for declaring Auto Layout constraints functionally

Awesome Lists containing this project

README 

        
Relayout

========



.. image:: video.png

   :target: https://www.youtube.com/watch?v=lPMfXD6NMrs



.. image:: https://img.shields.io/travis/stevestreza/Relayout/master.svg?maxAge=2592000

.. image:: https://camo.githubusercontent.com/3dc8a44a2c3f7ccd5418008d1295aae48466c141/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f43617274686167652d636f6d70617469626c652d3442433531442e7376673f7374796c653d666c6174

.. image:: https://img.shields.io/cocoapods/v/Relayout.svg?maxAge=2592000

.. image:: https://img.shields.io/cocoapods/l/Relayout.svg

.. image:: https://img.shields.io/cocoapods/p/Relayout.svg?maxAge=2592000

.. image:: https://img.shields.io/cocoapods/metrics/doc-percent/Relayout.svg?maxAge=2592000



Relayout is a Swift microframework to make using Auto Layout easier with static and dynamic layouts.



Why?

====



If you want to build a UI using Apple's UI frameworks today, you have three good options. You can use Auto Layout in Interface Builder, you can use Auto Layout in code and maintain references to those constraints, or you can implement a layout function with `layoutSubviews`:code:. Each of these approaches has pros and cons.



- If you layout manually with `layoutSubviews`:code:, you're usually doing the job of Auto Layout - describing the layout of UI elements. But instead of doing it with objects to describe those relationships, you end up describing it with mathematical equations. This can be the most explicit and least error prone, but can be difficult to read and understand later. You also don't pick up features like right-to-left language support. But you get the benefit of having a single method that handles all your layout, regardless of why a layout changed. 

- If you use Auto Layout in Interface Builder, you can end up with inconsistencies in your actual layout vs what Interface Builder creates, as it tries to magically fix issues with your layout. It can also be difficult to change those constraints later, either at runtime, or when you need to add a new feature. However, if you need a simple UI that doesn't change much, it can be an effective and quick way to get the job done.

- If you use Auto Layout in code, you get the benefits of the higher level abstraction and improved code readability. And this can be a good approach if you don't need dynamism in your UI. But if you need to be able to change the UI at runtime, you have to hold on to references to individual constraints, add and remove constraints, and hope you don't see the dreaded "Unable to simultaneously satisfy constraints" warning.



The fundamental problem behind making dynamic layouts is *state transformations*. Going from 1 state to 2 is easy (add 2 transformations, A -> B and B -> A). Going from 2 to 3 is still fairly easy (add 4 transformations, B -> C, A -> C, C -> B, and C -> A). But as you add more and more states, you end up doubling the number of transformations you need to account for, all while fully satisfying the constraint system. This exponential growth is unsustainable, especially when you don't really care about the transformations as much as the states themselves.



Wouldn't it be great if we could cherry pick some of the most useful properties of the approaches? Auto Layout is a very good tool because of how descriptive it is, and we should use it, but not in its current form. Let's take a page from React.js and define a function that returns a pile of constraints that we want for a given UI state. 



You could define a single object that generates a pile of constraints for your view. Any time anything happens that could possibly change those constraints, throw the old ones out and generate a new set of constraints. That's what Relayout is.



Since the goal of Relayout is to make it easier to use Auto Layout, it tries to have a minimal impact on your app. You can use it in a view controller or within individual views. You can use it for parts of your app, and not use it elsewhere. You can compose layouts together and control them conditionally based on behaviors like `UITraitCollection`:code: state. Whatever you want to do.



What It Is Not

--------------



Relayout is not a tool for creating constraints. That's up to you. Want to use the `NSLayoutConstraint`:code: visual formatting language? The iOS 9+ anchor APIs? A third-party library like PureLayout? As long as it returns `NSLayoutConstraint`:code: objects, Relayout can use them. But we're not going to be opinionated about how you create them, or whether they come pre-activated or not. 



Relayout is also not an alternative or replacement to Auto Layout, but rather an augmentation. It **requires** the use of Auto Layout, and that means the rules that come along with it. So if you hate Auto Layout and don't want to use it, then Relayout may not be for you (though you may find that the reasons you hate Auto Layout no longer exist when using Relayout!).



Relayout is also not the definitive implementation of a functional layout. It's an idea, that having a function that generates a list of constraints is a good way to build UI. It's a set of objects that implement that idea. Feel free to take this idea, and build on it, to help make it easier to build and scale UIs.



Finally, Relayout is not a great tool to use in conjunction with Interface Builder. Both Interface Builder and Relayout want you to supply a complete set of constraints to fully describe a UI. Trying to get those two to play nicely is a fight neither you nor I want to solve.



Installing

==========



Relayout supports iOS 8.0+, tvOS 9.0+, and OS X 10.10+. You can install Relayout with Carthage, CocoaPods, or manually.



With CocoaPods

--------------



Add the following to your `Podfile`:code:. ::



   pod 'Relayout', '~> 1.1'



With Carthage

-------------



Add the following to your `Cartfile`:code:. ::



   github "stevestreza/Relayout" ~> 1.1



Manually

--------



`Relayout.xcodeproj`:code: creates a `Relayout.framework`, so you can include the framework as an Xcode target dependency, and copy/link it into your app. Alternatively, you can include the source files from the Framework target as you see fit.



Swift 3

-------



When Swift 3 lands the project will be immediately updated to support it with a major update to the version number (e.g. version `2.0.0`:code:).



Usage

=====



You can use Relayout from within both views and view controllers. To take advantage of it, you will need a `ViewLayout`:code: object. Create one with a root view (such as the view controller's view, the table cell's content view, or the view itself). You will also need to give it an object that conforms to the `LayingOut`:code: protocol. This protocol is very simple and has one method which takes your root view and returns an `Array`:code:, which represents the list of constraints that you want applied.



Once you have a `ViewLayout`:code: object, you'll want to call its `layout()`:code: method anywhere that might trigger a layout. Places where that may happen include `updateConstraints`:code:, `setFrame`:code:, `traitCollectionDidChange`:code:, and any place where your UI's state changes.



The simplest way to return constraints is to use the `Layout`:code: object, which accepts either an `Array`:code: to pass through directly, or a closure that takes your root view and returns the `Array`:code: to apply to it.



Relayout was designed to be composable, meaning that the `Layout`:code: object is one building block to use to build powerful and flexible layouts. There are a number of implementations of the `LayingOut`:code: protocol, either existing or planned. So far you can use:



- `LayoutGroup`:code:, which returns all of the `NSLayoutConstraint`:code: objects provided by an `Array`:code: object

- `IdentifyingLayout`:code:, which adds an identifier to all `NSLayoutConstraint`:code: objects for a given `LayingOut`:code: object (which is useful for debugging unsatisfiable constraint errors)

- `ConditionalLayout`:code:, which returns the `NSLayoutConstraint`:code: objects from a given `LayingOut`:code: object if the condition is true, and optionally return other `NSLayoutConstraint`:code: objects if the condition is false

- `TraitCollectionLayout`:code:, which returns the `NSLayoutConstraint`:code: objects from a given `LayingOut`:code: object iff the root view has certain `UITraitCollection`:code: traits

- `ListLayout`:code:, which iterates over a list of objects, calling a closure that returns `NSLayoutConstraint`:code: objects when passed the object, its index, and the previous and next objects in the list (to easily constrain between an object and its next and previous views).



And you can of course implement the `LayingOut`:code: protocol if you see fit. It has no `Self`:code: requirement, so you can use them interchangeably anywhere.