Version:
1.8.43 (Main Root Server)
License:
This code is completely open and free. You may access it by visiting the BMLT Project Site. It is not sold, and no money will come back to the original creator. It is a gift.

INTRODUCTION

The Basic Meeting List Toolbox is a PHP framework that is designed to be the entire meeting list system for an NA Service Body. It is comprised of a fairly involved "Main Server," and substantially simpler "Satellite Servers" that communicate with each other using standard HTTP protocols (a REST interface, for nerds, because we have to give new names to old concepts, and feel that we discovered something new).

The main server contains the meeting list database, and is where the database is administered, but the satellite servers can be installed on other sites that connect to the main server via the Internet. The satellite servers can be easily customized, as can the main server, so each site can retain its own character, while presenting a unified look-and-feel.

HowDoesItWork.png


Figure 1: The Overall Architecture of the BMLT

The BMLT relies heavily on Google Maps, which provides powerful tools for programmers.

The idea is to present a natural, highly-usable and extremely consistent user experience to finding NA meetings.

The BMLT is designed to scale well. It does not rely on only one database. It uses a database abstraction layer to allow a number of different database engines to be used.

The BMLT main server requires PHP 5.1 or greater, but the satellite servers can use older versions of PHP.

It is designed so that many different types of browsers can use the system. The more capability the browser has, the more useful and interactive the user experience.

LICENSE

BMLT is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

BMLT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this code. If not, see the GNU General Public License.

TECHNICAL DETAILS

The Basic Meeting List Toolbox is a system designed to store, transmit, format and share NA meeting data. It uses an MVC pattern, with the server classes representing the Model, various interpretation files representing the Controller, and the rendered XHMTL / XML / CSS / JavaScript representing the View.

It will have a number of different View layer implementations, including basic HTML, WML2, RSS, JSON and XML.

The whole idea of the BMLT is to abstract a necessarily complex infrastructure behind a very easy to use, and easy to customize "front end."

The BMLT is designed to be a federated system, with multiple servers addressing localized needs, and providing a common interface for visitors and aggregators.

It is designed to be easily localized for different languages and script systems.

DOCUMENTATION AND CONFIGURATION

The BMLT is designed, primarily, as an SDK (Software Development Kit) and an API (Advanced Programming Interface). It is delivered as a standalone system, but has been designed in a fashion that allows easy integration into existing systems.

This documentation is the API documentation. It describes the internal PHP and JavaScript code of the BMLT.

Other documentation, for usage and administration, will be provided separately.

TechStructure.png


Figure 2: The Basic MVC Architecture of the BMLT

NOTE TO OO ADDICTS

PHP is a poopy object-oriented language. Learn to accept the fact and move on. The BMLT uses objects to handle complexity (Like a database model), but the lions' share of the code in this project is procedural. A lot of the JS is OO, but even that is carefully controlled, as OO is not necessary for the one-trick ponies we use in most of our JS code.

Procedural PHP is MUCH faster and less bug-prone than OO. It is entirely possible to model an MVC pattern in non-OO code, and this system proves it. There are some folks who think that you need to have MVC class hierarchies to have a "real" MVC pattern. These folks seem to have a hard time grasping the concept of "pattern."

Note the heavy reliance on objects and classes in this description.

We're sure that PHP's OO capabilities will improve over time (it already has, by the time of this writing), so maybe a future rewrite might see more OO being introduced.

Another consideration is maintainability. A lot more people are comfortable with procedural code than they are with OO. Most of the code that will require modification in the future (the Controller layers) is written in procedural code. The Model doesn't need much work, and has a lot of complexity, so it directly benefits from OO.

However, the system is complex and involved. It needs as much performance as possible, and it won't get that from excessive OO. There's too many examples of sluggish, bug-ridden OO PHP "camels" out there as it is.

STORAGE AND IMPLEMENTATION

The database format uses a main table to represent the few "key" attributes of each meeting, and then two ancillary tables to contain key/value sets of additional data. This makes for a tremendously flexible system. It's known as the "KVP" (Key/ValuePair) Pattern.

The KVP tables are the *_comdef_meetings_data and the *_comdef_meetings_longdata tables.

The *_comdef_meetings_data table will contain all of the extra meeting data in most implementations. It will hold integer, floating-point or strings less than 256 bytes in length.

The *_comdef_meetings_longdata table is only there in the case that some Service Bodies may wish to associate extra-long (Greater than 255 bytes) data with meetings. In practice, this should be avoided, as it will lead to large databases and reduced performance.

It stores information about Service Bodies and users (with login credentials). This allows very easily-specified security to control changes, and to specify information from Service bodies (Such as "Find all the meetings in the XXX Region").

It stores changes to various objects as "before" and "after" "snapshots," and has the ability to "rollback" to a state before the change.

BMLT uses five different types of objects. These are all stored in the database, and four of them are editable by the user (change records cannot be directly edited).

These are managed and abstracted by the Model layer, which consists of a set of classes that model the database.

The change recording feature is very powerful. Entire objects are saved as "before" and "after," and these can be used to give detailed reports and to restore objects to older versions. Due to the fact that each and every change is recorded, changes for meetings are removed after a preset number of changes have been made. This reduces the impact on the amount of data in the database.

Service Bodies are assigned to entities such as ASCs and RSCs, but are really used within the BMLT as "groups," allowing fine control over the authority of logged-in users. The Service Body system allows a hierarchy, so RSCs can have editors that can edit all of the meetings in all of the ASCs within that RSC, but each ASC can only edit their own meetings, etc.

SQLSchema.gif


Figure 3: The BMLT Database Schema

LOCALIZATION

The BMLT is designed to handle multi-language systems. Every single string that is displayed comes from a language directory. New languages can be added by creating a new directory, and localizing the strings in the directory.

OUTPUT

The View is designed to allow general users as much accessibility as possible. You don't have to have a particularly modern browser or JavaScript, etc. to use the BMLT, but administrators need to have fairly modern browsers that can handle AJAX.

The BMLT is provided as a "top to bottom" package that will work "out of the box." However, it is designed to be "skinned" or customized. All the CSS is low-specificity CSS 2.1, the markup is extremely well-formed to ensure XHTML 1.0 Strict / XHTML 1.1 compliance, and it will validate WAI AAA (Priority 3).

The meeting search result lists are displayed as tabular data (table elements), but everything else is done with block-level elements.

Google Maps are integral to the system. Meeting locations are described by a long/lat pair, not a street address. The address is actually very flexible, so the combination allows tremendous flexibility and accuracy in presenting a meeting location.

Meeting data are kept in an extremely flexible manner. There are a few "core" fields, but most of the meeting data are kept as key/value pairs in separate tables, which allows tremendous flexibility. A server can be set up to allow only certain fields, and the system does not have to rely on these fields.

CUSTOMIZATION

The BMLT is designed to allow easy customization via CSS. The system is written using low-specificity CSS. This means that it is fairly straightforward to write CSS of a higher specificity to alter the presentation. In addition, the BMLT uses a "theme" system for the root server, so new "themes" can be written.

ADMINISTRATION

The BMLT was designed to provide highly secure, highly usable administration. The administration interface is designed to use a great many modern features of Web clients, such as AJAX, so any browser used for administering the system must be a modern browser, capable of running active content. However, a user of the system can have an old browser, or one with active content disabled, and the BMLT will tailor its output to provide the richest experience possible.

SECURITY

Security of administration is provided in a number of ways:

RELEASE NOTES:

 All Classes Files Functions Variables Enumerations