Charcoal\Relation

README.md

@@ -4,6 +4,8 @@ Charcoal CMS
 The CMS Charcoal Module (Content Management System). Provides basic objects to build a website.
 Notably, `Section` (or _page_), `News`, `Event`
 
+Adds support for working with [relationships](#relationships) between models using an intermediate object.
+
 # How to install
 
 The preferred (and only supported) way of installing _charcoal-cms_ is with **composer**:
@@ -155,6 +157,102 @@ The `\Charcoal\Cms\Section\*` objects are `final`. To extend, use the `\Charcoal
 
 ## News object
 
+# Relationships
+
+-   [Concept](#concept)
+-   [Models](#models)
+-   [Widgets](#widgets)
+-   [Configuration](#configuration)
+-   [Usage](#usage)
+
+## Concept
+
+A **source** model has one or many relationships with a **target** model. These relationships are stored in an intermediate **pivot** model.
+
+## Models
+
+The `Pivot` Model extends `AbstractModel` and implements some new properties:
+
+    - `source_object_id`
+    - `source_object_type`
+    - `target_object_id`
+    - `target_object_type`
+
+## Widgets
+
+The module provides its own Admin widgets namespaced as `Charcoal\Admin\Widget\Relation`.
+
+## Configuration
+
+Add the View paths in `config/config.json`.
+```json
+"view": {
+    "paths": [
+        "...",
+        "vendor/locomotivemtl/charcoal-cms/templates/"
+    ]
+}
+```
+
+## Usage
+
+Your models need to know that they may have relationships to other models. To do that, use and implement the `PivotAware` concept:
+```php
+use Charcoal\Relation\Interfaces\PivotAwareInterface;
+use Charcoal\Relation\Traits\PivotAwareTrait;
+```
+
+In your **source** model metadata, add the widget configuration in the default form group (see example below).
+```json
+"forms": {
+    "default": {
+        "groups": {
+            "target_object_pivot_group": {
+                "priority": 10,
+                "show_header": false,
+                "title": "Target Objects",
+                "type": "charcoal/admin/widget/relation/form-group/pivot",
+                "template": "charcoal/admin/widget/relation/form-group/pivot",
+                "target_object_type": "my/namespace/target-object-type"
+            }
+        }
+    }
+}
+```
+
+To create a new `Pivot` model, your **target** model needs to provide a quick form.
+```json
+"forms": {
+    "project_name.quick": {
+        "group_display_mode": "tab",
+        "groups": {
+            "body": {
+                "title": "Target Object Information",
+                "show_header": false,
+                "properties": [
+                    "title"
+                ],
+                "layout": {
+                    "structure": [
+                        { "columns": [ 1 ] }
+                    ]
+                }
+            }
+        }
+    }
+},
+"default_quick_form": "project_name.quick",
+```
+
+Hooks allow the **source** model to remove unnecessary relationships when deleted.
+```php
+public function preDelete()
+{
+    // PivotAwareTrait
+    $this->removePivots();
+    return parent::preDelete();
+}
+```
 
 # Development
 

config/admin.routes.json

@@ -0,0 +1,15 @@
+{
+    "routes": {
+        "actions": {
+            "relation/sync": {
+                "ident": "charcoal/admin/action/relation/sync"
+            },
+            "relation/link": {
+                "ident": "charcoal/admin/action/relation/link"
+            },
+            "relation/unlink": {
+                "ident": "charcoal/admin/action/relation/unlink"
+            }
+        }
+    }
+}

metadata/charcoal/relation/pivot-interface.json

@@ -0,0 +1,195 @@
+{
+    "properties": {
+        "id": {
+            "type": "id",
+            "mode": "uniqid",
+            "label": "ID"
+        },
+        "active": {
+            "type": "boolean",
+            "label": {
+                "en": "Active",
+                "fr": "Actif"
+            }
+        },
+        "position": {
+            "type": "number",
+            "label": "Position"
+        },
+        "group": {
+            "type": "string",
+            "hidden": true,
+            "required": true,
+            "allow_null": false,
+            "label": {
+                "en": "Group",
+                "fr": "Groupe"
+            }
+        },
+        "source_object_type": {
+            "type": "string",
+            "hidden": true,
+            "required": true,
+            "allow_null": false,
+            "label": {
+                "en": "Source Object Type",
+                "fr": "Type de l'objet source"
+            }
+        },
+        "source_object_id": {
+            "type": "string",
+            "hidden": true,
+            "required": true,
+            "allow_null": false,
+            "label": {
+                "en": "Source Object",
+                "fr": "Objet source"
+            }
+        },
+        "target_object_type": {
+            "type": "string",
+            "hidden": true,
+            "required": true,
+            "allow_null": false,
+            "label": {
+                "en": "Target Object Type",
+                "fr": "Type de l'object ciblé"
+            }
+        },
+        "target_object_id": {
+            "type": "string",
+            "input_type": "charcoal/admin/property/input/selectize/relation",
+            "required": true,
+            "allow_null": false,
+            "label": {
+                "en": "Target Object",
+                "fr": "Object ciblé"
+            },
+
+            "multiple": false,
+
+            "selectize_options": {
+                "create": false,
+                "plugins": {
+                    "btn_remove": {}
+                },
+                "maxItems": 1
+            },
+            "form_ident": {
+                "create": "quick.create",
+                "update": "quick.update"
+            }
+        }
+    },
+
+    "sources": {
+        "default": {
+            "type": "database",
+            "table": "charcoal_pivots"
+        }
+    },
+    "default_source": "default",
+
+    "admin": {
+        "lists": {
+            "default": {}
+        },
+        "default_list": "default",
+
+        "forms": {
+            "relation.create": {
+                "groups": {
+                    "basic": {}
+                },
+                "sidebars": {
+                    "default": {}
+                }
+            },
+            "relation.edit": {
+                "groups": {
+                    "basic": {}
+                },
+                "sidebars": {
+                    "default": {}
+                }
+            }
+        },
+        "default_form": "relation.edit",
+        "default_quick_form": "relation.edit",
+
+        "form_groups": {
+            "basic": {
+                "group_display_mode": false,
+                "priority": 10,
+                "show_title": false,
+                "show_header": false,
+                "title": "Relation",
+                "properties": [
+                    "source_object_type",
+                    "source_object_id",
+                    "target_object_type",
+                    "target_object_id",
+                    "group"
+                ],
+                "layout": {
+                    "structure": [
+                        { "columns": [ 1 ] },
+                        { "columns": [ 1, 1 ] },
+                        { "columns": [ 1, 1 ] }
+                    ]
+                }
+            }
+        },
+
+        "dashboards": {
+            "admin.create": {
+                "widgets": {
+                    "form": {
+                        "type": "charcoal/admin/widget/objectForm",
+                        "group_display_mode": "tab",
+                        "form_ident": "relation.create",
+                        "permissions": [ "object/create" ]
+                    }
+                },
+                "layout": {
+                    "structure": [
+                        { "columns": [ 1 ] }
+                    ]
+                }
+            },
+            "admin.edit": {
+                "widgets": {
+                    "form": {
+                        "type": "charcoal/admin/widget/objectForm",
+                        "group_display_mode": "tab",
+                        "form_ident": "{{ formIdent }}",
+                        "permissions": [ "object/edit" ]
+                    }
+                },
+                "layout": {
+                    "structure": [
+                        { "columns": [ 1 ] }
+                    ]
+                }
+            },
+            "admin.table": {
+                "widgets": {
+                    "list": {
+                        "type": "charcoal/support/admin/widget/table",
+                        "collection_ident": "default",
+                        "data_sources": [ "request" ],
+                        "sortable": true
+                    }
+                },
+                "layout": {
+                    "structure": [
+                        { "columns": [ 1 ] }
+                    ]
+                }
+            }
+        },
+        "default_create_dashboard": "admin.create",
+        "default_edit_dashboard": "admin.edit",
+        "default_collection_dashboard": "admin.table"
+    }
+}