For the purpose of the documentation, the database structure of our basic component "Hello My World" is the following :
From this digram we can determine the following relations :
Visits is the pivot table between travellers & cities :
The naming conventions are inspired from the FOF conventions.
One to Many - 1:N
From a city, you can load its unique parent country. Let's load country.name
From a city, you can load its unique parent continent. Let's load country.continent.name
Especially in forms, it makes no sense to load a second level Foreign Key. You can only drag the first level node because, in our case, a continent can have many countries, so the city cannot attach to a continent directly. Instead, you can group the countries list by its continent. (see the field properties, once instancied)
Many to One (N:1)
At the end of the fields tree of a table, are listed all relations to it. (Also called cross references.)
Many to Many (N:m)
Depending the node you drag, Cook will automatically determines if it refers to a N:1, or to a N:m
In this example, the XREF node becomes the Pivot Table.
Model behaviors kept
Items are automatically managed in the pivot table. Creation and destruction of the links are handled by the pivot model.
Raw mode (optimization model-less)
So, regarding to the previous point, if you do not have particular treatments in that pivot model, you can optimize the queries, using the 'raw' mode in the relation declaration:
$this->belongsToMany('travellers', null, 'id', 'id', 'visits', 'city', 'traveller', array('name'), // HERE true // Raw mode );
The children items can be automatically suppressed when their parent are lost.
In case of N:m, the integrities are important because the links created in the pivot table are dependant of their parents.
learn more : Integrities
Both N:1 and N:m will display a mutiple selection list, rendered with chosen library:
The only difference stands for N:1. Only the availables values are listed.
One to One (1:1)
One to One is used to extends a table.
Cross-reference filters are not handled at the moment.
Understanding the code.
A relation is defined in the plural model constructor as follow:
$this->hasMany('cities', // name null, // foreignModelClass 'id', // localKey 'country', // foreignKey, array('name') // selectFields );
$this->belongsToMany('travellers', // name null, // foreignModelClass 'id', // localKey 'id', // foreignKey, 'visits', // pivotModelClass, 'city', // pivotLocalKey 'traveller', // pivotForeignKey array('name') // selectFields );
At any moment you can load the cross-reference lists (N:1, or N:m)
It works as well for the lists:
Your generated component can handle infinite level of cross-lists (in an pretty good optimized way).