wangshengjia / leego

Declarative, configurable & highly reusable UI development as making Lego bricks.

LeeGo is a lightweight Swift framework that helps you decouple & modularise your UI component into small pieces of LEGO style's bricks, to make UI development declarative, configurable and highly reusable.

Rational behind

We all know that MVC pattern has some serious problems when dealing with a complex iOS project. Fortunately there are also a bunch of approaches that aim to fix the problems, most of them mainly address the Controller part, such as MVP, MVVM, MVSM or VIPER. But there is barely a thing which addresses the View part. Does that mean we just run out of all the problems in the View part ? I think the answer is NO, especially when we need our app to be fully responsive.

I’ve talked this idea on a dotSwift’s talk, and also on my blog posts:

• Build UI without UIView
• Put your whole UI into struct & enum with LeeGo

Please checkout through for more details.

LeeGo, replaces the View part of MVC by Brick.

Features

What may LeeGo helps you:

• Describe your whole UI in small pieces of Lego style’s bricks. Let you configure your view as a brick whenever & wherever you want.
• No longer need to deal with a bunch of custom UIView’s subclasses. Instead, you only need to deal with different Bricks which is lightweight and pure value type.
• Designed to be UIKit friendly and non-intrusive. There is no need to inherit from other base class at all.
• Capable to update remotely almost everything via your JSON payload.
• Built-in convenience methods to make UIStackView like layout hassle-free.
• Built-in self-sizing mechanism to calculate cell’s height automatically.
• Method chaining syntax sugar.
• Benefits from Swift’s enum, let you put the whole UI in a single enum file.

Compare with Facebook ComponentKit

Both:

• Brings declarative, configurable & reusable UI development for iOS.

Pros:

• Written in Swift, built for Swift. No more Obj-C++ stuff.
• Lightweight and UIKit friendly. No inheritance, dealing with standard UIView and Auto Layout directly.
• Totally smooth to begin with integrating only a small part, also free to drop all without any side effect.
• Possible to update any part of UI which powered by LeeGo remotely via JSON payload.
• Powered by standard auto layout which you probably familiar with already.

Cons:

• Lack of high level features for the moment. Such as support of built-in configurable view controller, view animation, auto layout animation or UIControl component’s action.
• Powered by standard auto layout which may have some potential performance issues in some circumstances.
• Still requires the basic knowledge of standard auto layout and Visual Format Language.

Full Documentation

• Full Documentation
• Native UI powered by server side
• Configurable appearance
• Built-in convenience methods for layout
• Dynamic cell height

Usages

Basic bricks

Create a Brick instance which named "title" as UILabel, with default text "Showcase" and gray background color

import LeeGo

let titleBrick: Brick = "title".build(UILabel).style([.text("Showcase"), .backgroundColor(.lightGrayColor())])

Configure an UILabel instance just as title brick

let titleLabel = UILabel()
titleLabel.lg_configureAs(titleBrick)

#### More complex bricks Create the bricks inside a cell brick

let titleBrick = "title".build(UILabel).style([.numberOfLines(0), .text("title")])
let subtitleBrick = "subtitle".build(UILabel).style([.textColor(.lightGrayColor()), .numberOfLines(0), .font(.systemFontOfSize(14)), .text("subtitle")])
let imageBrick = "image".build(UIImageView).style([.ratio(1.5), .backgroundColor(.blueColor())]).width(68)

/// Create a brick stand for `UIView` which contains a `title`,
/// a `subtitle` and an `image` inside, layout them with
/// standard auto layout VFL.
let brickName = "cell"
let cellBrick = brickName.build().bricks(titleBrick, subtitleBrick, imageBrick) {
	title, subtitle, image in
	return Layout([
			"H:|-left-[\(image)]-spaceH-[\(title)]-right-|",
			"H:[\(image)]-spaceH-[\(subtitle)]-right-|",
			"V:|-top-[\(title)]-spaceV-[\(subtitle)]-(>=bottom)-|",
			"V:|-top-[\(image)]-(>=bottom)-|"], metrics: LayoutMetrics(20, 20, 20, 20, 10, 10))
}

Dequeue a standard UICollectionViewCell instance, then configure it as cell brick with element as data source

let cell = collectionView.dequeueCell…
cell.lg_configureAs(cellBrick, dataSource: element[indexPath.item])

UIStackView inspired layout

Create a brick stand for UIView which contains the 3 bricks (red, green & blue block), then lay them out with the UIStackView inspired layout helper method.

let bricks = ["red".build().style(Style.redBlockStyle).height(50),
 "green".build().style(Style.greenBlockStyle).height(80),
 "blue".build().style(Style.blueBlockStyle).height(30)]

let layout = Layout(bricks: bricks, axis: .Horizontal, align: .Top, distribution: .FillEqually, metrics: LayoutMetrics(10, 10, 10, 10, 10, 10))
let viewBrick = "view".build().style(Style.blocksStyle).bricks(bricks, layout: layout).height(100)

Configure a UIView instance just as the brick

view.lg_configureAs(viewBrick)

#### Union different bricks Union different bricks to a new brick with `UIStackView` style’s layout.

let viewBrick = Brick.union("brickName", bricks: [
		            title,
		            subtitle,
		            Brick.union("blocks", bricks: [
		                redBlock.height(50),
		                greenBlock.height(80),
		                blueBlock.height(30)], axis: .Horizontal, align: .Top, distribution: .FillEqually, metrics: LayoutMetrics(10, 10, 10, 10, 10, 10)).style([.backgroundColor(.yellowColor())])
		            ], axis: .Vertical, align: .Fill, distribution: .Flow(3), metrics: LayoutMetrics(20, 20, 20, 20, 10, 10))
                

Configure a UIView instance just as the brick

view.lg_configureAs(viewBrick)

#### More complex brick and build with an enum An enum which implements `BrickBuilderType`, used to centralize all `brick` designs in a single enum file.

import LeeGo

enum TwitterBrickSet: BrickBuilderType {
    // leaf bricks
    case username, account, avatar, tweetText, tweetImage, date, replyButton, retweetButton, retweetCount, likeButton, likeCount
    
    // complex bricks
    case retweetView, likeView
    case accountHeader, toolbarFooter, retweetHeader
    
    // root bricks
    case standardTweet

    static let brickClass: [Twitter: AnyClass] = [username: UILabel.self, account: UILabel.self, avatar: UIImageView.self, tweetText: UITextView.self]
    
    func brick() -> Brick {
        switch self {
        case .username:
            return build().style([.font(.boldSystemFontOfSize(14))])
        case .account:
            return build().style([.font(.systemFontOfSize(14))])
        case .avatar:
            return build().style([.ratio(1), .backgroundColor(.lightGrayColor()), .cornerRadius(3)]).width(50)
        case .tweetText:
            return build().style([.scrollEnabled(false)])
        …
        case .standardTweet:
            return build().style([.backgroundColor(.whiteColor())])
                .bricks(
                    avatar.brick(),
                    accountHeader.brick(),
                    tweetText.brick(),
                    tweetImage.brick(),
                    toolbarFooter.brick()
                ) { (avatar, accountHeader, tweetText, image, toolbarFooter) in
                    Layout(["H:|-10-[\(avatar)]-10-[\(tweetText)]-10-|",
                        "H:[\(avatar)]-10-[\(accountHeader)]-10-|",
                        "H:[\(avatar)]-10-[\(image)]-10-|",
                        "H:[\(avatar)]-10-[\(toolbarFooter)]-10-|",
                        "V:|-10-[\(avatar)]-(>=10)-|",
                        "V:|-10-[\(accountHeader)]-10-[\(tweetText)]-10-[\(image)]-10-[\(toolbarFooter)]-(>=10)-|"])
            }
        }
    }
}

/// Configure your cell
let cell = collectionView.dequeueCell…
cell.lg_configureAs(TwitterBrickSet.standardTweet.brick(), dataSource: element[indexPath.item])

## Update UI remotely `Brick` is designed to be JSON convertible, which makes possible that you can control your app’s interface, from tweak some UIKit appearances to create view/cell with brand new design **remotely** via JSON payload. Please check out ["JSON encodable & decodable"](Docs/Remote.md) for more details.

Best practices

For best practices and more design details, please checkout more design details

Installation

CocoaPods

LeeGo is available through CocoaPods. To install it, simply add the following line to your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

pod "LeeGo"

Carthage

To integrate LeeGo into your Xcode project using Carthage, specify it in your Cartfile:

github "wangshengjia/LeeGo"

Then, run the following command to build the LeeGo framework:

$ carthage update

At last, you need to set up your Xcode project manually to add the LeeGo framework.

Contributing

If you like LeeGo and willing to make it better, you are more than welcomed to send pull request for:

• Proposing new features.
• Answering questions on issues.
• Improving documentation.
• Reviewing pull requests.
• Finding, reporting or fixing bugs.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by [its terms](Docs/Code of Conduct.md).

Well...

If you have any thing want to tell me, please ping me on Twitter, on Weibo or just fire the issue.

I'd like to thank every one who helped me, inspired me and encouraged me. Also thank to my team at Le Monde, especially Vincent & Blaise.

Enjoy~ 🎉 🎉 🍻 🍻

leego's Issues

Handle cell's auto calculating height in a better way

• Handle better manual calculating height API
• Support both UITableView & UICollectionView
• Height cache mechanism

Are the explicit types in the README there deliberately?

eg.

import LeeGo

let titleBrick: Brick = "title".build(UILabel).style([.text("Showcase"), .backgroundColor(UIColor.lightGrayColor())])

could become

import LeeGo

let titleBrick: Brick = "title".build(UILabel).style([.text("Showcase"), .backgroundColor(.lightGrayColor())])

and

let bricks = ["red".build().style(Style.redBlockStyle).height(50),
 "green".build().style(Style.greenBlockStyle).height(80),
 "blue".build().style(Style.blueBlockStyle).height(30)]

let layout = Layout(bricks: bricks, axis: .Horizontal, align: .Top, distribution: .FillEqually, metrics: LayoutMetrics(10, 10, 10, 10, 10, 10))
let viewBrick = "view".build().style(Style.blocksStyle).bricks(bricks, layout: layout).height(100)

could become

let bricks = ["red".build().style(.redBlockStyle).height(50),
 "green".build().style(.greenBlockStyle).height(80),
 "blue".build().style(.blueBlockStyle).height(30)]

let layout = Layout(bricks: bricks, axis: .Horizontal, align: .Top, distribution: .FillEqually, metrics: LayoutMetrics(10, 10, 10, 10, 10, 10))
let viewBrick = "view".build().style(.blocksStyle).bricks(bricks, layout: layout).height(100)

But I understand if this was done intentionally; it is clearer and more easily readable (?) in the examples.

If this wasn't done deliberately, I'd gladly help using implicit type inference. :)

Handle better when dealing with UIScrollView

All value type object or model objects should conform Equatable & Printable

Compatible with Cocoapods & Carthage

Component configuration need a default value

Brick.bricks is not publicly accessible

It would be nice to iterate over the child bricks like so:

  func update(_ targetView: UIView, with brick: Brick) {
        for child in brick.bricks {
            switch targetView {
            case let label as UILabel where brick == FooBrickBuilder.name:
                label.text = name
            case let label as UILabel where brick == FooBrickBuilder.address:
                label.text = address
            default:
                break
            }
        }
    }

Component Action

Hi Wang,

Congrats on the great tool, nicely done !! I was wondering what's your plan for providing actions for components, like Button, swipe, tap, or anything? Blockable actions?

Fix NSAttributedString bug

LeeGo on Swift 3.0

Should be able to init from custom initializer ?

Built-in components, layouts or some kind of `Theme`

• UIStackview like layout
• Separator: 0.5pt line with color
• Sticky header view

Mixed view components

Hello Wang,

Nice work there, congrats! I was playing around w/ Leego for some time and wondering what's the best approach to integrate e.g. UICollectionView inside table view cell (for carousal) and may be some dynamic image carousals mixed w/ static cells.

Need to remove old style when apply diff style

Already begin, need to be finished

Build with CI

TravisCI, CircleCI or Codecov.io

Refactor Layout to use declarative NSLayoutAnchor

With the NSLayoutAnchor, we can now use it to avoid the layout format language. Imagine, in your function that defines layout, we could pass the view and return an array of objects. Like this:

let title = "title".build(UILabel.self).style([.numberOfLines(0), .text("test")])
let subtitle = "subtitle".build(UILabel.self).style([.numberOfLines(0), .text("subtitle")])

let brick = "details".build().bricks(title) { container, title in
    return [
        title.centerXAnchor.constraint(equalTo: container.centerXAnchor),
        title.centerYAnchor.constraint(equalTo: container.centerYAnchor),
    ]
}

However, this approach will require some refactoring. I can volunteer, if you want :)

Need a way to handle component's action

Manipulate components and layout in a functional way

components.map { component1, component2 in
  // manipulate styles
 }.reduce {
  // reduce to single component with layout
}.compose { 
  // ... 
}.bind {}

Support Behaviours ?

http://objc.io/issues/13-architecture/behaviors/

Handle UIScrollView with auto layout

https://developer.apple.com/library/ios/technotes/tn2154/_index.html

Sample project, show the suit case and potential power of LeeGo

Le Monde, Twitter, NYT, Airbnb, LinkedIn, Weibo, Zhihu

Apply configuration with only diff part

Need a way to find diff parts between two configurations. How to deal with auto layout?

Need a way to alternatively calculate cell's height or whole layout manually to get better performance

Need to rename some objects

Ex: ComponentTarget or Configuration ??

Add unit tests

Handle custom errors

LeeGo on Swift 2.3

Move LeeGo to adapt Swift 2.3

Add prefix to all extension methods which based on NSObject

Need to be thread safe ?

Best way to handle responsive configuration

Add Z index to component ?

Code Coverage 85%+

Add UIStackView inspired convenience methods

Such as arrangedComponents(components: [Component], flowDirection: Direction)

Support view style with layer properties

ex: cornerRadius, borderWidth, borderColor, etc ...

Handle custom init

ex: UIButton(type: .Custom)

Brick.bricks field shares ambiguous name with methods.

In Xcode 9.4.1 (Swift 4.1.2) if you try to get the child bricks for a Brick instance, the compiler complains: Ambiguous reference to member 'bricks(_:layout:)'

Example (using code from DetailsViewController in the Demo App):

let title = "title".build(UILabel.self).style([.numberOfLines(0), .text("Lorem Ipsum is simply dummy text of the printing industry")])
let description = "description".build(UILabel.self).style([.textColor(UIColor.lightGray), .numberOfLines(0), .font(UIFont.systemFont(ofSize: 14)), .text("Lorem Ipsum has been the industry's standard dummy text ever since the 1500s")])
let redBlock = "red".build().style(Style.redBlockStyle)
let greenBlock = "green".build().style(Style.greenBlockStyle)
let blueBlock = "blue".build(UIImageView.self).style(Style.blueBlockStyle + [Appearance.custom(["shadowColor": UIColor.brown, "shadowOpacity": Float(1.0)])])

let blocks = Brick.union("blocks", bricks: [
    redBlock.height(50),
    greenBlock.height(80),
    blueBlock.height(30)],
    axis: .horizontal, align: .top, distribution: .fillEqually, metrics: LayoutMetrics(10, 10, 10, 10, 10, 10)).style(Style.blocksStyle)

Then call add the line:

print(blocks.blocks.count) //Generates compiler error: Ambiguous reference to member 'bricks(_:layout:)'

Documentations

Be able to show/hide one of the component with or without animation

Be able to show/hide one of the component (and its relevant margin layout) with or without animation.

Some inspirations
https://github.com/forkingdog/UIView-FDCollapsibleConstraints

Debug mode

Handle several components with same name, typical case is "Separator"

How ?

Directly configure a view in nib file with custom attributes

Implement Encodable & Decodable for configuration

Configuration <-> Json Format

Keep the coherence between: configuration, sub configuration AND view's attributes, subview's attributes

Add convenience methods for auto layout

Swift 3.0 style API (Breaking change)

Travis CI configuration needs to be updated

When making a pull request, the following error is generated by Travis CI and the build fails:
❌ “Use Legacy Swift Language Version” (SWIFT_VERSION) is required to be configured correctly for targets which use Swift. Use the [Edit > Convert > To Current Swift Syntax…] menu to choose a Swift version or use the Build Settings editor to configure the build setting directly.