<p><code>IGListKit</code> powers every major product in Instagram for hundreds of millions of users. It was built to be fast, efficient, and stable.</p>
<p>The preferred installation method for <code>IGListKit</code> is with <ahref="http://cocoapods.org">Cocoapods</a>. Simply add the following to your Podfile:</p>
<preclass="highlight ruby"><code><spanclass="c1"># Latest release of IGListKit</span>
<p>You can also manually install the framework by dragging and dropping the <code>IGListKit.xcodeproj</code> into your workspace.</p>
<p><code>IGListKit</code> supports a minimum iOS version of 8.0.</p>
<ahref='#creating-your-first-list'class='anchor'aria-hidden=true><spanclass="header-anchor"></span></a><h2id='creating-your-first-list'>Creating your first list</h2>
<p>After installing <code>IGListKit</code>, creating a new list is really simple.</p>
<ahref='#creating-a-section-controller'class='anchor'aria-hidden=true><spanclass="header-anchor"></span></a><h3id='creating-a-section-controller'>Creating a section controller</h3>
<p>Creating a new section controller is very simple. You just subclass <code>IGListSectionController</code> and conform to the <code>IGListSectionType</code> protocol. Once you conform to <code>IGListSectionType</code>, the compiler will make sure you implement all of the required methods.</p>
<p>Take a look at <ahref="TODO%20URL">LabelSectionController</a> for an example section controller that handles a <code>String</code> and configures a single cell with a <code>UILabel</code>.</p>
<p><strong>Note:</strong> This example is done within a <code>UIViewController</code> and uses both a stock <code>UICollectionViewFlowLayout</code> and <code>IGListAdapterUpdater</code>. You can use your own layout and updater if you need advanced features!</p>
</blockquote>
<ahref='#connecting-a-data-source'class='anchor'aria-hidden=true><spanclass="header-anchor"></span></a><h3id='connecting-a-data-source'>Connecting a data source</h3>
<p>The last step is the <code>IGListAdapter</code>’s data source and returning some data.</p>
<p>You can return an array of <em>any</em> type of data, as long as it conforms to <code>IGListDiffable</code>. We’ve included a <ahref="TODO%20URL">default implementation</a> for all objects, but adding your own implementation can unlock even better diffing.</p>
<p><code>IGListKit</code> uses an algorithm adapted from a paper titled <ahref="http://dl.acm.org/citation.cfm?id=359467&dl=ACM&coll=DL">A technique for isolating differences between files</a> by Paul Heckel. This algorithm uses a technique known as the <em>longest common subsequence</em> to find a minimal diff between collections in linear time <code>O(n)</code>. It finds all <strong>inserts</strong>, <strong>deletes</strong>, <strong>updates</strong>, and <strong>moves</strong> between arrays of data.</p>
<p>To add custom, diffable models, you need to conform to the <code>IGListDiffable</code> protocol and implement <code>diffIdentifier()</code> and <code>isEqual(_:)</code>.</p>
<p>For an example, consider the following model:</p>
<p>Both <code>jack</code> and <code>jill</code> represent the same <em>unique</em> data because they share the same <code>primaryKey</code>, but they are not <em>equal</em> because their names are different.</p>
<p>To represent this in <code>IGListKit</code>’s diffing, add and implement the <code>IGListDiffable</code> protocol:</p>
<p>The algorithm will skip updating two <code>User</code> objects that have the same <code>primaryKey</code> and <code>name</code>, even if they are different instances! You now avoid unecessary UI updates in the collection view even when providing new instances.</p>
<blockquote>
<p><strong>Note:</strong> Remember that <code>isEqual(_:)</code> should return <code>false</code> when you want to reload the cells in the corresponding section controller.</p>
<p>Adding supplementary views to section controllers is as simple as setting the weak <code>supplementaryViewSource</code> and implementing the <code>IGListSupplementaryViewSource</code> protocol. This protocol works nearly the same as returning and configuring cells.</p>
<p><strong>Display Delegate</strong></p>
<p>Section controllers can set the weak <code>displayDelegate</code> delegate to an object, including <code>self</code>, to receive display events about an section controller and individual cells.</p>
<p><strong>Working Range</strong></p>
<p>A <em>working range</em> is a distance before and after the visible bounds of the <code>UICollectionView</code> where section controllers within this bounds are notified of their entrance and exit. This concept lets your section controllers <strong>prepare content</strong> before they come on screen (e.g. download images).</p>
<p>The <code>IGListAdapter</code> must be initialized with a range value in order to work. This value is a multiple of the visible height or width, depending on the scroll-direction.</p>
<spanclass="nv">workingRangeSize</span><spanclass="p">:</span><spanclass="mf">0.5</span><spanclass="p">)</span><spanclass="c1">// 0.5x the visible size</span>
<p>The default <code>IGListAdapterUpdater</code> should handle any <code>UICollectionView</code> update that you need. However, if you find the functionality lacking, or want to perform updates in a very specific way, you can create an object that conforms to the <code>IGListUpdatingDelegate</code> protocol and initialize a new <code>IGListAdapter</code> with it.</p>
<p>Check out the updater <code>IGListReloadDataUpdater</code> used in unit tests for an example.</p>
<p><code>IGListKit</code> comes with the ability to add experimental (or prerelease) features. If an enhancement or fix cannot be proven with a unit test, we encourage you to wrap changes in an experiment so that it can be properly tested in production.</p>
<p>Read <ahref="https://instagram.github.io/IGListKit">the docs here</a>. Documentation is generated with <ahref="https://github.com/realm/jazzy">jazzy</a> and hosted on <ahref="https://pages.github.com">GitHub-Pages</a>.</p>
<p>Generated by <aclass="link"href="https://github.com/realm/jazzy"target="_blank"rel="external">jazzy ♪♫ v0.7.2</a>, a <aclass="link"href="http://realm.io"target="_blank"rel="external">Realm</a> project.</p>
