mescaline 0.5

mescaline is a PHP web application and framework which makes data stored in databases available to users.
mescaline is a PHP web application and framework which makes data stored in databases available to users.

The interfaces for viewing and editing the data are created without requiring any coding or configfile editing using a wizard. You most likely don't need any administrative rights on the webserver to install mescaline.

Requirements:

It should work on pretty much every os, tested and developed on linux.
PHP5, not sure about oop support in php4.
MySQL, i guess most versions work.
A webserver (Apache).
In case you want to use the wizard, the webservers needs the right to write files.

Installation:

1) move the whole "mescaline" folder into the root of your webserver hierarchy.
2) if you want to use the wizard for creating forms, you should assign the ownership of the "mescaline/context" directory to the web-server user.
3) protect the "mescaline/includes" and "mescaline/context" folders from direct access by users, otherwise they will be able to read the login information to the mysql server in plaintext. included in the distribution are .htaccess files which deny direct access from the webbrowser.
4) you may also deny access to the "mescaline/wizard" folder by default, and allow it, while using the wizard.

Usage:

0) terms with an attached * are explained in 3) glossary.

1) creation of contexts.

mescaline build its tables and forms with the information stored in context files. the context files can be created using the wizard or manually in a script.

1.1) using the wizard.

the wizard is started by calling /mescaline/wizard/index.php.

- enter the information needed to access the database*.
- if the database* could be accessed you select the table you want to create forms for.
- the idfield* is usually the first field in a table of the type integer.
- when you select the fields, it is important to include all fields which are marked as required *if* you want the users to be able to create new entries* in the form.
- after selecting the fields you can choose to assign (and remove) references* to fields.
- to add references* you have to choose table & idfield* again for the referenced table.
- the reference* display field*, is the column* you want to be displayed in the table and edit forms dropdown menus.
- The autogenerated SQL query for references* will fetch all *entries of the referenced table and display them in the edit forms dropdown menu. To further narrow this selection, you can customize the SQL query.
- When finished, the new context is available in "mescaline/context/.context".

1.2) manual creation.

the manual creation requires you to write a php script on your own, which builds the context. you have to use classes in the include path.

ini_set('include_path', '/mescaline/includes/');
require_once('table.inc');
require_once('idfield.inc');
require_once('boolfield.inc');
require_once('listfield.inc');
require_once('reference.inc');
require_once('database.inc');
require_once('context.inc');

1.2.1) create a table object.

the table names have to be actual names in the database*.

$table = new Table();

1.2.2) create database object.

$database = new Database(, , , );

1.2.3) build the field array.

the names of the fields* have to be the correct column* names of the tables.

$fields = array();

1.2.3.1) add the idfield* first.

$fields[] = new IDField();

1.2.3.2) add default fields (if there are any).

$fields[] = new Field();

or for optional fields

$fields[] = new Field(, true);

1.2.3.3) add bool fields (if there are any).

$fields[] = new BoolField();

or for optional fields

$fields[] = new BoolField(, true);

1.2.3.4) add list fields (references*, if there are any).

1.2.3.4.1) create reference table.

$referencetable = new Table();

1.2.3.4.2) set id field from the referenced table.

$referenceidfield = new IDField();

1.2.3.4.3) set the field to be displayed in table and edit form from the referenced table.

$referencedisplayfield = new Field();

1.2.3.4.4) create reference object.

$reference = new Reference($referencetable, $referenceidfield, $referencedisplayfield);

1.2.3.4.5) create listfield and its query.

$listfield = new ListField(, $reference);

or for an optional field

$listfield = new ListField(, $reference, true);

for the reference* field you can either use a generated query

$listfield->query = $listfield->buildQuery($database);

or use your own

$listfield->query = "";

add the listfield to the fields array.

$fields[] = $listfield;

1.2.4) assign the fields to the table.

$table->fields = $fields;

1.2.5) create context object and serialize it to the disk.

$context = new Context(, $table, $database);
$s = serialize($context);
$fp = fopen($context->name . ".context", "w");
fputs($fp, $s);
fclose($fp);

1.2.6) move the context file.

there should be a context file now, which can used after it has been moved into "mescaline/context".

2) calling the forms

the forms are started by calling /mescaline/index.php?context=

3) glossary

- column/field: kind of used as synonyms here. however the correct meaning for column would likely be the structural entity in a table layout, while a field would be a single element of a column within a row*.
- database: currently this is refering to MySQL exclusively.
- entry/row: an entry means a table row here.
- idfield: a special column in a table which identifies a row. no value in this column should exist twice. usually the idfield is of type integer and increments itsself automatically.
- reference: you can reference the content of other tables in a table. the referencing table has a column, which contains the idfields* of the referenced entries in the other table. the referenced entry is displayed in the table view and in the edit forms there appears a dropdown menu, which contains only the values stored in the referenced table.

4) creating new field types.

the following steps describe how to enhance mescaline by added custom fields. refer to ListField, BoolField & StringField implementations for examples.

4.1) create the model class.

create a class Field with the filename "includes/field.inc" derived from class Field.

4.2) autodetection.

if you want the class to be autodetected in the wizard you have to put a handler for it in the class Database. Add "require_once("field.inc");" to the top of "includes/database.inc". Add a handler to the Database::columns method.

4.3) create the view class.

create a class WebField with the filename "includes/webfield.inc" derived from class WebField.

4.4) handle it in the web context.

put "require_once("webfield.inc");" to the top of "include/webcontext.inc". Add a line in the WebContext::createWebFields() method for your custom Field Class.

What's New in This Release:

after editing you will return to a sorted list and the correct location.
implemented a more consequent MVC pattern.
id field isn't visible in the editor anymore.
fixed display of big tables.
possible to hide fields.
cleaned up interface a bit.
fixed a bug where empty (NULL) optional fields where created with a value.
improved sql error handling.
improved handling of varchars/strings.

last updated on:
July 31st, 2008, 23:12 GMT
price:
FREE!
developed by:
Magnus Kulke
license type:
GPL v3 
category:
ROOT \ Internet \ HTTP (WWW)

FREE!

In a hurry? Add it to your Download Basket!

user rating 10

UNRATED
3.6/5
 

0/5

Add your review!

SUBMIT