Convert entity from Base to Base Plus

[bandtank]

This tutorial provides instructions for converting an entity from type Base to type Base Plus. I needed to do this recently and it took me a few minutes to figure it out. To document the process so it is easier next time, here is a tutorial.

Assumptions:

• Files are located in custom/Espo/Custom/. If the files are in a module, replace that part of the path with custom/Espo/Modules/MyModule/. Nothing else is different.
• Meetings and Calls are the only event entities. If you have more types of event entities, add them to the lists whenever you see Meetings and Calls.
• Tasks are special. BasePlus entities have a relationship with Tasks by default, which typically means Tasks will appear in the same lists as Meetings and Calls. That is not always true, however, so be aware.

---

Edit the controller in Controllers/TestEntity.php. The following line needs to be modified:

class TestEntity extends \Espo\Core\Templates\Controllers\Base     # Old
class TestEntity extends \Espo\Core\Templates\Controllers\BasePlus # New

Edit the language files in Resources/i18n/xx_xx/TestEntity.json. The following lines need to be added:

{
    ...
    "links": {
        ...
        "meetings": "Meetings",
        "calls": "Calls",
        "tasks": "Tasks"
    },
    ...
}

Edit the client definition in Resources/metadata/clientdefs/TestEntity.php. The following lines needs to be added:

{
    ...
    "sidePanels": {
        "detail": [
            {
                "name": "activities",
                "label": "Activities",
                "view": "crm:views/record/panels/activities",
                "aclScope": "Activities"
            },
            {
                "name": "history",
                "label": "History",
                "view": "crm:views/record/panels/history",
                "aclScope": "Activities"
            },
            {
                "name": "tasks",
                "label": "Tasks",
                "view": "crm:views/record/panels/tasks",
                "aclScope": "Task"
            }
        ]
    }
}​

Edit the scope definition in Resources/metadata/scopes/TestEntity.json. The following line needs to be modified:

    "type": "Base"            <-- Old
    "type": "BasePlus"        <-- New

Edit the entity definition in Resources/metadata/entityDefs/TestEntity.json. The following lines need to be added:

{
    ...
    "links": {
        ...
        "meetings": {
            "type": "hasMany",
            "entity": "Meeting",
            "foreign": "parent",
            "layoutRelationshipsDisabled": true
        },
        "calls": {
            "type": "hasMany",
            "entity": "Call",
            "foreign": "parent",
            "layoutRelationshipsDisabled": true
        },
        "tasks": {
            "type": "hasChildren",
            "entity": "Task",
            "foreign": "parent",
            "layoutRelationshipsDisabled": true
        },
        "emails": {
            "type": "hasChildren",
            "entity": "Email",
            "foreign": "parent",
            "layoutRelationshipsDisabled": true
        }
    }
}​

Edit the entity definition in Entities/TestEntity.php. The following line needs to be modified:

class TestEntity extends \Espo\Core\Templates\Entities\Base     # Old
class TestEntity extends \Espo\Core\Templates\Entities\BasePlus # New

Edit the entity definition in Services/TestEntity.php. The following line needs to be modified:

class TestEntity extends \Espo\Core\Templates\Services\Base     # Old
class TestEntity extends \Espo\Core\Templates\Services\BasePlus # New

Now is the part when you have to make a decision. The entity has to be added to the list of parent entities for each of the desired event entities. For example, to allow Meeting records to select TestEntity records as parents, modify the following file: custom/Espo/Custom/Resources/metadata/entityDefs/Meeting.json. Add the following code:

{
    ...
    "fields": {
        ...
        "parent": {
            "entityList": [
                ...
                "TestEntity"
            ]
        }
    },
    ...
}​

Do that for every entity which needs to select TestEntity records as the parent (Meetings, Calls, Tasks, etc.).

Rebuild in the administration menu. At this point, the entity should be the same as if it had been created as Base Plus instead of Base.

[jflores]

I’ve noticed since v8 (maybe sooner) that creating custom entities from the gui no longer generates files in entities or services - just controllers and resources (eg scopes, entitydefs, clientdefs etc). I’m not sure if the .php filed in entity or services are necessary any longer unless they’re being extended.

[bandtank]

You can read more about that here.

[shalmaxb]

Thanks for pointing to this. Sometimes I miss such discussions, because I do not cruise all the time for everything.

[jflores]

Very cool. I wondered if they were, strictly speaking, necessary in many cases since they were largely empty. Custom getters and setters really seemed like the most common use case I had. This clarifies things. Thanks for sharing!