DOCUMENTATION

   1 DOCUMENTATION
   2 ===============================================================================
   3 Table of contents:
   4
   5     1. Agile Object-Oriented System
   6     1.1 Why? What? How?
   7     1.2 License
   8
   9     2. The system
  10     2.1 Structure
  11     2.2 AOOSModel
  12     2.3 AOOSModule
  13     2.4 AOOSException
  14     2.5 AOOSCore
  15     2.6 settings.php and lang.php
  16
  17     3. The modules
  18     3.1 Developing a module
  19
  20 1. Agile Object-Oriented System
  21 1.1 Why? What? How?
  22 Agile Object-Oriented System(AOOS) is a systems that helps you develop
  23 PHP-applications easily. It is not a fullblown framework like CakePHP or Rails,
  24 but is more like a toolkit, like Qt or MooTools. It provides a bunch of classes
  25 which make it very easy to create new modules without having to worry about
  26 things like storage handling, coupling between modules and so on. AOOS makes it
  27 very easy to have one part doing only what it should and in that way implement
  28 portable system in which only the parts you need are included. And this is also
  29 the philosophy of AOOS. A module should only perform one tasks, not do many
  30 things. Having this in mind results in cleaner and more maintainable code which
  31 is a Good Thing(tm). Another positive side of AOOS is that it is very
  32 transperant. You don't need to know all the details of the system as long as you
  33 understand the basic structure. You don't need to have a black belt in PHP as
  34 long as you understand OOP and a bit of PHP.
  35 So how would you get AOOS? First, if you havn't installed Git on your computer,
  36 do it. Git is a revision control system and all AOOS code is contained within a
  37 git repository. When you have Git installed clone the repository from
  38 http://repo.or.cz/r/AOOS.git and that's it! You are ready to start hacking,
  39 although it might be a good idea to the rest of this document ;)
  40
  41 1.2 License
  42 The license under which AOOS should released, hasn't been decided yet but it
  43 will probably be BSD.
  44
  45
  46 2. The system
  47 2.1 Structure
  48 AOOS has a very simple structure. It consists of seven .php-files in the root
  49 directory and three directories which might contain other .php-files or
  50 directories. The structure looks like this:
  51
  52 AOOS/
  53  |
  54  |-- AOOSCore.php
  55  |
  56  |-- AOOSException.php
  57  |
  58  |-- AOOSModel.php
  59  |
  60  |-- AOOSModule.php
  61  |
  62  |-- index.php
  63  |
  64  |-- lang.php
  65  |
  66  |-- settings.php
  67  |
  68  |-- lib/
  69       |
  70       |-- AOOSInterfaces.php
  71       |
  72       |-- AOOSModelConstraints.php
  73       |
  74       |-- AOOSMysqlInterface.php
  75       |
  76       |-- other...
  77  |
  78  |-- modules/
  79       |
  80       |-- Module/
  81           |
  82           |-- Module.php
  83           |
  84           |-- other...
  85       |-- other...
  86  |
  87  |-- tmp/
  88       |
  89       |-- Development files
  90
  91 AOOSCore.php contains the AOOSCore class.
  92
  93 AOOSException.php contains the AOOSException class, and exception classes
  94 derived from AOOSException.
  95
  96 AOOSModel.php contains the AOOSModel and AOOSModelRow classes.
  97
  98 AOOSModule.php contains the AOOSModule class.
  99
 100 index.php is, well.. index.php
 101
 102 lang.php contains translation strings used globally.
 103
 104 settings.php contains settings used globally.
 105
 106 lib/ contains files used in one of the AOOS* classes. AOOSInterfaces.php
 107 contains the declaration of interfaces used, AOOSModelConstraints.php contains
 108 the implementations of model constraints, which are covered later, and
 109 AOOSMysqlInterface.php contains a MySQL-implementation of the storage interface.
 110
 111 modules/ contains all module. Notice that module names must start with a captial
 112 letter and the module directories must contain a file with the name of the
 113 module and the php-extension.
 114
 115 tmp/ are used for temporary files used during development.
 116
 117 2.2 AOOSModel
 118 AOOSModel is the perhaps most important class in the whole system. The class is
 119 an implementation of a table-like model, which consists of AOOSModelRow-objects.
 120 Each model has a column index attached, which defines the names of the columns.
 121 The size of the column index is the column count. For each column a type *must*
 122 be set and each column might have flags and properties set along with a number
 123 of constraints. Type, flags and properties are set through the
 124 setProperties-function which is called like this:
 125
 126     $modelInstance->setProperties("columnName", int columnType, int columnFlags,
 127 int columnProperties);
 128
 129 While types are defined as number 1,2,3 and so on, flags and properties have the
 130 values of 1,2,4,8,16,32 and so on which allows to use bitwise operations on
 131 flags and properties. This means that AOOSMODEL_TYPE_STRING|AOOSMODEL_TYPE_TEXT
 132 is no good while AOOSMODEL_FLAG_FROM_DATABASE|AOOSMODEL_FLAG_UNIQUE makes
 133 perfectly sense.
 134 The difference between flags, properties and constraints might not be clear in
 135 the beginning, but is quite important. Flags are flags and nothing else. They
 136 tell something about the data of a given column like does it come from a
 137 database, are values unique, should columns be shown when using an automated
 138 GUI-creator and so on. They do not change the values of the column at any time.
 139 Properties also tell something about the data of a column, but in contrast to
 140 flags they might actually change the values of the column. A property might
 141 ensure that values don't contain html or that whitespace are trimmed from
 142 beginning and end of value before inserting it into the model or that a given
 143 column contains timestamps which are automatically computed when a new row is
 144 added.
 145 Finally we have constraints which are similar to properties in that they change
 146 data, but opposite properties which do quite simple stuff to data, constraints
 147 can take arguments. This means that you can make a constraints which takes an
 148 argument or two and when a value is inserted into the model, the constraint
 149 evaluates the inserted value based on that value and the arguments it is given.
 150 An example of this is the Length-constraints which takes an integer argument and
 151 crops the inserted value if the length of that value is bigger than the
 152 argument. Another example is the Range-constraints which takes an array of two
 153 integers and makes sure that inserted values are within the range defined by the
 154 two integers given as an argument.
 155 To understand this better, read the documentation and code in AOOSModel.php, it
 156 is quite simple.
 157
 158 AOOSModel also serves as an abstraction layer between you and the database.
 159 Accessing the database is simple, just call setSource() and setTable() in that
 160 order and you are good to go. Data is fetched from the database by calling
 161 populate on the model and insertion, deletion and updating are handled
 162 automatically. All you have to do is to call save() on the model when you have
 163 inserted, deleted or update one or more rows.
 164
 165 Internally the data is stored as an array of AOOSModelRow-objects.
 166 AOOSModelRow-objects are quite handy since they make it easy to handle the data,
 167 already inserted into the model. The find()-function for example returns an
 168 AOOSModelRow-object which contains the data of the first matching row in the
 169 model, and then you are free to manipulate those data. AOOSModelRow implements
 170 the ArrayAccess interface which means that if you have an AOOSModelRow-object
 171 you are able to use the []-operates on it, like:
 172
 173     $rowObject["columnName"] = "newValue";
 174
 175 Also __set() and __get are defined so you can also set and get data using the
 176 "->"-operator, like:
 177
 178     $rowObject->columnName = "newValue2";
 179
 180 vim: textwidth=80