Repository files navigation

The MatrixKit will no longer be supported, the code will be merged intoElement iOS repository.

Please avoid to create issues or PR in this repository, report them toElement iOS instead.

WhileMatrixSDK provides an Objective-C API touse the Matrix Client-Server API, MatrixKit provides a higher level, reusableand easy-customisable UI built on top of the SDK.

Put simply, MatrixKit is a set of ViewControllers and Views. An app developercan pick up UI components from this set and insert them into their applicationstoryboard or code. The end application controls what is shown when.

Each of the provided UI components has been designed to run standalone. Thereare no dependencies between them.

The currently available view controllers are:

• MXKRoomViewController: shows messages of a room and allows user to chat
• MXKRecentListViewController: displays the user's rooms ordered by lastactivity
• MXKRoomMemberListViewController: a page showing the list of a room's members

Coming soon:

• Authentication views
• Public rooms: the list of public rooms
• Room creation
• Address book

Here are two samples for displaying messages of a room:

The left one is the stock room view controller. This is the one used byConsole (GitHub).

The right one is an override ofJSQMessagesViewController. The display isfully managed by JSQMessagesViewController but the implementation uses datacomputed by MatrixKit components: MXKRoomDataSource & MXKRoomBubbleCellData.See the next session for definition of DataSource and celldata.

All view controllers in MatrixKit that display a list of items share the sameecosystem based on 4 components:

ViewController

The ViewController is responsible for managing the display and user actions.

DataSource

Provides the ViewController with items (CellView objects) to display. Moreaccurately, the DataSource gets data (mainly Matrix events) from the MatrixSDK. It asks CellData objects to process the data into human readable text andstore it. Then, when the ViewController asks for a cellview, it renders thecorresponding CellData into a cellview that it returns.

For convenience, DataSources provided in MatrixKit implementUITableViewDataSource and UICollectionViewDataSource protocols so thatUITableView and UICollectionView DataSources can be directly plugged to them.

CellData

Contains data the CellView must display. There is one CellData object peritem in the list. This is also a kind of cache to avoid displayed data needingto be computed everytime.

CellView

This is an abstract object. It is often a UITableViewCellView or aUICollectionViewCell but can be any UIView. This is the view for an itemdisplayed by the ViewController.

You can embed MatrixKit to your application project with CocoaPods. The pod forthe latest MatrixKit release is:

pod 'MatrixKit'

Suppose you have a MXSession instance stored in mxSession (you can learn howto get in the Matrix SDK tutorialshere) and you want to chat in #matrix:matrix.org which room id is!cURbafjkfsMDVwdRDQ:matrix.org.

You will have to instantiate a MXKRoomViewController and attach aMXKRoomDataSource object to it. This object that will manage the room data.This is done with the following code:

// Create a data souce for managing data for the targeted roomMXKRoomDataSource *roomDataSource = [[MXKRoomDataSource alloc] initWithRoomId:@"!cURbafjkfsMDVwdRDQ:matrix.org" andMatrixSession:mxSession];// Create the room view controller that will display itMXKRoomViewController *roomViewController = [[MXKRoomViewController alloc] init];[roomViewController displayRoom:roomDataSource];

Then, your app presents roomViewController. Your end user is now able to postmessages or images to the room, navigate in the history, etc.

The approach is similar to the previous use case. You need to create a datasource and pass it to the view controller:

// Create a data source for managing dataMXKRecentsDataSource *recentsDataSource = [[MXKRecentsDataSource alloc] initWithMatrixSession:mxSession];// Create the view controller that will display itMXKRecentListViewController *recentListViewController = [[MXKRecentListViewController alloc] init];[recentListViewController displayList:recentsDataSource];

The kit has been designed so that developers can make customisations atdifferent levels, which are:

ViewController

The provided ViewControllers can be subclassed in order to customise the following points:

• the CellView class used by the DataSource to render CellData.
• the layout of the table or the collection view.
• the interactions with the end user.

CellView

The developer may override MatrixKit CellViews to completely change the way items are displayed. Note that CellView classes must be conformed to the MXKCellRendering protocol.

CellData

The developer can implement his own CellData classes in order to prepare differently rendered data. Note that the use of customised CellData classes is handled at DataSource level (see registerCellDataClass method).

DataSource

This object gets the data from the Matrix SDK and serves it to the viewcontroller via CellView and CellData objects. You can override the defaultDataSource to have a different behaviour.

This use case shows how to make cellView customisation.

A room chat is basically a list of items where each item represents a message(or a set of messages if they are grouped by sender). In the code, these itemsare inherit from MXKTableViewCell. If you are not happy with the defaultones used by MXKRoomViewController and MXKRoomDataSource, you can change them by overriding MXKDataSourceDelegate methods in your view controller:

- (Class<MXKCellRendering>)cellViewClassForCellData:(MXKCellData*)cellData{   // Let `MyOwnBubbleTableViewCell` class manage the display of message cells   // This class must inherit from UITableViewCell and must conform the `MXKCellRendering` protocol   return MyOwnBubbleTableViewCell.class;}- (NSString *)cellReuseIdentifierForCellData:(MXKCellData*)cellData{    // Return the `MyOwnBubbleTableViewCell` cell identifier.    return @"MyOwnBubbleTableViewCellIdentifier";}

You may return a cellView class by taking into account the provided cell data. For example you can define different classes for received and sent messages.

If you want to help to improve MatrixKit by adding new ViewControllers, newviews, new CellViews or other improvements, this git repository contains asample Xcode project for demoing all reusable UI. Please hack on the developbranch and make git pull requests from it.

As its dependencies are based on CocoaPods, you will need to run pod installbefore opening MatrixKit.xcworkspace.

The filled icons play, pause, minus, back and keyboard are taken from icons8:http://icons8.com/

Copyright (c) 2014-2017 OpenMarket LtdCopyright (c) 2017 Vector Creations LtdCopyright (c) 2017-2018 New Vector Ltd

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.