• Stars
    star
    165
  • Rank 228,906 (Top 5 %)
  • Language
    Objective-C
  • License
    MIT License
  • Created over 9 years ago
  • Updated almost 7 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Elegant and concise way to load and show data sets into table and collection view. It supports AFNetworking, Core Data and memory data stores.

XLData

By XMARTLABS.

license license

XLData provides an elegant, flexible and concise way to load, synchronize and show data sets into table and collection views.

Purpose

You probably implement table/collection view controllers on a daily basis since a large part of an iOS app involves loading, synchronizing and showing data in these views.

The data you need to show might be stored in memory, a Core Data db, and often needs to be fetched from a json API endpoint.

Apart from loading, synchronizing and showing data sets into a UITableView/UICollectionView it also handles the empty state view and "no internet connection" view by showing or hiding a proper view when the table becomes empty/no-empty or internet reachability changes respectively.

XLData supports static and dynamic data sets. In order to support dynamic data sets efficiently it provides support for pagination and search, as well as a super simple way to fetch data from an API endpoint using AFNetworking.

Whatever your source of data, XLData provides an elegant and concise solution to handle all challenges introduced above with minimal effort. We are sure you will love XLData!

Gif Example

What XLData does

  • Show a data set stored in memory using a UITableView or a UICollectionView (works with both in-memory and Core Data data sets).
  • Keeps track of data set changes on runtime to update the UITableView/UICollectionView on the fly (works with both in-memory and Core Data data sets).
  • Provides a high-level abstraction to fetch a data set from a json API endpoint. You can check additional details here.
  • Provides support for pagination and filtering.
  • Provides an in-memory mechanism to store data sets. You can check additional details here.
  • Manage empty state view showing a customizable empty state view when the data set is empty.
  • Manage no internet connection view showing it when internet connection is not reachable.

Usage

XLData supports different scenarios from in-memory to core data data sets, it is also able to synchronize the data set with the json results of an API endpoint. In this section we'll briefly explain how it can be used in typical scenarios. For a more detailed explanation please take a look at the Examples folder.

Data Store table/collection view controller

1 - Create a view controller object that extends from XLDataStoreController.

2 - Add sections (XLDataSectionStore objects) and then items (any object) to a section. Items can be of any type.

[self.dataStore addDataSection:[XLDataSectionStore dataSectionStoreWithTitle:@"Example"]];
[self.dataStore addDataItem:@{@"title": "Row title 1"}];
[self.dataStore addDataItem:@{@"title": "Row title 2"}];

3 - Provide either the table or collection view cell:

-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    UITableViewCell * cell = ....
    // retrieve data set item at indexPath
    NSDictionary * dataItem = [self.dataStore dataAtIndexPath:indexPath];
    // configure cell
    ...
    return cell;
}

Any changes made to the data store will be automatically reflected in the table/collection view. ;)

For further details on how to implement this kind of view controller take a look at UsersDataStoreController.m file. You can see it in action by running the Demo app and tapping the cell "Data Store TableView" or "Data Store CollectionView".

Data Store table/collection view controller sync with remote json endpoint

1 - Create a view controller object that extends from XLRemoteDataStoreController.

2 - Set up the dataLoader property by following these steps:

// instantiate a XLDataLoader instance and set `dataLoader` property with it. We can use a convenient initializer to configure offset, limit and filter query parameter names.
self.dataLoader =  [[XLDataLoader alloc] initWithURLString:@"/mobile/users.json"
                                          offsetParamName:@"offset"
                                           limitParamName:@"limit"
                                    searchStringParamName:@"filter"];
// assign the view controller as the delegate of the data loader
self.dataLoader.delegate = self;
// assign the view controller as the storeDelegate of the data loader
self.dataLoader.storeDelegate = self;
// configure how many items we want to fetch per request
self.dataLoader.limit = 4;
// configure the dataset path within the json result. In this example the dataset is in the json result's root.
self.dataLoader.collectionKeyPath = @"";
// configure any additional query parameter by providing key/value using the `parameter` property.
self.dataLoader.parameters[@"paramName1"] = paramValue1;
self.dataLoader.parameters[@"paramName2"] = paramValue2;

3 - Provide a AFHTTPSessionManager by implementing the following XLDataLoaderDelegate method:

-(AFHTTPSessionManager *)sessionManagerForDataLoader:(XLDataLoader *)dataLoader

4 - Return the cell:

-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    UITableViewCell * cell = ....
    // retrieve data set item at indexPath
    NSDictionary * dataItem = [self.dataStore dataAtIndexPath:indexPath];
    // configure cell
    ...
    return cell;
}

XLData will automatically update the dataStore using the data fetched by its XLDataLoader object and the current property values such as offset and limit.

5 - Optional Override a method to update the data store differently. By default XLData appends the fetched items to the last section of the data store.

-(void)dataLoaderUpdateDataStore:(XLDataLoader *)dataLoader completionHandler:(void (^)())completionHandler

You must call at the end completionHandler block and must not call super implementation in case you decide to implement it.

The default implementation for the method above provided by XLRemoteDataStoreController is:

[[self.dataStore lastSection] addDataItems:dataLoader.loadedDataItems fromIndex:dataLoader.offset];
completionHandler();

For further details on how to implement this kind of view controller take a look at UsersRemoteDataStoreController.m file. You can see it in action by running the Demo app and tapping the cell "Remote Data Store TableView" or "Remote Data Store CollectionView".

####Core Data table/collection view controller

1 - Create a view controller object that extends from XLCoreDataController

2 - Set up fetchedResultsController property:

self.fetchedResultsController = [[NSFetchedResultsController alloc] initWithFetchRequest:[User getFetchRequest] managedObjectContext:[CoreDataStore mainQueueContext] sectionNameKeyPath:nil cacheName:nil];

3 - Return the cell:

-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    UITableViewCell * cell = ...
    // retrieve data set item at indexPath
    NSManagedObject * dataItem = [self.fetchedResultsController objectAtIndexPath:indexPath];
    // configure cell
    ...
    return cell;
}

For further details on how to implement this kind of view controller take a look at UsersCoreDataController.m file. You can see it in action by running the Demo app and tapping the cell "Core Data TableView" or "Core Data CollectionView".

####Core Data table/collection view controller sync with remote json endpoint

1 - Create a view controller object that extends from XLRemoteCoreDataController.

2 - Set up the dataLoader property by following these steps:

// instantiate a `XLDataLoader` instance and set `dataLoader` property with it. We can use a convenient initializer to configure offset, limit and filter query parameter names.
self.dataLoader =  [[XLDataLoader alloc] initWithURLString:@"/mobile/users.json"
                                          offsetParamName:@"offset"
                                           limitParamName:@"limit"
                                    searchStringParamName:@"filter"];
// assign the view controller as the delegate of the data loader
self.dataLoader.delegate = self;
// assign the view controller as the storeDelegate of the data loader
self.dataLoader.storeDelegate = self;
// configure how many items we want to fetch per request
self.dataLoader.limit = 4;
// configure the dataset path within the json result. In this example the dataset is in the json result's root.
self.dataLoader.collectionKeyPath = @"";
// configure any additional query parameter by providing key/value using the `parameter` property.
self.dataLoader.parameters[@"paramName1"] = paramValue1;
self.dataLoader.parameters[@"paramName2"] = paramValue2;

3 - Provide a AFHTTPSessionManager by implementing the following XLDataLoaderDelegate method:

-(AFHTTPSessionManager *)sessionManagerForDataLoader:(XLDataLoader *)dataLoader

4 - Return the cell:

-(UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    UITableViewCell * cell = ...
    // retrieve data set item at indexPath
    NSManagedObject * dataItem = [self.fetchedResultsController objectAtIndexPath:indexPath];
    // configure cell
    ...
    return cell;
}

5 - You must override the following method in order to synchronize the dataset fetched by the DataLoader with the Core Data dataset.

-(void)dataLoaderUpdateDataStore:(XLDataLoader *)dataLoader completionHandler:(void (^)())completionHandler

Make sure you invoke completionHandler block from within -(void)dataLoaderUpdateDataStore:(XLDataLoader *)dataLoader completionHandler:(void (^)())completionHandler when you are done with the core data sync (insert, update, delete NSManagedObjects).

For further details on how to implement this kind of view controller take a look at UsersRemoteCoreDataController.m file. You can see it in action by running the Demo app and tapping the cell "Remote Core Data TableView" or "Remote Core Data CollectionView".

###Customization

How to set up an empty state view

XLDataStoreController and XLCoreDataController expose emptyDataSetView property. We can set up a UIView either through storyboard (IBOutlet) or programatically.

How to set up a networking status view

XLRemoteDataStoreController and XLRemoteCoreDataController expose 'networkStatusView' property. We can set up a UIView either through storyboard (IBOutlet) or programatically.

Take a look at the examples to see how those properties work.

How it works?

In this section we will introduce two relevant abstractions that will help you have a better understanding of the library design and behaviour.

###XLDataStore

As you may already know, XLData is able to show a data set that is stored in-memory or in a Core Data db.

In order to show a Core Data data set we use the well-known class NSFetchedResultsController, making XLCoreDataController conforms to the NSFetchedResultsControllerDelegate protocol and get notified each time a new NSManagedObjectModel instance is added, deleted or modified within a NSManagedObjectContext.

Since NSFetchedResultsControllerDelegate works well and is popular among the community, we designed a similar pattern for in-memory data sets.

In order to accomplish that, XLDataStoreController store the in-memory data sets within a XLDataStore instance and conforms to the XLDataStoreDelegate to get notified whenever the in-memory data set is modified either by adding/removing a new item or section (XLDataStoreSection).

XLDataStoreDelegate is analog to NSFetchedResultsControllerDelegate but it works with in-memory data sets. XLDataStore contains XLDataStoreSection instances which are able to store any kind of object. Cool right?

BTW XLDataStore and its delegate are encapsulated and can be used independently and not just alongside XLData controllers.

###XLDataLoader

As we have explained previously, XLData is able to fetch data from an API endpoint. To do so we define XLDataLoader which exposes several properties in order to support any kind of json format.

This are some properties exposed by XLDataLoader:

@property NSUInteger offset;
@property NSUInteger limit;
@property NSString * searchString;
@property (nonatomic) NSMutableDictionary * parameters;
@property (nonatomic) NSString * collectionKeyPath;
@property (readonly) NSDictionary * loadedData;
@property (readonly) NSArray * loadedDataItems;

Apart of these properties, XLDataLoader exposes a delegate and storeDelegate.

@property (weak, nonatomic) id<XLDataLoaderDelegate> delegate;
@property (weak, nonatomic) id<XLDataLoaderStoreDelegate> storeDelegate;

Any object that conforms to XLDataLoaderDelegate can get notified about when a request starts, finish successfully or not.

@protocol XLDataLoaderDelegate <NSObject>

@required
-(AFHTTPSessionManager *)sessionManagerForDataLoader:(XLDataLoader *)dataLoader;

@optional
-(void)dataLoaderDidStartLoadingData:(XLDataLoader *)dataLoader;
-(void)dataLoaderDidLoadData:(XLDataLoader *)dataLoader;
-(void)dataLoaderDidFailLoadData:(XLDataLoader *)dataLoader withError:(NSError *)error;

@end

Any object that conforms to XLDataLoaderStoreDelegate can manipulate the fetched data and have the chance to update the data set or do something useful with the fetched data.

@protocol XLDataLoaderStoreDelegate <NSObject>

@optional
-(NSDictionary *)dataLoader:(XLDataLoader *)dataLoader convertJsonDataToModelObject:(NSDictionary *)data;
-(void)dataLoaderUpdateDataStore:(XLDataLoader *)dataLoader completionHandler:(void (^)())completionHandler;

@end

XLRemoteDataStoreController and XLRemoteCoreDataControllerconforms to XLDataLoaderDelegate and XLDataLoaderStoreDelegate protocols and updates the controller view accordingly by implementing some some of its methods.

However XLDataLoader and its delegates can be used independently and not just alongside XLData controllers.

How to run XLData examples

  1. Clone the repository [email protected]:xmartlabs/XLData.git. Optionally you can fork the repository and clone it from your own github account, this approach would be better if you want to contribute.
  2. Move to project root folder.
  3. Install example project cocoapod dependencies by running on terminal pod install.
  4. Open XLData workspace using XCode and run the project. Enjoy!

Installation

The easiest way to use XLData in your app is via CocoaPods.

  1. Add the following line in the project's Podfile file: pod 'XLData', '~> 2.0'.

  2. Run the command pod install from the Podfile folder directory.

In order to avoid unnecessary dependencies, XLData is divided into standalone sub-modules (with different dependencies each) using CocoaPods subspecs:

  • XLData/DataStore includes in-memory related library classes.
  • XLData/CoreData includes Core Data related library classes (depends on Core Data framework).
  • XLData/RemoteCoreData includes Core Data related library classes and networking classes (depends on AFNetworking library and Core Data framework).
  • XLData/RemoteDataStore includes in-memory related library classes and networking classes (depends on AFNetworking library).

Requirements

  • ARC
  • iOS 8.0 and above

Release Notes

Version 2.0.2

  • Bug fixes and stability improvements.

Version 2.0.0

  • Bug fixes.
  • Add completeHandler parameter to -(void)dataLoaderUpdateDataStore:(XLDataLoader *)dataLoader completionHandler:(void (^)())completionHandler
  • Split up XLDataLoaderDelegate into XLDataLoaderStoreDelegate and XLDataLoaderDelegate.

Version 1.0.2

  • Bug fixes.
  • Improve examples.

Version 1.0.1

  • Fix podspec minor issue.

Version 1.0.0

  • Initial release

Author

Martin Barreto (@mtnBarreto)

Contact

Any suggestion or question? Please create a Github issue or reach me out.

More Repositories

1

Eureka

Elegant iOS form builder in Swift
Swift
11,705
star
2

XLPagerTabStrip

Android PagerTabStrip for iOS.
Swift
6,880
star
3

XLForm

XLForm is the most flexible and powerful iOS library to create dynamic table-view forms. Fully compatible with Swift & Obj-C.
Objective-C
5,790
star
4

XLActionController

Fully customizable and extensible action sheet controller written in Swift
Swift
3,326
star
5

Bender

Easily craft fast Neural Networks on iOS! Use TensorFlow models. Metal under the hood.
Swift
1,795
star
6

PagerTabStripView

๐Ÿš€ Elegant Pager View fully written in pure SwiftUI.
Swift
722
star
7

Xniffer

A swift network profiler built on top of URLSession.
Swift
502
star
8

XLRemoteImageView

UIImageView that shows a progress indicator while the image is loading from server. It makes use of AFNetworking. It looks like the Instagram loading indicator.
Objective-C
346
star
9

fountain

Android Kotlin paged endpoints made easy
Kotlin
169
star
10

XLSlidingContainer

XLSlidingContainer is a custom container controller that embeds two independent view controllers allowing to easily maximize any of them using gestures.
Swift
149
star
11

android-snapshot-publisher

Gradle plugin to deploy Android Snapshot Versions
Kotlin
145
star
12

Swift-Project-Template

Script to easily create an iOS project base code!
Swift
144
star
13

Swift-Framework-Template

Swift script to easily create Swift frameworks!
Swift
143
star
14

react-native-line

Line SDK wrapper for React Native ๐Ÿš€
TypeScript
119
star
15

Ecno

Ecno is a task state manager built on top of UserDefaults in pure Swift 4.
Swift
102
star
16

XLSwiftKit

Helpers and extensions for Swift
Swift
101
star
17

XLMediaZoom

UI controls to view an image or reproduce a video in fullscreen like Instagram does.
Swift
92
star
18

XLMailBoxContainer

Custom container view controller ala MailBox app.
Objective-C
90
star
19

gong

Xmartlabs' Android Base Project Template
Kotlin
89
star
20

cordova-plugin-market

Cordova Plugin that allows you to access native Marketplace app (aka Google Play, App Store) from your app
Java
87
star
21

stock

Dart package for Async Data Loading and Caching. Combine local (DB, cache) and network data simply and safely.
Dart
74
star
22

Opera

Protocol-Oriented Network abstraction layer written in Swift.
Swift
74
star
23

Ahoy

A lightweight swift library to build onboarding experiences.
Swift
52
star
24

bigbang

Android base project used by Xmartlabs team
Kotlin
50
star
25

MetalPerformanceShadersProxy

A proxy for MetalPerformanceShaders which takes to a stub on a simulator and to the real implementation on iOS devices.
Objective-C
45
star
26

Swift-Style-Guide

Swift language style guide & coding conventions followed by Xmartlabs.
44
star
27

RxSimpleNoSQL

Reactive extensions for SimpleNoSQL
Java
37
star
28

docker-jenkins-android

Jenkins docker image for Android development
36
star
29

docker-htpasswd

Docker image to create a htpasswd file
32
star
30

spoter-embeddings

Create embeddings from sign pose videos using Transformers
Python
30
star
31

TypedNavigation

A lightweight library to help you navigate in compose with well typed functions.
Kotlin
23
star
32

XLMapChat

A chat application running on Node.js, using Socket.IO, GMaps, and more...
JavaScript
22
star
33

flutter-template

Xmartlabs' Flutter Base Project
Dart
17
star
34

XLDataLoader

Objective-C
16
star
35

tf_tabular

Easily build TensorFlow models on tabular data
Python
16
star
36

dreamsnap

Real life through the eyes of an artist
CSS
15
star
37

bigbang-template

Android template used by Xmartlabs team
Kotlin
14
star
38

blog

Xmartlabs Blog
CSS
14
star
39

MLKitTest

Source code related to a blog post about ML Kit
Swift
13
star
40

benderthon

Set of utilities to work easier with Bender.
Python
13
star
41

XLiOSKit

Objective-C
13
star
42

python-template

Python
9
star
43

react-template-xmartlabs

This is an internal private project - aims to be at some point in the future our React base project
TypeScript
9
star
44

gpgpu-comparison

9
star
45

XmartRecyclerView

A smart, simple and fast RecyclerView library
Java
8
star
46

jared-landing

Landing page for Jared Bot.
HTML
8
star
47

Fastlane-CI-Files

Fastlane CI files
Ruby
8
star
48

fluttips

Flutter trips and tricks
JavaScript
8
star
49

Android-Style-Guide

Style guide for Android by Xmartlabs
7
star
50

XLMaterialCalendarView

MaterialCalendarView powered with reactive bindings and with the Java 8 Time API!
Java
6
star
51

rnx-cli

TypeScript
6
star
52

docker-android

Docker image for Android development.
6
star
53

gh-top-repos-users

Download the contributors of the top repos.
Python
5
star
54

BuildSlackNotifier

Jenkins plugin to send Android build results through a slack channel using incoming webhooks
Java
4
star
55

javascript-plugin

Source Code of blog Making a JS widget: a full-stack approach
Ruby
4
star
56

AndroidSwissKnife

Kotlin
3
star
57

projecthub-landing

ProjectHub lets you manage your GitHub Projects on the fly, from your mobile phone.
HTML
3
star
58

gh2s3

Download GitHub Archive data and upload it to an Amazon S3 bucket.
Python
3
star
59

xmartchat

Dart
3
star
60

pycon-es-workshop

Python
2
star
61

xl-blog

Gatsby XL's Blogpost
JavaScript
2
star
62

node-template

Base template for starting a new Node project
TypeScript
2
star
63

mPOS-SDK-iOS

Objective-C
1
star
64

terraform

HCL
1
star
65

FastlaneDemo

Demo project to show a basic fastlane configuration
Swift
1
star
66

xl-school-automation-web

This is the repository for web automation training for XL
Java
1
star
67

workshop-microservicios

Python
1
star
68

fountain-docs

Fountain documentation
1
star
69

client-side-widget-template

JavaScript templates for a client-side widget
HTML
1
star
70

rn-lightbox

JavaScript
1
star
71

malaria-detector

Jupyter Notebook
1
star
72

SQLiteDSL

1
star
73

terraform-basic-infra

HCL
1
star
74

docker-pcl-cmake

Docker image containing PCL and CMake.
1
star
75

cocoapods-specs

Ruby
1
star
76

simon-ai

This is the repository for the XL Says initiative
Dart
1
star