composed-swift/ComposedUI

Getting Started

Lets define a simple section to hold our contacts:

struct Person {
	var kind: String // family or friend
}

final class ContactsSection: ArraySection<Person> { }

Now we can extend this so we can show it in a collection view:

extension ContactsSection: CollectionSectionProvider {

	func section(with traitCollection: UITraitCollection) -> CollectionSection {
		/*
		Notes:
		The `dequeueMethod` signals to the coordinator how to register and dequeue the cell
		The element is generic to that cell type
		*/
		let cell = CollectionCellElement(section: self, dequeueMethod: .fromNib(PersonCell.self)) { cell, index, section in
			// Since everything is generic, we know both the cell and the element types
			cell.prepare(with: element(at: index))
		}

		return CollectionSection(section: self, cell: cell, header: header)
	}
	
}

Finally we need to retain a coordinator on our view controller:

final class ContactsViewController: UICollectionViewController {
	
	private var coordinator: CollectionCoordinator?
	
	override func viewDidLoad() {
		super.viewDidLoad()
		
		let contacts = ContactsSection()
		// contacts.append(...)
		
		// this single line is all that's needed to connect a collection view to our provider
		coordinator = CollectionCoordinator(collectionView: collectionView, sections: contacts)
	}

}

Now if we build and run, our collection view should be populated with our contacts as expected. Simple!

Protocols

ComposedUI also includes various protocols for enabling opt-in behaviour for your sections. Lets add support for selection events to our section above:

extension ContactsSection: CollectionSelectionHandler {
	
	func didSelect(at index: Int, cell: UICollectionViewCell) {
		print(element(at: index))
		deselect(at: index)
	}
	
}

That's it! Our coordinator already handles selection, so when a selection occurs it uses the indexPath to determine which section the selection occured in, it then attempts to cast that section to the protocol and on success, calls the associated method for us. As you can see this is an extremel powerful approach, yet extremely simple and elegant API that has 2 major benefits:

1. You opt-in to the features you want rather than inherit them by default
2. You can provide your own protocols and use the same infrastructure provided by Composed

Advanced Usage

So far we've built a relativel simple example that shows a single section. Lets update our view controller above to use a SectionProvider – and make things more interesting.

override func viewDidLoad() {
	super.viewDidLoad()
	
	// ... create our contacts (family and friends)
	
	let provider = ComposedSectionProvider()
	provider.append(family)
	provider.append(friends)
	
	// this single line is all that's needed to connect a collection view to our provider
	coordinator = CollectionCoordinator(collectionView: collectionView, provider: provider)
}

If we now run our example again, we'll see everything works as it did before, except we now have 2 sections.

This has a number of benefits already:

1. We didn't need to manage indexPaths or section indexes
2. We were able to reuse our existing section
3. Our section has no knowledge that its now inside of a larger structure

Now lets add some custom behaviour depending on the data:

extension ContactsSection: CollectionSelectionHandler {
	var allowsMultipleSelection: Bool { return isFamily }
}

Lets run the project again and we can see that the Family section now allows multiple selection, whereas the Friend section does not. This is another great benefit of using ComposedUI because the Coordinator is able to perform more advanced logic without needing to understand the underlying structure.

Package Metadata

Repository: composed-swift/ComposedUI

Stars: 12

Forks: 3

Open issues: 7

Default branch: master

Primary language: swift

License: Other

Topics: composed, composition, composition-api, protocol-oriented-programming, spm, swift, swift-package-manager, uicollectionview, uistackview, uitableview

README: README.md