External relation
You are probably already familiar with inner relations, and you came across the topic of outer relations in the definition topic. So let's take a look at them.
An outer relation is a relationship between two independent entities. That is, entities that are not hierarchically arranged in relation to each other - they are not subentities. You can thus link two independent entities and use this link especially when creating queries . The important thing is that the connection is not automatically given in principle, like internal relations, but it is necessary to define exactly with what (with which entity) and especially how the given entity is connected.
But let's go straight from theory to practice and show it again with an example from a sample application. As already said in the chapter on modeling principles , the images within the small sample gallery are not a sub-entity of the gallery, but a separate entity, and for that reason. that there can be a large number of them and this would create a very large data entity and that might not be appropriate. But despite that, we need to know the fact that the gallery is linked from the images. It can be used, for example, in search (as we will show), but certainly not only that.
So how to define such an outer relation? Within the JetApplication\Content_Gallery sample class like this:
namespace JetApplication;
use Jet\DataModel;
use Jet\DataModel_Definition;
use Jet\DataModel_IDController_UniqueString;
use Jet\DataModel_Query;
#[DataModel_Definition(
name: 'gallery',
database_table_name: 'image_galleries',
id_controller_class: DataModel_IDController_UniqueString::class,
relation: [
'related_to_class_name' => Content_Gallery_Image::class,
'join_by_properties' => ['id' => 'gallery_id'],
'join_type' => DataModel_Query::JOIN_TYPE_LEFT_OUTER_JOIN
]
)]
class Content_Gallery extends DataModel
{
//... ... ...
}
So nothing complicated at all... It is necessary to determine the following things:
- related_to_class_name
What class (entity) the session points to. - join_by_properties
What properties of classes form a binding. This is an associated field, where the key is the name of the property of the class to which the definition is bound (in the example it is JetApplication\Content_Gallery) and the value is the name of the property of the bound class (here JetApplication\Content_Gallery_Image). The property can be N, or it must be as many as necessary for linking. - join_type
How the bond is supposed to work. The options are DataModel_Query::JOIN_TYPE_LEFT_JOIN and DataModel_Query::JOIN_TYPE_LEFT_OUTER_JOIN and it's really meant as LEFT JOIN and LEFT OUTER JOIN in SQL terms.
Before we show what it's good for in practice, let's say that X external relations can be defined - that is, not just one, as in the example, but as many as you need.
And one more important caveat. This binding is only for queries and data loading . It does not mean, for example, that deleting entity A will automatically delete related entities B. This is not always desirable, so Jet does not do this automatically and leaves it up to your application logic.
What is it good for?
Here I'm going a little ahead of the topic and we'll show you how to load data and create queries . In the small sample gallery, it is possible to easily search for galleries in the administration module, even based on the name of the image in it. This is handled by the JetApplication\Content_Gallery::search method. And it does nothing but create a simple query using an outer session and retrieve galleries that meet the given criteria. Thanks to the definition of the external session, the system will understand that we are also searching using an external session and will take care of generating the necessary SQL query:
/**
* @param string $search
*
* @return Content_Gallery[]
*/
public static function search( string $search ): iterable
{
$search = '%' . $search . '%';
return static::fetchInstances(
[
'gallery_localized.title *' => $search,
'OR',
'image.file_name *' => $search
]
);
}