TimetableKit

The TimetableKit provides you with a timetable view that manages an ordered collection of events and presents them in the planned order.

Overview • Development • Usage • Installation • Architecture • Engage • Licensing

Overview

A timetable view is made up of sections each with its own locations. Each location has one or more event tiles. When adding a timetable view to your user interface, your app’s main job is to manage the event data associated with that timetable view.

The structure of the timetable includes the following components:

• Event: Events are the elementary data for the timetable. An event is an entity which is defined by it's occurence in time specified by a time interval a name attribute and a location where it occures.

• Location: A group of events associated with the same location where they occure.

• Section: A number of locations which are grouped together by theme or motto. This can be anything, for a festival there could be one section for the stages and one for the food shops.

Sections are identified by their index number within the timetable view, and locations are identified by their index number within a section. Event tiles are identified by their index number within the location.

Limitations

• The timetable view is not able to display overlapping or simultan occuring events at the same location, you have to split these locations into multiple locations.
• The timetable view is meant for displaying events that have a duration of hours not days. If you need to display lengthy events please consider to use a calendar view.

Development

Setup

1. Install and setup Xcode 15 or higher
2. Install jazzy

   brew install jazzy
   

3. Install bartycrouch

   brew install bartycrouch
   

Build

There is an ExampleApp for developing and testing which you can build using Xcode.

Requirements

• iOS 13.0+
• Xcode 13.1+
• swift-tools-version:5.3+
• jazzy 0.13.6+ for building the documentation
• bartycrouch 4.8.0+ for string localization

Usage

After installing the TimtableKit in your project you can use the TimetableView the same way you use the build-in UIViews. If you want to use the timetable in a SwiftUI based project you can see an example wrapper implementation. For more information about using UIViews within SwiftUI see UIViewRepresentable.

The timetable view is driven by the delegation pattern. After you created and installed the view the way you need it, the timetable will ask its delegate to determin what and how to display its content. You can implemen four different delegate protocols to influence the behavior of the timetable: TimetableDataSource, TimetableDelegate, TimetableAppearanceDelegate and TimetableClock

• You are required to implement the TimetableDataSource as it provides the data to display.
• The TimetableDelegate allows you to react to the user interacting with the timetable and is also required to implement.
• By implementing the TimetableAppearanceDelegate you can fine tune the timetables appearance.
• Implementing TimetableClock allows the delegate to determin the current date and time displayed by the timetable.

Installation

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate TimetableKit into your Xcode project using Carthage, specify it in your Cartfile:

github "Festivals-App/timetablekit-ios" ~> 0.1

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. It is in early development, but TimetableKit does support its use on supported platforms.

Once you have your Swift package set up, adding TimetableKit as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/Festivals-App/timetablekit-ios.git", .upToNextMajor(from: "0.1"))
]

Architecture

The TimetableKit is not coupled with other projects from the FestivalsApp and can be used within any other project unrelated to it. To find out more about architecture and technical information see the ARCHITECTURE document.

The full documentation for the FestivalsApp is in the festivals-documentation repository. The documentation repository contains technical documents, architecture information, UI/UX specifications, and whitepapers related to this implementation.

Engage

I welcome every contribution, whether it is a pull request or a fixed typo. The best place to discuss questions and suggestions regarding the timetable is the projects issues section. More general information and a good starting point if you want to get involved is the festival-documentation repository.

If this doesn't fit you proposal or reason to contact me, there are some more general purpose communication channels where you can reach me, listed in the following table.

Type	Channel
General Discussion
Other Requests

Licensing

Copyright (c) 2020-2023 Simon Gaus.

Licensed under the GNU Lesser General Public License v3.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.html.

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.