ENH Use better auto-scaffolded form fields (#301)

docs/en/01_basic_usage.md

@@ -12,13 +12,11 @@ The [`Link`](api:SilverStripe\LinkField\Models\Link) model can be used with a `h
 >
 > See [model-level permissions](https://docs.silverstripe.org/en/developer_guides/model/permissions) for more information about these methods.
 
-The [`LinkField`](api:SilverStripe\LinkField\Form\LinkField) form field is used to manage links in a `has_one` relation, and [`MultiLinkField`](api:SilverStripe\LinkField\Form\MultiLinkField) is for links in a `has_many` relation.
+The [`LinkField`](api:SilverStripe\LinkField\Form\LinkField) form field is used to manage links in a `has_one` relation, and [`MultiLinkField`](api:SilverStripe\LinkField\Form\MultiLinkField) is for links in a `has_many` relation. If you are relying on auto-scaffolded fields, these will be provided for you.
 
 ```php
 namespace App\Model;
 
-use SilverStripe\LinkField\Form\LinkField;
-use SilverStripe\LinkField\Form\MultiLinkField;
 use SilverStripe\LinkField\Models\Link;
 use SilverStripe\ORM\DataObject;
 
@@ -46,24 +44,6 @@ class MyModel extends DataObject
         'HasOneLink',
         'HasManyLinks',
     ];
-
-    public function getCMSFields()
-    {
-        $fields = parent::getCMSFields();
-
-        // Don't forget to remove the auto-scaffolded fields!
-        $fields->removeByName(['HasOneLinkID', 'HasManyLinks']);
-
-        $fields->addFieldsToTab(
-            'Root.Main',
-            [
-                LinkField::create('HasOneLink'),
-                MultiLinkField::create('HasManyLinks'),
-            ]
-        );
-
-        return $fields;
-    }
 }
 ```
 
@@ -92,6 +72,46 @@ class MyModel extends DataObject
 }
 ```
 
+## Form fields
+
+When relying on auto-scaffolded fields for your relations, an appropriate `LinkField` or `MultiLinkField` instance will be scaffolded for you. But in some cases you may want to explicitly set those fields up yourself, so here's an example of how to do that.
+
+```php
+namespace App\Model;
+
+use SilverStripe\LinkField\Form\LinkField;
+use SilverStripe\LinkField\Form\MultiLinkField;
+use SilverStripe\LinkField\Models\Link;
+use SilverStripe\ORM\DataObject;
+
+class MyModel extends DataObject
+{
+    private static array $has_one = [
+        'HasOneLink' => Link::class,
+    ];
+
+    private static $has_many = [
+        'HasManyLinks' => Link::class . '.Owner',
+    ];
+    // ...
+
+    public function getCMSFields()
+    {
+        $fields = parent::getCMSFields();
+
+        $fields->addFieldsToTab(
+            'Root.Main',
+            [
+                LinkField::create('HasOneLink'),
+                MultiLinkField::create('HasManyLinks'),
+            ]
+        );
+
+        return $fields;
+    }
+}
+```
+
 ## Validation
 
 Custom links can have validation set using standard [model validation](https://docs.silverstripe.org/en/developer_guides/forms/validation/#model-validation). This is true both for the validation of the link data itself, as well as validating relations to the `Link` class.

docs/en/02_configuration.md

@@ -51,7 +51,6 @@ class MyModel extends DataObject
     public function getCMSFields()
     {
         $fields = parent::getCMSFields();
-        $fields->removeByName(['EmailLinkID', 'LinkList']);
         $fields->addFieldsToTab(
             'Root.Main',
             [
@@ -64,6 +63,29 @@ class MyModel extends DataObject
 }
 ```
 
+You can also use [`FieldList::dataFieldByName()`](api:SilverStripe\Forms\FieldList::dataFieldByName()) if you want to just update the auto-scaffolded form fields.
+
+```php
+namespace App\Model;
+
+use SilverStripe\LinkField\Models\EmailLink;
+use SilverStripe\LinkField\Models\SiteTreeLink;
+use SilverStripe\ORM\DataObject;
+
+class MyModel extends DataObject
+{
+    // ...
+
+    public function getCMSFields()
+    {
+        $fields = parent::getCMSFields();
+        $fields->dataFieldByName('EmailLink')->setAllowedTypes([EmailLink::class]);
+        $fields->dataFieldByName('LinkList')->setAllowedTypes([SiteTreeLink::class, EmailLink::class]);
+        return $fields;
+    }
+}
+```
+
 ## Excluding the `LinkText` field
 
 Sometimes you might want to have a link which doesn't have text, or for which you handle the text elsewhere. For example you might have a banner with a link, and you only want to use a `Link` record to control where the banner links to.
@@ -84,7 +106,6 @@ class MyModel extends DataObject
     public function getCMSFields()
     {
         $fields = parent::getCMSFields();
-        $fields->removeByName(['LinkID', 'LinkList']);
         $fields->addFieldsToTab(
             'Root.Main',
             [

src/Models/Link.php

@@ -4,12 +4,15 @@
 
 use SilverStripe\Core\ClassInfo;
 use SilverStripe\Forms\FieldList;
+use SilverStripe\Forms\FormField;
 use SilverStripe\LinkField\Services\LinkTypeService;
 use SilverStripe\ORM\DataObject;
 use SilverStripe\ORM\DataObjectSchema;
 use SilverStripe\ORM\FieldType\DBHTMLText;
 use SilverStripe\Versioned\Versioned;
 use SilverStripe\Forms\Tip;
+use SilverStripe\LinkField\Form\LinkField;
+use SilverStripe\LinkField\Form\MultiLinkField;
 
 /**
  * A Link DataObject. This class should be treated as abstract. You should never directly interact with a plain Link
@@ -164,6 +167,25 @@ public function getShortCode(): string
         return strtolower(rtrim(ClassInfo::shortName($this), 'Link')) ?? '';
     }
 
+    public function scaffoldFormFieldForHasOne(
+        string $fieldName,
+        ?string $fieldTitle,
+        string $relationName,
+        DataObject $ownerRecord
+    ): FormField {
+        return LinkField::create($relationName, $fieldTitle);
+    }
+
+    public function scaffoldFormFieldForHasMany(
+        string $relationName,
+        ?string $fieldTitle,
+        DataObject $ownerRecord,
+        bool &$includeInOwnTab
+    ): FormField {
+        $includeInOwnTab = false;
+        return MultiLinkField::create($relationName, $fieldTitle);
+    }
+
     /**
      * Get a string representing the versioned state of the link.
      */

src/Models/SiteTreeLink.php

@@ -42,7 +42,6 @@ public function getCMSFields(): FieldList
         $this->beforeUpdateCMSFields(function (FieldList $fields) {
             // Remove scaffolded fields to we don't have field name conflicts which would prevent field customisation
             $fields->removeByName([
-                'PageID',
                 'Anchor',
                 'QueryString',
             ]);
@@ -53,16 +52,7 @@ public function getCMSFields(): FieldList
                 'Auto generated from Page title if left blank',
             )));
 
-            $fields->insertAfter(
-                'LinkText',
-                TreeDropdownField::create(
-                    'PageID',
-                    _t(__CLASS__ . '.PAGE_FIELD_TITLE', 'Page'),
-                    SiteTree::class,
-                    'ID',
-                    'TreeTitle'
-                )
-            );
+            $fields->dataFieldByName('PageID')->setTitle(_t(__CLASS__ . '.PAGE_FIELD_TITLE', 'Page'));
 
             $fields->insertAfter(
                 'PageID',