Dave Keen

Flextrine 0.6.5 released

devdave — Fri, 20 Aug 2010 12:46:30 +0000

Another released of Flextrine! Since 0.6.1 there have been a number of changes to the Flextrine core. The entity merging algorithm has been altered to take better advantage of Doctrine 2 merging giving us a hefty performance boost (thanks for Benjamin Eberlei at Doctrine for pointing this out), the requirement to use $_explicitType in Doctrine entities has now been removed, bootstrapping and configuration code has been extended and neatened up and there have been numerous bug fixes at all levels of the application.

My continued thanks to the community for their help in testing and using Flextrine!

Flextrine on Android 2.2 (Froyo)!

devdave — Tue, 03 Aug 2010 16:16:37 +0000

Android 2.2 got rolled out for my HTC Desire this afternoon, and I am both pleased and surprised to report that Flextrine runs on it without any problems!

Flextrine Tutorial – CRUD in a simple Flex 4 address book: Conclusion

devdave — Tue, 03 Aug 2010 13:18:02 +0000

Introduction
Setting up the server
Creating the entities
Creating the database schema
Loading the entities
Creating new entities
Deleting entities
Updating entities
Conclusion

I hope that this tutorial has given you some insight into the power of Flextrine. In fact there are many areas of Flextrine that we didn’t touch on here including one to one and many to many associations, lazy loading, DQL, fetch joins, custom PHP functions and more – check the documentation for more details.

Both Flextrine and Doctrine 2 are currently in beta; the planned release date for both products is 1st September 2010 by which time I would hope to be able to confidently pronounce Flextrine as stable. That’s where you come in! If you find any issues in Flextrine please log them at http://code.google.com/p/flextrine2/issues/list and help me to make Flextrine the best Flex ORM library there is

Flextrine Tutorial – CRUD in a simple Flex 4 address book: Updating entities

devdave — Tue, 03 Aug 2010 13:01:52 +0000

Introduction
Setting up the server
Creating the entities
Creating the database schema
Loading the entities
Creating new entities
Deleting entities
Updating entities
Conclusion

Once an entity is in an EntityRepository (either because it was loaded from the database or it was persisted) it is known as a MANAGED entity. This means that Flextrine will constantly watch the entity to see if anything changes, and if so will mark the entity for updating on the next flush().

Therefore updating entities is extremely simple – as long as the entity is managed there is literally nothing to do

Lets create an editor for the ContactGroups (in the same directory as Main.mxml):

ContactGroupEditor.mxml

"1.0" encoding="utf-8"?>
"http://ns.adobe.com/mxml/2009"
         xmlns:s="library://ns.adobe.com/flex/spark"
         xmlns:mx="library://ns.adobe.com/flex/mx">
    
    

        import vo.ContactGroup;
        
        [Bindable]
        public var contactGroup:ContactGroup;
        
        ]]>
    
    
    "150" width="100%" height="100%">
        
        "Edit group" />
        
        "Name">
            "@{contactGroup.name}" />
        
        
    
    


The component takes a contactGroup and provides a TextInput that edits its name attribute using Flex 4 two-way databinding. In fact you need to be careful with two-way databinding on some components (e.g. DateChooser) as it can cause unnecessary updates, but it works fine for Spark’s TextInput.

Now we need to add the ContactGroupEditor into Main.mxml:

…
"100%" height="100%">
            
            "{tree.selectedItem as ContactGroup}" enabled="{tree.selectedItem is ContactGroup}" />
…

And that’s it for the group editor. When we select a ContactGroup in the tree, the ContactGroupEditor becomes enabled, and the selected item is passed to the editor’s contactGroup attribute. Flex updates the contactGroup’s name attribute when we change it in the editor and Flextrine automatically picks up on the change and marks the entity for updating. On the next flush() the changes will be written to the database.

Now for the ContactEditor.

ContactEditor.mxml

"1.0" encoding="utf-8"?>
"http://ns.adobe.com/mxml/2009"
         xmlns:s="library://ns.adobe.com/flex/spark"
         xmlns:mx="library://ns.adobe.com/flex/mx">
    
    

        import org.davekeen.flextrine.orm.EntityManager;
        import vo.ContactGroup;
        import vo.Contact;
        
        [Bindable]
        public var contact:Contact;
        
        ]]>
    
    
    "150" width="100%" height="100%">
        
        "Edit contact" />
        
        "Name">
            "@{contact.name}" />
        
        
        "Telephone number">
            "@{contact.telephoneNumber}" />
        
        
        "Birthday">
            "{contact.birthday}" change="contact.birthday = event.currentTarget.selectedDate" />
        
        
        "Group">
            "{EntityManager.getInstance().getRepository(ContactGroup).entities}"
                            selectedItem="{contact.contactGroup}"
                            change="contact.setContactGroup(event.currentTarget.selectedItem);"
                            labelField="name" />
        
        
    
    


The contact editor is marginally more complicated, but still fairly simple. A few points:

Note is that as mentioned above we don’t use two-way databinding on any component apart from TextInput.
Although it is perfectly legal to retrieve the singleton EntityManager in the ContactEditor as we have done in the DropDownList dataProvider, in a real application we probably wouldn’t do this as it breaks encapsulation. I’ve done it here for the sake of simplicity

Finally we need to add the editor to Main.mxml:

…
  
"100%" height="100%">
    
    "{tree.selectedItem as ContactGroup}" enabled="{tree.selectedItem is ContactGroup}" />
    "100%" />
    "{tree.selectedItem as Contact}" enabled="{tree.selectedItem is Contact}" />
…

An that’s it! A simple but fully functioning, database aware Flex application.

And now, the thrilling conclusion.

Flextrine Tutorial – CRUD in a simple Flex 4 address book: Deleting entities

devdave — Tue, 03 Aug 2010 13:00:31 +0000

Introduction
Setting up the server
Creating the entities
Creating the database schema
Loading the entities
Creating new entities
Deleting entities
Updating entities
Conclusion

Deleting entities is very simple. Update the delete button MXML tag to call onDeleteClick() when clicked, and to only be enabled if there is a selection in the tree.

   1: "Delete" click="onDeleteClick()" enabled="{tree.selectedItem != null}" />

And implement the onDeleteClick() method:

private function onDeleteClick():void {
    em.remove(tree.selectedItem);
    
    if (tree.selectedItem is Contact)
        tree.selectedItem.contactGroup.removeContact(tree.selectedItem);
    
}

Notice that we maintain the bi-directional association if the deleted item is a contact by removing it from its associated contactGroup.

And that’s it :) The entity will be removed from its entity repository (updating the tree via databinding) and on the next flush() it will be removed from the database.

The final step in our little address book is to allow the user to update existing entities.

Flextrine Tutorial – CRUD in a simple Flex 4 address book: Creating new entities

devdave — Tue, 03 Aug 2010 12:59:16 +0000

Introduction
Setting up the server
Creating the entities
Creating the database schema
Loading the entities
Creating new entities
Deleting entities
Updating entities
Conclusion

To add new entities to the repository we use the EntityManager.persist() method. Let’s link up the Add group and Add contact buttons and get them to create and persist new entities.

Modify the Button MXML tags for Add Group and Add Contact so that they call addNewGroup() and addNewContact() when they are clicked. We can only add contacts within a group, so we will also make sure that you can only click addNewContact() if a ContactGroup is selected in the tree.

   1: "New group" click="onNewGroupClick()" />
   2: "New contact" click="onNewContactClick()" enabled="{tree.selectedItem is ContactGroup}" />

Firstly we’ll make the onNewGroupClick() function. It really is as simple as creating a new ContactGroup(), assigning some properties and calling EntityManger.persist().

private function onNewGroupClick():void {
    var contactGroup:ContactGroup = new ContactGroup();
    contactGroup.name = "New group";
    em.persist(contactGroup);
    
    // Select the new ContactGroup in the tree
    tree.selectedItem = contactGroup;
}

And that’s it :) When the user clicks Add Group a new ContactGroup entity is created, a name is assigned to it and it is persisted to Flextrine. This means that the new contactGroup is added to entities in the ContactGroup entity repository (triggering databinding and updating the tree), and the new entity is marked for insertion into the database. Note that Flextrine doesn’t actually do anything with the database when we call persist, it just notes that we need to insert it on the next flush – we’ll worry about flushing after we have created onNewContactClick().

onNewContactClick() is very similar:

private function onNewContactClick():void {
    var selectedContactGroup:ContactGroup = tree.selectedItem as ContactGroup;
    
    var contact:Contact = new Contact();
    contact.name = "New contact";
    
    contact.contactGroup = selectedContactGroup;
    selectedContactGroup.contacts.addItem(contact);
    
    em.persist(contact);
    
    // Select the new Contact in the tree
    tree.selectedItem = contact;
}

There is one important subtlety here. Just like JPA, Flextrine does not automatically handle both ends of a bi-directional association, and its the developer’s job to manage the domain model. Let’s talk about this in more detail. Our association between ContactGroup and Contact is OneToMany bi-directional. This means that a ContactGroup has many Contacts, and a Contact has one ContactGroup. Therefore when we create a new Contact we need to do the following:

Set newContact.contactGroup to selectedContactGroup
Add newContact to selectedContactGroup.contacts

In this way we maintain both sides of the bi-directional association. If we were to change the contactGroup of an existing contact we would need to add another step:

Remove contact from its current contactGroup.contacts
Set contact.contactGroup to selectedContactGroup
Set newContact.contactGroup to selectedContactGroup

Let’s encapsulate this functionality within Contact and ContactGroup by creating ContactGroup.addContact, ContactGroup.removeContact and Contact.setContactGroup. These are called association helpers and its very likely that future versions of Flextrine will auto-generate these for you. However, for now we’ll code them by hand.

ContactGroup.as

package vo {
    import mx.collections.ArrayCollection;
    
    [RemoteClass(alias="vo/ContactGroup")]
    [Entity]
    public class ContactGroup extends ContactGroupEntityBase {
        
        public function get children():ArrayCollection {
            return contacts;
        }
        
        public function addContact(contact:Contact):void {
            contact.setContactGroup(this);
        }
        
        public function removeContact(contact:Contact):void {
            contacts.removeItemAt(contacts.getItemIndex(contact));
        }
        
    }
  
}

Contact.as

package vo {
    import mx.collections.ArrayCollection;
    
    [RemoteClass(alias="vo/Contact")]
    [Entity]
    public class Contact extends ContactEntityBase {
        
        public function setContactGroup(contactGroup:ContactGroup):void {
            if (this.contactGroup) this.contactGroup.removeContact(this);
            this.contactGroup = contactGroup;
            if (contactGroup) contactGroup.contacts.addItem(this);
        }
        
    }
  
}

And now we can change onNewContactClick() to simply read:

private function onNewContactClick():void {
    var selectedContactGroup:ContactGroup = tree.selectedItem as ContactGroup;
    
    var contact:Contact = new Contact();
    contact.name = "New contact";
    selectedContactGroup.addContact(contact);
    em.persist(contact);
    
    // Select the new Contact in the tree
    tree.selectedItem = contact;
}

These complications are only relevant for bi-directional association. If, for example, ContactGroup has many Contacts, but ContactGroups don’t know anything about their Contacts this would be a ManyToOne uni-directional association and all we would need to do would be to set contactGroup on the Contact to maintain the domain model.

Flushing

At this point nothing has actually been written to the database - all that has happened is that Flextrine has marked our persisted objects for insertion. In order to tell Flextrine to execute its queue of operations against the database we use EntityManager.flush(). This will create new entities, update changed entities and delete removed entities in the database.

One thing to consider is if for some reason the flush fails (for example if we were to try and delete a ContactGroup without deleting its child Contacts) the client will be out of sync with what is in the database so we are going to add a responder to flush() that will simply reload all the data fresh from the database in case of an error.

Note that once the flush() has completely successfully our persisted ContactGroup and Contact entities will have their id fields automatically updated with the auto increment id from the database.

Update the Save button to call onSaveClick():

   1: "Save" click="onSaveClick()" />

And implement the method and the responders:

private function onSaveClick():void {
    enabled = false;
    
    em.flush().addResponder(new AsyncResponder(onSaveResult, onSaveFault));
}
  
private function onSaveResult(result:Object, token:Object):void {
    enabled = true;
}
  
private function onSaveFault(result:Object, token:Object):void {
    enabled = true;
    
    em.clear();
    em.getRepository(ContactGroup).loadAll();
}

Notice that if there is an error we call EntityManager.clear() before reloading the data – this empties out all the current entities in the repositories.

In the next section of the tutorial we’ll see how we can delete entities.

Flextrine Tutorial – CRUD in a simple Flex 4 address book: Loading the entities

devdave — Tue, 03 Aug 2010 01:51:31 +0000

Introduction
Setting up the server
Creating the entities
Creating the database schema
Loading the entities
Creating new entities
Deleting entities
Updating entities
Conclusion

In FlashDevelop or Flash Builder create a new Flex 4 project and add the Flextrine client side library (in flextrine/src of the Flextrine download) to the classpath of your project. Alternatively you can use the compiled flextrine/bin/flextrine.swc. Now return to the Flextrine manager and click on GENERATE AS3 CLASSES. You will be prompted to download a zip file – extract its contents into the src directory of your project. You should now have AS3 versions of vo.ContactGroup and vo.Contact for use in your Flex application.

For reference, here are a few screenshot of what we will be working towards. The tree on the left will show the groups and contacts, and the area on the right will have the group editor at the top and the contact editor below. We will also have some buttons to create, delete and save contacts and groups.

Create the Main.mxml entry class

We will begin by creating the Main.mxml entry class for our application. To start with we will just create the basic MXML Application with a creationComplete event listener that configures Flextrine’s central class – the EntityManager. For our simple application the only configuration that is required is to set the URL of gateway.php in the Flextrine server side component – in this case http://localhost/contacts/gateway.php.

"1.0" encoding="utf-8"?>
"http://ns.adobe.com/mxml/2009"
               xmlns:s="library://ns.adobe.com/flex/spark"
               xmlns:mx="library://ns.adobe.com/flex/mx"
               xmlns:local="*"
               creationComplete="creationComplete()">
    
    

        import org.davekeen.flextrine.orm.Configuration;
        import org.davekeen.flextrine.orm.EntityManager;
        
        private var em:EntityManager;
        
        /**
         * Initialize the Flextrine EntityManager, set the dataprovider of the tree and load the ContactGroups.
         */
        private function creationComplete():void {
            // Setup the entity manager
            var configuration:Configuration = new Configuration();
            configuration.gateway = "http://localhost/contacts/gateway.php";
            
            em = EntityManager.getInstance();
            em.setConfiguration(configuration);
        }
        
        ]]>
    
    


Now we’ll add the GUI. We’ll add a Flex Tree on the left with id tree, along with the buttons and the layout.

"1.0" encoding="utf-8"?>
"http://ns.adobe.com/mxml/2009"
               xmlns:s="library://ns.adobe.com/flex/spark"
               xmlns:mx="library://ns.adobe.com/flex/mx"
               xmlns:local="*"
               creationComplete="creationComplete()">
    
    

        import org.davekeen.flextrine.orm.Configuration;
        import org.davekeen.flextrine.orm.EntityManager;
        
        private var em:EntityManager;
        
        /**
         * Initialize the Flextrine EntityManager, set the dataprovider of the tree and load the ContactGroups.
         */
        private function creationComplete():void {
            // Setup the entity manager
            var configuration:Configuration = new Configuration();
            configuration.gateway = "http://localhost/contacts/gateway.php";
            
            em = EntityManager.getInstance();
            em.setConfiguration(configuration);
        }
        
        ]]>
    
    
    "100%" height="100%">
        
        "100%">
            "tree" width="100%" height="100%" />
        
        
        "100%" height="100%">
            
            
            "100%" />
            
            "100%" />
            
            
            "100%" horizontalAlign="center">
                "New group" />
                "New contact" />
                "Delete" />
                "Save" />
            
        
    
    
  


Loading the contacts into the tree

Now its time to load some data into the tree. Obviously at this point there isn’t any data to load so for the moment we’ll manually add some into the database so we have something to see. Execute the following SQL against the contacts database to create some test data. This creates two groups and three contacts, just like in the screenshots at the top of this section.

INSERT INTO `contact` (`id`,`name`,`telephoneNumber`,`birthday`,`contactGroup_id`) VALUES 
 (1,‘Arthur’,‘01332 823636′,‘1976-01-12′,2),
 (2,‘Mum’,‘07884 763623′,‘1976-01-13′,1),
 (3,‘Peter’,‘0131 827 3625′,‘1977-12-06′,2);
  
INSERT INTO `contactgroup` (`id`,`name`) VALUES 
 (1,‘Family’),
 (2,‘Friends’);

At this point we should talk about the concept of Flextrine’s entity repositories. Every entity in your application has its own EntityRepository, so for our application we have one EntityRepository for ContactGroup and one for Contact. Entity repositories perform a number of functions:

First and foremost entity repositories provide local storage for your entities. Each EntityRepository has an attribute called entities which is an ArrayCollection containing the entities currently in existence in your application.
Secondly entity repositories make sure that there is only ever one instance of a particular entity in existence at any one time.
Finally entity repositories watch their entities for changes and mark them for updating when they change.

Add the following lines to the end of creationComplete() remembering to add import vo.ContactGroup to the top of the script tag.

   1: tree.dataProvider = em.getRepository(ContactGroup).entities;
   2: em.getRepository(ContactGroup).loadAll();

The first line sets the entities of the ContactGroup EntityRepository as the dataProvider of the tree. Obviously at this point there are no entities in the ContactGroup repository, but Flextrine is very careful to respect Flex databinding throughout its lifecycle so in fact it doesn’t matter that entities is currently empty. Any Flex component bound to the entities will automatically update themselves when the repository changes with no extra work required.

The second line calls the loadAll() method on the ContactGroup repository. As you would expect this loads all the ContactGroups into the ContactsGroup repository and Flex databinding will take care of updating the tree once the load is complete. By default Flextrine runs in EAGER mode, which means that when loading entities it will follow all associations and load any linked objects, so in fact loading the ContactGroups will also load all the Contacts. Flextrine also supports LAZY loading which won’t automatically follow associations and requires you to to explicitly request unitialized entities; see Loading Associations for more details.

If you now run the application it will look like this.

We can see that the two ContactGroups are loading from the database and that Flex databinding has updated the tree automatically to reflect the loaded entities. Unfortunately the tree doesn’t realise that it should be showing contacts as children of the contact groups, so we need to explicitly tell it so by adding a children attribute to ContactGroup. Flextrine allows you to add logic to your entities by seperating Flextrine specific code into an ‘EntityBase’ class, and then creating an empty main entity class which you can ammend. The idea behind this is that if you later update your entities you can replace the EntityBase without losing any functionality you added to the main entity class.

Open up vo/ContactGroup.as and add a getter function that simply returns the contacts:

package vo {
    import mx.collections.ArrayCollection;
    
    [RemoteClass(alias="vo/ContactGroup")]
    [Entity]
    public class ContactGroup extends ContactGroupEntityBase {
        
        public function get children():ArrayCollection {
            return contacts;
        }
        
    }
  
}

We also want the labels in the tree to show the name property of both ContactGroup and Contact so add labelField=”name” to the Tree component in Main.mxml:

   1: "tree" width="100%" height="100%" labelField="name" />

Now running the application should show the following!

Lets see how we can create new entities.

Flextrine Tutorial – CRUD in a simple Flex 4 address book: Creating the database schema

devdave — Tue, 03 Aug 2010 01:48:31 +0000

Introduction
Setting up the server
Creating the entities
Creating the database schema
Loading the entities
Creating new entities
Deleting entities
Updating entities
Conclusion

Once we have defined the entities in the entities directory of the Flextrine server component it is very simple to create the appropriate database schema.

Creating the database schema

Browse to http://localhost/flextrinemanager (or whatever URL you pointed to the manager directory). You should see a screen like this:

Enter the URL of the Flextrine server side component (http://localhost/contacts) in the FLEXTRINE PROJECT URL input and Click to refresh. The Flextrine manager will examine your project and update the manager to show the entities and database. Now click on Create schema to automatically generate the appropriate tables in the database. The manager should now look like this:

Under the hood Doctrine 2 has parsed the annotations in ContactGroup and Contact and has determined the appropriate tables and columns that will be required to persist the objects. Although you will never need to edit the schema manually, the following SQL is what was actually executed when you clicked CREATE SCHEMA. Notice that Doctrine enforces referential integrity through MySQL constraints so that, for example, you cannot delete a ContactGroup which has any Contacts referring to it.

CREATE TABLE  `contact`.`contactgroup` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(100) NOT NULL,
  PRIMARY KEY (`id`)
);
  
CREATE TABLE  `contact`.`contact` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(80) NOT NULL,
  `telephoneNumber` varchar(50) DEFAULT NULL,
  `birthday` date DEFAULT NULL,
  `contactGroup_id` int(11) DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `contactGroup_id` (`contactGroup_id`),
  CONSTRAINT `contact_ibfk_1` FOREIGN KEY (`contactGroup_id`) REFERENCES `contactgroup` (`id`)
);

Now that the schema has been created you can use UPDATE SCHEMA whenever you add/remove entities or attributes within entities to update the schema without losing any data that is already in the database. This gives you a very efficient workflow as your entities expand over the lifetime of a project.

We now have everything we need in the Flextrine server side component and in the database. Its time to start writing some Flex code!

Flextrine Tutorial – CRUD in a simple Flex 4 address book: Creating the entities

devdave — Tue, 03 Aug 2010 01:46:15 +0000

Introduction
Setting up the server
Creating the entities
Creating the database schema
Loading the entities
Creating new entities
Deleting entities
Updating entities
Conclusion

Now that Flextrine has been configured we need to create our entities. Entities are the objects that we want to enable for reading and writing to the database, and they are defined in PHP in the entities directory of the Flextrine server side component.

The requirements for our simple address book are that we need to have groups containing contacts. Unfortunately Group is a reserved word in SQL so we’ll call it ContactGroup. ContactGroups have a name, and many Contacts, and Contacts have a name, telephone number, birthday and a contactGroup. We are going to place all our entities in the vo package. This gives us the class diagram below:

Create a folder called vo in the entities directory of the Flextrine server side component and create ContactGroup.php and Contact.php with the contents given below. More information on writing entities can be found in the Doctrine documentation for Basic Mapping and Association Mapping. The main thing to remember when creating entities is that:

All mapped attributes must be public

ContactGroup.php

 
namespace vo;
 
use Doctrine\Common\Collections\ArrayCollection;
 
/**
 * @Entity
 */
 
class ContactGroup {
 
    /** @Id @Column(type="integer") @GeneratedValue(strategy="IDENTITY") */
    public $id;
 
    /** @Column(length=100, type="string") */
    public $name;
 
    /**
     * @OneToMany(targetEntity="Contact", mappedBy="contactGroup")
     */
 
    public $contacts;
 
    public function __construct() {
        $this->contacts = new ArrayCollection();
    }
    
}
 
?>

Contact.php

namespace vo;
 
use Doctrine\Common\Collections\ArrayCollection;
 
/**
 * @Entity
 */
 
class Contact {
 
    /** @Id @Column(type="integer") @GeneratedValue(strategy="IDENTITY") */
    public $id;
 
    /** @Column(length=80, type="string") */
    public $name;
 
    /** @Column(length=50, type="string", nullable="true") */
    public $telephoneNumber;
 
    /** @Column(type="date", nullable="true") */
    public $birthday;
    
    /**
     * @ManyToOne(targetEntity="ContactGroup", inversedBy="contacts")
     */
    public $contactGroup;
 
    public function __construct() {
 
    }
 
}
 
?>

Now that we have created our entity definitions we need to create the matching database schema.

Flextrine Tutorial – CRUD in a simple Flex 4 address book: Setting up the server

devdave — Tue, 03 Aug 2010 01:43:53 +0000

Introduction
Setting up the server
Creating the entities
Creating the database schema
Loading the entities
Creating new entities
Deleting entities
Updating entities
Conclusion

Before using Flextrine you need to do some groundwork to get your project ready.

Download the latest version of Flextrine from http://code.google.com/p/flextrine2/downloads/list
Install the Flextrine manager. This is as simple as copying the manager directory from the Flextrine download into a web-accessible directory. For the purposes of the tutorial I will assume that you have set the URL pointing at this document root as http://localhost/flextrinemanager. Note that you will require mod_rewrite to be enabled on your webserver for the manager to function correctly.
Install the Flextrine server side libraries. These are contained in the flextrine/web/lib directory of the the Flextrine download. All you need to do to install these is to copy flextrine/web/lib to a directory in your PHP include_path, or ammend the include_path to include the flextrine/web/lib directory. Note that if you don’t want to change your include_path you can set it explicitly after the next step by uncommenting the $flextrineIncludePAth line in config.php of your project (see http://code.google.com/p/flextrine2/wiki/GettingStarted for more details).
Install the latest version of Doctrine 2 from http://www.doctrine-project.org/projects/orm/download. Doctrine 2 is the technology that Flextrine is based upon and required for its operation. The easiest way to install Doctrine is to merely extract the package into flextrine/web/lib as this is already in your PHP include_path. Alternatively you can add a new entry to your include_path pointing to Doctrine.
Create an empty server-side Flextrine project. The Flextrine download contains a blank project in flextrine/web/flextrineproject which will be your starting point. Copy this to a new directory on your machine and make this directory web accessible. For the purposes of this tutorial I will assume that you have set the URL pointing to this directory as http://localhost/contacts and will refer to the directory as the Flextrine server side component.
Create a new MySQL database called contacts.
In your Flextrine server side component open up config.php and set the database connection options in the $connectionOptions variable.

Note that next time you start a new Flextrine projects you only need to do steps 5 – 6 as steps 1 – 4 only need to be done once.

Now we are ready to use Flextrine! The next step is to create some entities.