mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-07-05 19:09:27 +02:00
17 KiB
17 KiB
title: DataObject Relationship Management summary: Learn how to create custom DataObjects and how to build interfaces for managing that data.
This tutorial is deprecated, and has been replaced by Lessons 7, 8, 9, and 10 in the [Lessons section](http://www.silverstripe.org/learn/lessons)
Tutorial 5 - Dataobject Relationship Management
Overview
This tutorial explores the relationship and management of DataObjects. It builds on the second tutorial where we learnt how to define additional fields on our models, and attach images to them.
What are we working towards?
To demonstrate relationships between objects, we are going to use the example of students working on various projects. Each student has a single project, and each project has one or more mentors supervising their progress. We'll create these objects, make them editable in the CMS, and render them on the website.
This table shows some example data we'll be using:
| Project | Student | Mentor |
|---|---|---|
| Developer Toolbar | Jakob,Ofir | Mark,Sean |
| Behaviour Testing | Michal,Wojtek | Ingo, Sean |
| Content Personalization | Yuki | Philipp |
| Module Management | Andrew | Marcus,Sam |
Has-One and Has-Many Relationships: Project and Student
A student can have only one project, it'll keep them busy enough.
But each project can be done by one or more students.
This is called a one-to-many relationship.
Let's create the Student and Project objects.
mysite/code/Student.php
<?php
use SilverStripe\ORM\DataObject;
class Student extends DataObject
{
private static $db = array(
'Name' => 'Varchar',
'University' => 'Varchar',
);
private static $has_one = array(
'Project' => 'Project'
);
}
mysite/code/Project.php
<?php
use Page;
class Project extends Page
{
private static $has_many = array(
'Students' => 'Student'
);
}
mysite/code/ProjectController.php
<?php
use PageController;
class ProjectController extends PageController
{
}
The relationships are defined through the $has_one
and $has_many properties on the objects.
The array keys declares the name of the relationship,
the array values contain the class name
(see the "datamodel"
topic for more information).
As you can see, only the Project model extends Page,
while Student is a plain DataObject subclass.
This allows us to view projects through the standard
theme setup, just like any other page.
It would be possible to render students separately as well,
but for now we'll assume they're just listed as part of their Project page.
Since Project inherits all properties (e.g. a title) from its parent class,
we don't need to define any additional ones for our purposes.
Now that we have our models defined in PHP code, we need to tell the database to create the related tables. Trigger a rebuild through dev/build before you proceed to the next part of this tutorial.
Organizing pages: ProjectHolder
A Project is just a page, so we could create it anywhere in the CMS.
In order to list and organize them, it makes sense to collect them under a common parent page.
We'll create a new page type called ProjectsHolder for this purpose,
which is a common pattern in SilverStripe's page types. Holders
are useful for listing their children, and usually restrict these children to a specific class,
in our case pages of type Project.
The restriction is enforced through the $allowed_children directive.
mysite/code/ProjectsHolder.php
:::php
getComponentByType('SilverStripe\\Forms\\GridField\\GridFieldDataColumns') ->setDisplayFields(array( 'Name' => 'Name', 'Project.Title'=> 'Project' // Retrieve from a has-one relationship )); // Create a gridfield to hold the student relationship $studentsField = new GridField( 'Students', // Field name 'Student', // Field title $this->Students(), // List of all related students $config ); // Create a tab named "Students" and add our field to it $fields->addFieldToTab('Root.Students', $studentsField); return $fields; } } ``` This creates a tabular field, which lists related student records, one row at a time. It's empty by default, but you can add new students as required, or relate them to the project by typing in the box above the table. In our case, we want to manage those records, edit their details, and add new ones. To accomplish this, we have added a specific [api:GridFieldConfig]. While we could've built the config from scratch, there's several preconfigured instances. The `GridFieldConfig_RecordEditor` default configures the field to edit records, rather than just viewing them. The GridField API is composed of "components", which makes it very flexible. One example of this is the configuration of column names on our table: We call `setDisplayFields()` directly on the component responsible for their rendering.
Adding a `GridField` to a page type is a popular way to manage data,
but not the only one. If your data requires a dedicated interface
with more sophisticated search and management logic, consider
using the [ModelAdmin](/developer_guides/customising_the_admin_interface/modeladmin)
interface instead.
Select each `Project` page you have created before,
go in the tab panel called "Students", and add all students as required,
by clicking on the link **Add Student** of your *GridField* table.
Once you have added all the students, and selected their projects, it should look a little like this:
### Many-many relationships: Mentor
Now we have a fairly good picture of how students relate to their projects.
But students generally have somebody looking them over the shoulder.
In our case, that's the "mentor". Each project can have many of them,
and each mentor can have one or more projects. They're busy guys!
This is called a *many-many* relationship.
The first step is to create the `Mentor` object and set the relation with the `Project` page type.
**mysite/code/Mentor.php**
```php
'Varchar',
);
private static $belongs_many_many = array(
'Projects' => 'Project'
);
}
```
**mysite/code/Project.php**
```php
'Mentor'
);
}
```
This code will create a relationship between the `Project` table and the `Mentor` table by storing the ids of the respective `Project` and `Mentor` in a another table named "Project_Mentors"
(after you've performed a `dev/build` command, of course).
The second step is to add the table in the method `getCMSFields()`,
which will allow you to manage the *many_many* relation.
Again, GridField will come in handy here, we just have
to configure it a bit differently.
**mysite/code/Project.php**
```php
Mentors(),
GridFieldConfig_RelationEditor::create()
);
$fields->addFieldToTab('Root.Mentors', $mentorsField);
return $fields;
}
}
```
The important difference to our student management UI is the usage
of `$this->Mentor()` (rather than `Mentor::get()`). It will limit
the list of records to those related through the many-many relationship.
In the CMS, open one of your `Project` pages and select the "Mentors" tab.
Add all the mentors listed [above](#what-are-we-working-towards)
by clicking on the **Add Mentor** button.
To associate the mentor with a project, select one of the mentors, and click on the projects tab. Add all the projects a mentor is associated with (see the [list](/tutorials/dataobject_relationship_management#What_are_we_working_towards?)), by typing the name in "Find Projects by Page name" and clicking the "Link Existing" button.
You will notice that you are able to select the same `Project` for multiple mentors.
This is the definition of a **many-to-many** relation.
## Website Display
Now that we have created all the *Page* and *DataObject* classes necessary and the relational tables to manage the [relations](/developer_guides/model/data_model_and_orm#relations) between them, we would like to see these relations on the website. We will see in this section how to display all these relations,
but also how to create a template for a *DataObject*.
For every kind of *Page* or *DataObject*, you can access to their relations thanks to the **control** loop.
### Projects Overview Template
We'll start by creating a `ProjectsHolder` template,
which lists all projects, and condenses their
student and mentor relationships into a single line.
You'll notice that there's no difference between
accessing a "has-many" and "many-many" relationship
in the template loops: to the template, it's just
a named list of object.
**themes/simple/templates/Layout/ProjectsHolder.ss**
```ss
<% include SideBar %>
$Title
$Content
<% loop $Children %>
<% end_loop %>
| Project | Students | Mentors |
|---|---|---|
| $Title | <% loop $Students %> $Name ($University)<% if not $Last %>, <% end_if %> <% end_loop %> | <% loop $Mentors %> $Name<% if not $Last %>, <% end_if %> <% end_loop %> |
$Title
$Content
Students
<% if $Students %>-
<% loop $Students %>
- $Name ($University) <% end_loop %>
No students found
<% end_if %>Mentors
<% if $Mentors %>-
<% loop $Mentors %>
- $Name <% end_loop %>
No mentors found
<% end_if %>