Modules overview
This page provides a quick overview of the different modules provided by Bitlibs.
Datamodels
At the core of bitlibs there is the concept of Datamodels. Datamodels provide abstractions around pieces of data in your application which actually represent instances of domain models. You define a Datamodel class by stating the fields the model has and the operations that can be performed on it. Datamodels can even be defined in a hierarchical fashion by embedding one model into another, increasing modularity and code reuse.
After having defined the models in your application you can benefit from working with instances of these models instead of with raw pieces of data. This provides a much better developer experience, enables code reuse and increases the modularity of your application. When using a PersistenceManager to persist your models to and fetch them from an API, Datamodels also mirror the objects returned by your API. You can think of the Datamodels module as being the Object-Relational Mapper for your front-end applications.
Fields
You define your Datamodels by stating the fields (properties) they have along with the types of those fields. Bitlibs provides a number of built-in field classes for the most common types, like StringField, BooleanField, EmailField, RegexField, DateTimeField etcetera, but you can also define your own. The field type determines the range of values accepted by that field and how its value is serialized.
Persistence Managers
A PersistenceManager takes care of saving Datamodel instances to and retrieving them from a persistent store like an API, local storage etc. You can obtain instances of your Datamodel classes by either creating them anew or retrieving them from a persistent store. You can modify retrieved objects and save them back to their persistent store with just a few calls.
Validators
Validators take care of validating the field values of your models. Bitlibs provides a built-in validator but you can also provide your own for even greater control over when and how datamodels should be validated.
Serializers
Serializers determine how instances of Datamodels are (de)serialized to/from the format in which they are stored in their persistence store. The built-in validator supports conditional serialization of fields and more, but again you can also make your own subclass.
Signallers
Signallers provide a publish-subscribe system for events regarding models. Datamodel and Field instances both have instances of their own Signaller subclass to which code can subscribe in order to be notified about changes to models.
Datasets
Datasets provide an abstraction around collections of Datamodel objects. You often need to work with (paginated) sets of data (tables, lists, grids etc.) which have to be sortable, filterable and searchable. These operations can either be performed by an API from which you retrieve the data in the set or by the javascript application code after retrieving it. Datasets allow you to define which operations a dataset should support and how those operation are implemented.
Filter Backends
A FilterBackend subclass modifies the current selection of a Dataset in some way. Bitlibs provides built-in filter backends for searching, sorting and generic filtering of dataset in javascript code. FilterBackends can take arguments which influence how they operate on the Dataset on which they are defined.
Forms
The Forms module provides an optional view layer integration for working with Datamodel instances in the UI in an application using one of the supported frameworks. You simply define how a field of a certain type should be represented in the UI, after which you can embed the view representations (widgets) for the fields of a model instance anywhere in your view. Bitlibs then takes care of syncing the inputted data with the model instance, validating the instance and reporting back any errors and persisting the model instance when submitting the form.
Networking
The networking module provides a modular, layered network stack for your application. At the heart of the networking module is the Networker class, which you can use to perform all of your network requests. The APIPersistenceManager class from the Datamodels module uses the networking module to perform requests to APIs.
Networker Clients
You register NetworkerClients at a networker to handle requests to certain domains or subpaths on those domains. When performing a request, the networker picks the most applicable client for the request and lets it handle it. There are a number of built-in clients that can be used to easily perform CRUD operations against RESTful APIs for example, but you can also easily define your own.
Service Adapters
ServiceAdapters take care of translating requests to a format accepted by the type(s) of API(s) they are built for. You can use the same application code to interface with different APIs by simply telling a NetworkerClient to use a certain ServiceAdapter subclass.
Requests
You provide instances of (subclasses of) Request to the Networker to perform. A Request encapsulates a certain type of network request, allowing you to pass it certain arguments which it can use to alter the URL to perform the request against, the parameters and headers to send along, the method to perform against the service etcetera.
This setup allows you to work with requests at a very high level. As an example you could define an OAuthTokenRequest which accepts the url of the OAuth token endpoint and the username and password of the user as parameters. The OAuthTokenRequest class can then take care of including your application's credentials, URL-encoding the username and password etcetera without having to do this manually every time you want to perform this type of request.
Middleware
You can register middleware with a networker and specify to which requests, responses and/or thrown errors it should be applied. Middleware can be used to take care of things like including authentication credentials, logging etcetera.
Context
The context module provides functionality for managing application contexts. Front-end applications often have the concept of context(s) in which the user currently resides, the most common example being the current navigation context. This can however also include application-specific context like and order that is being placed.
The context module allows you to manipulate context stacks by pushing and popping context data to/from a certain context, optionally specifying things like an expiration time of a certain context. It can be viewed as a kind of temporary storage at the front-end side.
Loading
The loading module allows you to define named "Loaders" with a corresponding loading state. It integrates into the view layer by providing you with Loader components that you can use to specify what should be displayed while loading and what should be displayed once the loader is completely loaded.
Pagination
The pagination module contains convenience functions for paginating sets of data. It is used by the Datasets module.
Notifications
The notifications module provides functionality for submitting notifications to a notification center, optionally with associated data, actions and duration. It also provides an API for obtaining the currently active notifications for easy displaying in the view layer.
Storage
The storage module provides an abstraction around key-value stores like localstorage. It allows you to use a higher-level interface for storing things like application state and persistent data. You can easily switch to another key-value store for your needs by using a different Storage subclass.
Utils
This module contains various utility functions used throughout the other bitlibs modules.