mirror of
https://github.com/Instagram/IGListKit
synced 2026-05-15 05:18:18 +00:00
e15311a0a2
Summary: Title Reviewed By: jessesquires Differential Revision: D4002935 fbshipit-source-id: d407942c49407807776e1d911177c040c25f4355
406 lines
26 KiB
HTML
406 lines
26 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<title>IGListKit Reference</title>
|
|
<link rel="stylesheet" type="text/css" href="css/jazzy.css" />
|
|
<link rel="stylesheet" type="text/css" href="css/highlight.css" />
|
|
<meta charset='utf-8'>
|
|
<script src="js/jquery.min.js" defer></script>
|
|
<script src="js/jazzy.js" defer></script>
|
|
|
|
</head>
|
|
<body>
|
|
<a title="IGListKit Reference"></a>
|
|
<header>
|
|
<div class="content-wrapper">
|
|
<p><a href="index.html">IGListKit Docs</a> (79% documented)</p>
|
|
<p class="header-right"><a href="https://github.com/Instagram/IGListKit"><img src="img/gh.png"/>View on GitHub</a></p>
|
|
</div>
|
|
</header>
|
|
<div class="content-wrapper">
|
|
<p id="breadcrumbs">
|
|
<a href="index.html">IGListKit Reference</a>
|
|
<img id="carat" src="img/carat.png" />
|
|
IGListKit Reference
|
|
</p>
|
|
</div>
|
|
<div class="content-wrapper">
|
|
<nav class="sidebar">
|
|
<ul class="nav-groups">
|
|
<li class="nav-group-name">
|
|
<a href="Categories.html">Categories</a>
|
|
<ul class="nav-group-tasks">
|
|
<li class="nav-group-task">
|
|
<a href="Categories.html#/c:objc(cy)NSObject@IGListDiffable">NSObject(IGListDiffable)</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="nav-group-name">
|
|
<a href="Classes.html">Classes</a>
|
|
<ul class="nav-group-tasks">
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListAdapter.html">IGListAdapter</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListAdapterUpdater.html">IGListAdapterUpdater</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListBatchUpdateData.html">IGListBatchUpdateData</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListCollectionView.html">IGListCollectionView</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListIndexPathResult.html">IGListIndexPathResult</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListIndexSetResult.html">IGListIndexSetResult</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListMoveIndex.html">IGListMoveIndex</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListMoveIndexPath.html">IGListMoveIndexPath</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes.html#/c:objc(cs)IGListReloadDataUpdater">IGListReloadDataUpdater</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListSectionController.html">IGListSectionController</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListSingleSectionController.html">IGListSingleSectionController</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Classes/IGListStackedSectionController.html">IGListStackedSectionController</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="nav-group-name">
|
|
<a href="Constants.html">Constants</a>
|
|
<ul class="nav-group-tasks">
|
|
<li class="nav-group-task">
|
|
<a href="Constants.html#/c:@IGListKitVersionNumber">IGListKitVersionNumber</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Constants.html#/c:@IGListKitVersionString">IGListKitVersionString</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="nav-group-name">
|
|
<a href="Enums.html">Enums</a>
|
|
<ul class="nav-group-tasks">
|
|
<li class="nav-group-task">
|
|
<a href="Enums/IGListDiffOption.html">IGListDiffOption</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Enums/IGListExperiment.html">IGListExperiment</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="nav-group-name">
|
|
<a href="Protocols.html">Protocols</a>
|
|
<ul class="nav-group-tasks">
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListAdapterDataSource.html">IGListAdapterDataSource</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListAdapterDelegate.html">IGListAdapterDelegate</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListAdapterUpdaterDelegate.html">IGListAdapterUpdaterDelegate</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListCollectionContext.html">IGListCollectionContext</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListDiffable.html">IGListDiffable</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListDisplayDelegate.html">IGListDisplayDelegate</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListScrollDelegate.html">IGListScrollDelegate</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListSectionType.html">IGListSectionType</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListSingleSectionControllerDelegate.html">IGListSingleSectionControllerDelegate</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListSupplementaryViewSource.html">IGListSupplementaryViewSource</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListUpdatingDelegate.html">IGListUpdatingDelegate</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Protocols/IGListWorkingRangeDelegate.html">IGListWorkingRangeDelegate</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="nav-group-name">
|
|
<a href="Type Definitions.html">Type Definitions</a>
|
|
<ul class="nav-group-tasks">
|
|
<li class="nav-group-task">
|
|
<a href="Type Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListItemUpdateBlock">IGListItemUpdateBlock</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Type Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListObjectTransitionBlock">IGListObjectTransitionBlock</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Type Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListReloadUpdateBlock">IGListReloadUpdateBlock</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Type Definitions.html#/c:IGListAdapter.h@T@IGListUpdaterCompletion">IGListUpdaterCompletion</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Type Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListUpdatingCompletion">IGListUpdatingCompletion</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="nav-group-name">
|
|
<a href="Functions.html">Functions</a>
|
|
<ul class="nav-group-tasks">
|
|
<li class="nav-group-task">
|
|
<a href="Functions.html#/c:@F@IGListDiff">IGListDiff</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Functions.html#/c:@F@IGListDiffExperiment">IGListDiffExperiment</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Functions.html#/c:@F@IGListDiffPaths">IGListDiffPaths</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Functions.html#/c:@F@IGListDiffPathsExperiment">IGListDiffPathsExperiment</a>
|
|
</li>
|
|
<li class="nav-group-task">
|
|
<a href="Functions.html#/c:IGListExperiments.h@F@IGListExperimentEnabled">IGListExperimentEnabled</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</nav>
|
|
<article class="main-content">
|
|
<section>
|
|
<section class="section">
|
|
|
|
<p align="center">
|
|
<img src="https://raw.githubusercontent.com/Instagram/IGListKit/master/Resources/logo-animation.gif" width=400 />
|
|
</p>
|
|
|
|
<p><a href="https://travis-ci.org/Instagram/IGListKit"><img src="https://secure.travis-ci.org/Instagram/IGListKit.svg" alt="Build Status" /></a> <a href="https://cocoapods.org/pods/IGListKit"><img src="https://img.shields.io/cocoapods/v/IGListKit.svg" alt="Version Status" /></a> <a href="https://opensource.org/licenses/BSD-3-Clause"><img src="https://img.shields.io/cocoapods/l/IGListKit.svg" alt="license BSD" /></a> <a href="https://instagram.github.io/IGListKit"><img src="https://img.shields.io/cocoapods/p/IGListKit.svg" alt="Platform" /></a> <a href="https://github.com/Carthage/Carthage"><img src="https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat" alt="Carthage compatible" /></a></p>
|
|
|
|
<hr>
|
|
|
|
<p>A data-driven <code>UICollectionView</code> framework for building fast and flexible lists.</p>
|
|
|
|
<table><thead>
|
|
<tr>
|
|
<th></th>
|
|
<th>Main Features</th>
|
|
</tr>
|
|
</thead><tbody>
|
|
<tr>
|
|
<td>🙅</td>
|
|
<td>Never call <code>performBatchUpdates(_:, completion:)</code> or <code>reloadData()</code> again</td>
|
|
</tr>
|
|
<tr>
|
|
<td>🏠</td>
|
|
<td>Better architecture with reusable cells and components</td>
|
|
</tr>
|
|
<tr>
|
|
<td>🔠</td>
|
|
<td>Create collections with multiple data types</td>
|
|
</tr>
|
|
<tr>
|
|
<td>🔑</td>
|
|
<td>Decoupled diffing algorithm</td>
|
|
</tr>
|
|
<tr>
|
|
<td>✅</td>
|
|
<td>Fully unit tested</td>
|
|
</tr>
|
|
<tr>
|
|
<td>🔍</td>
|
|
<td>Customize your diffing behavior for your models</td>
|
|
</tr>
|
|
<tr>
|
|
<td>📱</td>
|
|
<td>Simply <code>UICollectionView</code> at its core</td>
|
|
</tr>
|
|
<tr>
|
|
<td>🚀</td>
|
|
<td>Extendable updating API</td>
|
|
</tr>
|
|
<tr>
|
|
<td>🐦</td>
|
|
<td>Written in Objective-C with full Swift interop support</td>
|
|
</tr>
|
|
</tbody></table>
|
|
|
|
<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>
|
|
<a href='#installation' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='installation'>Installation</h2>
|
|
|
|
<p>The preferred installation method for <code>IGListKit</code> is with <a href="http://cocoapods.org">Cocoapods</a>. Simply add the following to your Podfile:</p>
|
|
<pre class="highlight ruby"><code><span class="c1"># Latest release of IGListKit</span>
|
|
<span class="n">pod</span> <span class="s1">'IGListKit'</span>
|
|
</code></pre>
|
|
|
|
<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>
|
|
<a href='#creating-your-first-list' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='creating-your-first-list'>Creating your first list</h2>
|
|
|
|
<p>After installing <code>IGListKit</code>, creating a new list is really simple.</p>
|
|
<a href='#creating-a-section-controller' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='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 <a href="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>
|
|
<pre class="highlight swift"><code><span class="kd">class</span> <span class="kt">LabelSectionController</span><span class="p">:</span> <span class="kt">IGListSectionController</span><span class="p">,</span> <span class="kt">IGListSectionType</span> <span class="p">{</span>
|
|
<span class="c1">// ...</span>
|
|
<span class="p">}</span>
|
|
</code></pre>
|
|
<a href='#creating-the-ui' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='creating-the-ui'>Creating the UI</h3>
|
|
|
|
<p>After creating at least one section controller, you must create an <code>IGListCollectionView</code> and <code>IGListAdapter</code>.</p>
|
|
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">layout</span> <span class="o">=</span> <span class="kt">UICollectionViewFlowLayout</span><span class="p">()</span>
|
|
<span class="k">let</span> <span class="nv">collectionView</span> <span class="o">=</span> <span class="kt">IGListCollectionView</span><span class="p">(</span><span class="nv">frame</span><span class="p">:</span> <span class="kt">CGRect</span><span class="o">.</span><span class="n">zero</span><span class="p">,</span> <span class="nv">collectionViewLayout</span><span class="p">:</span> <span class="n">layout</span><span class="p">)</span>
|
|
|
|
<span class="k">let</span> <span class="nv">updater</span> <span class="o">=</span> <span class="kt">IGListAdapterUpdater</span><span class="p">()</span>
|
|
<span class="k">let</span> <span class="nv">adapter</span> <span class="o">=</span> <span class="kt">IGListAdapter</span><span class="p">(</span><span class="nv">updatingDelegate</span><span class="p">:</span> <span class="n">updater</span><span class="p">,</span> <span class="nv">viewController</span><span class="p">:</span> <span class="k">self</span><span class="p">,</span> <span class="nv">workingRangeSize</span><span class="p">:</span> <span class="mi">0</span><span class="p">)</span>
|
|
<span class="n">adapter</span><span class="o">.</span><span class="n">collectionView</span> <span class="o">=</span> <span class="n">collectionView</span>
|
|
</code></pre>
|
|
|
|
<blockquote>
|
|
<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>
|
|
<a href='#connecting-a-data-source' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='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>
|
|
<pre class="highlight swift"><code><span class="kd">func</span> <span class="nf">objectssForListAdapter</span><span class="p">(</span><span class="nv">listAdapter</span><span class="p">:</span> <span class="kt">IGListAdapter</span><span class="p">)</span> <span class="o">-></span> <span class="p">[</span><span class="kt">IGListDiffable</span><span class="p">]</span> <span class="p">{</span>
|
|
<span class="c1">// this can be anything!</span>
|
|
<span class="k">return</span> <span class="p">[</span> <span class="s">"Foo"</span><span class="p">,</span> <span class="s">"Bar"</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span> <span class="s">"Biz"</span> <span class="p">]</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="kd">func</span> <span class="nf">listAdapter</span><span class="p">(</span><span class="nv">listAdapter</span><span class="p">:</span> <span class="kt">IGListAdapter</span><span class="p">,</span>
|
|
<span class="nf">sectionControllerForObject</span><span class="p">(</span><span class="nv">object</span><span class="p">:</span> <span class="kt">AnyObject</span><span class="p">)</span> <span class="o">-></span> <span class="kt">IGListSectionController</span> <span class="p">{</span>
|
|
<span class="k">if</span> <span class="k">let</span> <span class="nv">_</span> <span class="o">=</span> <span class="n">object</span> <span class="k">as?</span> <span class="kt">String</span> <span class="p">{</span>
|
|
<span class="k">return</span> <span class="kt">LabelSectionController</span><span class="p">()</span>
|
|
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
|
|
<span class="k">return</span> <span class="kt">NumberSectionController</span><span class="p">()</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="kd">func</span> <span class="nf">emptyViewForListAdapter</span><span class="p">(</span><span class="nv">listAdapter</span><span class="p">:</span> <span class="kt">IGListAdapter</span><span class="p">)</span> <span class="o">-></span> <span class="kt">UIView</span><span class="p">?</span> <span class="p">{</span>
|
|
<span class="k">return</span> <span class="kc">nil</span>
|
|
<span class="p">}</span>
|
|
</code></pre>
|
|
|
|
<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 <a href="TODO%20URL">default implementation</a> for all objects, but adding your own implementation can unlock even better diffing.</p>
|
|
<a href='#diffing' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='diffing'>Diffing</h2>
|
|
|
|
<p><code>IGListKit</code> uses an algorithm adapted from a paper titled <a href="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>
|
|
<pre class="highlight swift"><code><span class="kd">class</span> <span class="kt">User</span> <span class="p">{</span>
|
|
<span class="k">let</span> <span class="nv">primaryKey</span><span class="p">:</span> <span class="kt">Int</span>
|
|
<span class="k">let</span> <span class="nv">name</span><span class="p">:</span> <span class="kt">String</span>
|
|
<span class="c1">// implementation, etc</span>
|
|
<span class="p">}</span>
|
|
</code></pre>
|
|
|
|
<p>The user’s <code>primaryKey</code> uniquely identifies user data, and the <code>name</code> is just the value for that user.</p>
|
|
|
|
<p>Consider the following two users:</p>
|
|
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">jack</span> <span class="o">=</span> <span class="kt">User</span><span class="p">(</span><span class="nv">primaryKey</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="nv">name</span><span class="p">:</span> <span class="s">"Jack"</span><span class="p">)</span>
|
|
<span class="k">let</span> <span class="nv">jill</span> <span class="o">=</span> <span class="kt">User</span><span class="p">(</span><span class="nv">primaryKey</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="nv">name</span><span class="p">:</span> <span class="s">"Jill"</span><span class="p">)</span>
|
|
</code></pre>
|
|
|
|
<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>
|
|
<pre class="highlight swift"><code><span class="kd">extension</span> <span class="kt">User</span><span class="p">:</span> <span class="kt">IGListDiffable</span> <span class="p">{</span>
|
|
<span class="kd">func</span> <span class="nf">diffIdentifier</span><span class="p">()</span> <span class="o">-></span> <span class="kt">NSObjectProtocol</span> <span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">pk</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="kd">func</span> <span class="nf">isEqual</span><span class="p">(</span><span class="nv">object</span><span class="p">:</span> <span class="kt">AnyObject</span><span class="p">?)</span> <span class="o">-></span> <span class="kt">Bool</span> <span class="p">{</span>
|
|
<span class="k">if</span> <span class="n">object</span> <span class="o">===</span> <span class="k">self</span> <span class="p">{</span>
|
|
<span class="k">return</span> <span class="kc">true</span>
|
|
<span class="p">}</span>
|
|
<span class="k">if</span> <span class="k">let</span> <span class="nv">object</span> <span class="o">=</span> <span class="n">object</span> <span class="k">as?</span> <span class="kt">User</span> <span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">name</span> <span class="o">==</span> <span class="n">object</span><span class="o">.</span><span class="n">name</span>
|
|
<span class="p">}</span>
|
|
<span class="k">return</span> <span class="kc">false</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span>
|
|
</code></pre>
|
|
|
|
<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>
|
|
</blockquote>
|
|
<a href='#advanced-features' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='advanced-features'>Advanced Features</h2>
|
|
<a href='#delegates' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='delegates'>Delegates</h3>
|
|
|
|
<p><strong>Supplementary Views</strong></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>
|
|
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">adapter</span> <span class="o">=</span> <span class="kt">IGListAdapter</span><span class="p">(</span><span class="nv">updatingDelegate</span><span class="p">:</span> <span class="kt">IGListAdapterUpdater</span><span class="p">(),</span>
|
|
<span class="nv">viewController</span><span class="p">:</span> <span class="k">self</span><span class="p">,</span>
|
|
<span class="nv">workingRangeSize</span><span class="p">:</span> <span class="mf">0.5</span><span class="p">)</span> <span class="c1">// 0.5x the visible size</span>
|
|
</code></pre>
|
|
|
|
<p><img src="Resources/workingrange.png" alt="working-range"></p>
|
|
|
|
<p>You can set the weak <code>workingRangeDelegate</code> on an section controller to receive events.</p>
|
|
<a href='#custom-updaters' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='custom-updaters'>Custom Updaters</h3>
|
|
|
|
<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>
|
|
<a href='#experiments' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='experiments'>Experiments</h3>
|
|
|
|
<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>
|
|
<a href='#documentation' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='documentation'>Documentation</h2>
|
|
|
|
<p>Read <a href="https://instagram.github.io/IGListKit">the docs here</a>. Documentation is generated with <a href="https://github.com/realm/jazzy">jazzy</a> and hosted on <a href="https://pages.github.com">GitHub-Pages</a>.</p>
|
|
<a href='#generating-docs' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h4 id='generating-docs'>Generating docs</h4>
|
|
<pre class="highlight shell"><code><span class="gp">$ </span>./build_docs.sh
|
|
<span class="gp">$ </span>open -a safari docs/index.html <span class="c"># preview in Safari</span>
|
|
</code></pre>
|
|
<a href='#contributing' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='contributing'>Contributing</h2>
|
|
|
|
<p>See the <a href="CONTRIBUTING.md">CONTRIBUTING</a> file for how to help out.</p>
|
|
<a href='#license' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='license'>License</h2>
|
|
|
|
<p><code>IGListKit</code> is BSD-licensed. We also provide an additional patent grant.</p>
|
|
|
|
<p>The files in the /Example directory are licensed under a separate license as specified in each file; documentation is licensed CC-BY-4.0.</p>
|
|
|
|
</section>
|
|
</section>
|
|
<section id="footer">
|
|
<p>© 2016 <a class="link" href="https://twitter.com/fbOpenSource" target="_blank" rel="external">Instagram</a>. All rights reserved. (Last updated: 2016-09-30)</p>
|
|
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.7.2</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
|
|
</section>
|
|
</article>
|
|
</div>
|
|
</body>
|
|
</div>
|
|
</html>
|