BlueErp

or how to create a new entity in 10 minutes and only 20 lines of code (including the spacing)!

In this tutorial, we will create a sample application called 'projects', and we will see how the entity framework can assist in creating this entity.

In this application, we assume that you can reach egw by going to 'http://localhost/', you may have to adapt the url given below to suit you specific case

Step 1: Create and install new egw application

At the root of the egw directory, run the script 'new_app.sh myproject'.
This will create a skeleton directory called 'myproject'
Go into the myrpoject directory, and allow you web server to write the content of the setup directory. An insecure way to do it is to enter the following command, this should be enough for the time being:

chmod -R 777 setup

Then go back to the egw setup http://localhost/setup/, log in as the configuration manager, go to install application and choose to install the new application called myproject.

Finally, go back to the main screen of egw, log in, go to egroupware admin, and allow your user to access the application. For instance, this can be achieved by selected 'Manage groups', then the 'default' group, and tick the box in front of 'myproject'

Step 2: Create the table that will store the entity details

In egroupware, go to etemplate and select DB Tools in the menu.
Select 'myproject' as your application. The entity we will create will be called myproject and be stored in a table of the same name.
Enter the name of the entity and click on 'add table'. The new table myproject now appears in the drop down menu.

Now you need to add rows as follows:

When it is done, select 'Write tables'. Egw will then write

Go back to egw setup -> Manage Applications and upgrade myproject to its new version.

Step 3: Create the myproject entity

In the directory myproject/inc, create a new file called class.MyProject.inc.php. This file will contain the MyProject class which defines the MyProject entity.

   1.
   2. include_once PHPGW_INCLUDE_ROOT . '/entity/inc/class.Entity.inc.php';
   3. 
   4. class MyProject extends Entity
   5. {
   6.   function __construct()
   7.   {
   8.           $this->addFields(array(
   9.                   CreateField('HiddenField', 'id', 'id'),
  10.                   CreateField('Field', 'Project Code', 'project_code'),
  11.                   CreateField('TextareaField', 'Description', 'description'),
  12.                   CreateField('BooleanField','Project is active?', 'is_active')
  13.                      -> setDefault(true),
  14.                   CreateField('RelatedEntityField', 'Customer', 'customer_id',
  15.                           'blue_contact.Customer'),
  16.           ));
  17.           $this->setBrowseColumns(array('project_code', 'customer', 'is_active')); 
  18.   }
  19.   function getDbInfo() { return array('app' => 'myproject', table => 'mytable'); }
  20. }  

Notes on the code:

Line 2: we include the entity framework in order to be able to use it in the rest of the code
Line 4: all entity classes extends the entity class, which contains all the functions and call backs to make the framework useful
Line 6: the entity framework is php5 only. We use the unified constructor syntax which was introduced with php5
Line 8: the addFields method is the most easy way to define your entity by adding an array of fields
Line 9: the CreateField function simply creates objects in the entity application. The syntax of this function is CreateField($classname, ...) where ... are the parameters to be passed to the constructor.
The use of this function is superior to the use of the operator 'new', as with php5 object returned by functions can be reused in the next function call (see below)
Line 10: We use here the basic 'Field' type, which default to a a text input
Line 13: Here we use another new feature of php5: the ability to call a function on an object returned by a function. The set_default function is a function defined in the Field class (and hence inherited in by BooleanField class) which allows to set a default value for a given field. This can be used by any field.
Line 14 & 15: The RelatedEntityField class allows the user refer to another entity by just manipulating its ID in the code. When the end users sees the form, he is presented with a select html input which shows a human readable format. The constructor of this field is as follows:
function __construct($label, $dbname, $entityClass, $where = null)
$label: human readable label of what the field is about
$dbname: the database column name used to store the value of this field in the database
$entityClass: the name of the entity this fields refers to, in the format appname.ClassName
$where: an array of selection criteria
Line 16: We specify which one are the columns that will be shown when browsing the entity
Line 19: the get_db_info is to be overriden by class that extend entity. It contains the reference to the table in which the entity data is stored

In this example, we have our entity which has a field called 'customer_id'. This field refers to the id field in the table 'blue_customer'. However, from a user perspective, the customer is referred to by its name and not its id which is a cryptic number. The name of a customer is stored in the column 'name' of the blue_customer table.

Then, we will tell egw that the entity that we want to edit is the one defined by the class myproject.myproject. To do this, modify the file myproject/index.php so that the entity variable points to myproject.myproject.

Then go to the myproject; application in egw by going to http://localhost/myproject'

You can now browse, edit and delete entities of the type 'myproject'. Et voilà!

Step 4: Going further

Now that you know the basics, you can easily create one or more additional entities. The entity framework is capable of much more! For more advanced example, the best is to refer to further documentation and code examples:

• The entity documentation describes in more details the entity interface and should highlight some of the more advanced uses of the framework
• blue_ledger.journal illustrates the 1 to many relationship with a sub entity - in this case the rows entity
• blue_ledger.product illustrates the n to n relationship with a sub entity (blue_admin.tax)
• blue_order.order is one of the most complex entities. It illustrates the 1 to many relationship with the order_item relationship, the use of customs etemplates to edit entities, and the use of pre processing and post_processing of data in a complex manner, and the use of havign several entities stored in a single table, the use of custom filters, the use of a custom ui class for editing the entity