Getting Started

Download / Checkout

To download the latest release of Mozajik Framework, click here. We will soon move to Google Code as a public repository, but if you want access to our SVN repo right now, just contact us at info@mozajik.org.

Installation

To install Mozajik, follow these steps:

Make sure you have PHP 5.3 installed on your server. If not, you can use Zend's free community server
Place downloaded files (unzipped :) ) into a folder which is accessible by your Apache webserver
Enable .htaccess and mod_rewrite for that folder (typically not done so by default)
Add write access to the cache and data subfolders (so the webserver has write access)
You are done! Open the root URL in your browser (ex: http://example.com/mozajik-release/)

Files, Folders, and Paths

Mozajik is a framework based on the Model-View-Controller (MVC) architecture. As such, the files and folders are set up to resemble this structure.

/app - this is your app. most of your work will be performed in this folder.

/app/controller - all the controller files are stored here. mozajik routes requests by searching the names and subfolders in the controller folder.
/app/model - these are the model files - the structure and classes of the tables stored in the database.
/app/view - this is where the HTML (the user interface) goes.

/cache - a system folder used by mozajik to store cache files
/data - a system folder used by mozajik to store data files (photos, file uploads, etc.)
/plugins - you can create or install project-specific plugins here.

/plugins/conf - you can put conf files here which can be loaded into your program or for any template files.
/plugins/fields - here you can define custom fields for use in your models.
/plugins/filters - filters can perform useful actions on template variables. add your own here.
/plugins/lang - language files can be used for localization of templates.
/plugins/lib - you can add custom libraries here.
/plugins/tags - the template system has many built-in tags, but you can add your own here.
/plugins/view - some items (for example fields) will require their own templates. you can place plugin-related templates here.

/site - this is where all your assets (CSS, JS, images, robots.txt, favicon, etc.) should be stored.
/system - the mozajik system files are here. the structure is very similar to your project-specific folders (the ones described above). any system files can be 'overridden' by placing a project-specific version in the appropriate project-specific folder. this makes extending the system VERY easy.

Creating the Hello World! example

The simple way

Mozajik uses controller files to route user requests and view files to display the HTML output.

Find the main() method of the /app/controller/default.ctl.php file. This is where the homepage requests are routed.
Add the line print "hello world!"; to create the most basic version of our example.
Open the base url from your browser and you should see the result!

Using Views and Controllers

A slightly more complex "Hello World" example

So that was a very simple version. Let's make it a bit more complex to demonstrate how Mozajik routes requests and displays templates.

Copy the /app/controller/default.ctl.php file and name it /app/controller/hello.ctl.php.
Open /app/controller/hello.ctl.php, rename the class to zajapp_hello (the class name must always match the file name).
Create a new method in /app/controller/hello.ctl.php by the name of world().
Add the line $this->zajlib->template->show('helloworld.html'); to the world() method.
Now create a file /app/view/helloworld.html and write Hello world! in the file.
Open http://yourbaseurl/hello/world/ in your browser to see the result!

Let's see what happens here when the request is made. First, Mozajik parses the request /hello/world/ and tries to search for /app/controller/hello.ctl.php. In this case, it finds the file, so it calls the world() method within that file. (Note: If either the file or the method is not found, Mozajik will continue searching for other possible combinations, but more about that later...)

So, the request is routed to /app/controller/hello.ctl.php / world(); where the code tells Mozajik to open up the helloworld.html template from the /app/view folder. The template is compiled and cached and then displayed. (Of course, in this example there is not much to compile in the template:)).

Enabling MySQL

Although certain applications will work without a database, most of your more complex creations will require MySQL. Follow these steps to enable MySQL support in Mozajik (which is disabled by default):

Create a new user/password and a new database in MySQL. Make sure the user has full access to the database. You can use phpmyadmin (how?) or another tool.
Open /site/index.php. This file contains all sorts of default settings for your Mozajik project.
Find the section database access and modify the settings as shown below (using the same details you just set up in the database).

$zaj_mysql_enabled = true;
$zaj_mysql_server = "localhost";
$zaj_mysql_user = "-your-chosen-username-";
$zaj_mysql_password = "-your-chosen-password-";
$zaj_mysql_db = "-your-chosen-database-name";
$zaj_mysql_ignore_tables = array();

You are now ready to use the database with Mozajik. Only two more steps to create the default Models in the database:

Open up the Mozajik update menu at http://yourbaseurl/update/
Click "database model update" to run the automatic database updater (IMPORTANT: You may get an error in the BETA version. Just run the update again - by reloading it - and it should work fine the second time!)

The default tables have now been created!

Using Models

Confusing introduction :)

In Mozajik's Model-View-Controller (MVC) architecture, database objects (rows in the database) are created, edited, and deleted using zajModel classes. Each zajModel class is contained in a model file (in the /app/model/ folder) and each class corresponds to a single table in the database. When you create new model objects, each will be a single row in its table. Confusing? Let's look at the default example in detail.

In practice

Open the file /app/model/sample.model.php. This is where the Sample model class is defined. Notice that it has a model definition method (__model()) where there are three defined fields: name, description, and photos.

When you ran the update a few minutes ago, Mozajik read this file and saw that it needs to create a table named sample in which there should be three fields. Now go over again to phpmyadmin and see the database that has been created! (Note: there are some automatic fields and photos is actually a manytoone field, so you won't see it in the sample table)

Now let's try an exercice:

Rename sample.model.php to something more useful. Try book.model.php. Make sure to also rename the class to Book (on line 9).
Books have a "title", not a "name", so rename the first field (line 18) like this: $f->title = zajDb::name();. Do not change zajDb::name(); because that is the field type - more about that in the next section (Model syntax).
The book's description is probably relatively long (not a single line), so let's change the second field's type (line 19) like this: $f->description = zajDb::textarea();. Again, you can find more info about available field types in the next section (Model syntax).
Let's also add a genre after photos as a new line: $f->genre = zajDb::select(array('Novel', 'Comedy', 'Short-story'));

When finished, your model defintion file /app/model/book.model.php should look like this:

class Book extends zajModel {
	
	/**
	 * __model function. creates the database fields available for objects of this class.
	 * 
	 */
	static function __model(){
		/////////////////////////////////////////
		// begin custom fields definition:
			$f->title = zajDb::name();
			$f->description = zajDb::textarea();
			$f->photos = zajDb::photos();
			$f->genre = zajDb::select(array('Novel', 'Comedy', 'Short-story'));
		// end of custom fields definition
		/////////////////////////////////////////		

		// do not modify the line below!
			$f = parent::__model(__CLASS__, $f); return $f;
	}
	
	......

Since we have modified database models, we now need to tell Mozajik to update the database! We can do this by running the same update process as before:

Open up the Mozajik update menu at http://yourbaseurl/update/
Click "database model update" to run the automatic database updater (IMPORTANT: You may get an error in the BETA version. Just run the update again - by reloading it - and it should work fine the second time!)
After it is done, click "show" to view the details of manual changes you must perform (deleting the now unused fields and the unused Sample table). (This step is optional. Mozajik will work with unused fields still present!)

Now check phpmyadmin again, and note the changes! The latest update has created a new table with the fields you defined. As before, there will be some default fields (id, time_create, ordernum, etc.) - more about this in the next section. Also, photos will be missing, since it is a onetomany field stored in another table (in table Photos to be exact :).

You have successfully created a model representing a Book! When you add new books to the database (Book objects), new rows will be created in this table! So let's now see a more detailed description of model syntax.