Adds code samples to fields and a set of documents around Entities

docs/development/entity.md

@@ -0,0 +1,83 @@
+# Entities
+
+Entities are models that represent the data in your application. Fields are properties of the model that get stored in the database. 
+
+By default, EspoCRM supports the following Entities:
+
+- [Base Entity](../entity/entity-base)
+- [Entity Plus](../entity/entity-plus) - An Entity that includes Activities, Tasks, and History by default.
+- [Event Entity](../entity/entity-event) - An Entity that has calendar properties, by default
+- [Person Entity](../entity/entity-person) - An Entity with details for a person, including an attribute to manage personal data.
+- [Company Entity](../entity/entity-company) - An Entity with details for a company or organization.
+
+## Entity Fields
+Entities are made up of fields, which describe the entity's data and provide structure to the entity. The types of fields available are described [on the fields page](/administration/fields).
+
+These fields are organized into an [entityDefs](/development/metadata/entity-defs) file that, by default, is created at `custom/Espo/Custom/Resources/metadata/entityDefs/{YourBaseEntityName}.json` when using the GUI to create the interface.
+
+When fields are updated via the GUI, updates are also stored in that file.
+
+If you are creating a module, then the best practice is to organize entities as modules. If you do that, the file should be created at `custom/Espo/Modules/{ModuleName}/Resources/metadata/clientDefs/{YourBaseEntityName}.json`
+
+!!! note
+    If you create an Entity as a Module, but update it via the GUI, then the updates will write to `custom/Espo/Custom/Resources/metadata/entityDefs/{YourBaseEntityName}.json` AND NOT `custom/Espo/Modules/{ModuleName}/Resources/metadata/clientDefs/{YourBaseEntityName}.json`. If you update via the GUI and want the updates in your module, then you will need to copy the data from the default file into your module file. 
+
+!!! note
+    The system loads file data from `custom/Espo/Custom` _after_ `custom/Espo/Modules/`. If you define a field in entityDefs in your module and then update it via the GUI, the updates at `custom/Espo/Custom` will supercede your Module.
+
+## Labels
+
+While you define your schema in the entityDefs file of your Entity, the naming/labelling of those fields is managed in the Internationalization area of the application.
+
+For example, if I define somefield "someEnumFieldName" in entityDefs:
+
+```
+"someEnumFieldName": {
+    "type": "enum",
+    "options": [
+        "Option 1",
+        "Option 2",
+        "Option 3"
+    ],
+    "style": {
+        "Option 1": null,
+        "Option 2": null,
+        "Option 3": null
+    },
+    "isSorted": true,
+    "displayAsLabel": false,
+    "audited": false,
+    "readOnly": false,
+    "inlineEditDisabled": false,
+    "default": "Option 1",
+    "tooltip": false,
+    "isCustom": true
+}
+```
+
+Then the labeling of that field name for the GUI will be managed at `custom/Espo/Custom/Resources/i18n/{someInID}/{SomeEntity}.json`
+
+For example, in the "en_US" language file, it might look something like this:
+
+`custom/Espo/Custom/Resources/i18n/en_US/SomeEntity.json`
+
+```
+{
+    "fields": {
+        "someEnumFieldName": "Enum Field Name for the GUI"
+    },
+    "tooltips": {
+        "someEnumFieldName": "This is the text for my tooltip"
+    },
+    "options": {
+        "someEnumFieldName": {
+            "Option 1": "Option 1 Label for GUI",
+            "Option 2": "Option 2 Label for GUI",
+            "Option 3": "Option 3 Label for GUI",
+        }
+    }
+}
+```
+
+When defining an Entity from the backend of the application, you need to keep this in mind as translations are not automatically defined for you.
+

docs/development/entity/entity-base.md

@@ -0,0 +1,94 @@
+# Base Entity
+The Base Entity refers to an Entity that doesn't have associations to Tasks, Activities, and/or History by default. If your entity needs those relationshps out of the box, refer to [Base Plus](../entity/entity-plus.md).
+
+Entity properties are defined in an entityDefs file. 
+
+!!! note 
+
+    If you create the entity through the GUI, that file will reside at `custom/Espo/Custom/Resources/metadata/entityDefs/{YourBaseEntityName}.json`. 
+
+    If you create it as part of a module, the path should be created at `custom/Espo/Modules/{ModuleName}/Resources/metadata/clientDefs/{YourBaseEntityName}.json`.
+
+## Example entityDefs file
+By default, creating a "Base Entity" from the Admin interface generates the following entityDefs file at `custom/Espo/Custom/Resources/metadata/entityDefs/{YourBaseEntityName}.json`.
+
+```
+{
+    "fields": {
+        "name": {
+            "type": "varchar",
+            "required": true,
+            "trim": true,
+            "pattern": "$noBadCharacters"
+        },
+        "description": {
+            "type": "text"
+        },
+        "createdAt": {
+            "type": "datetime",
+            "readOnly": true
+        },
+        "modifiedAt": {
+            "type": "datetime",
+            "readOnly": true
+        },
+        "createdBy": {
+            "type": "link",
+            "readOnly": true,
+            "view": "views/fields/user"
+        },
+        "modifiedBy": {
+            "type": "link",
+            "readOnly": true,
+            "view": "views/fields/user"
+        },
+        "assignedUser": {
+            "type": "link",
+            "required": true,
+            "view": "views/fields/assigned-user"
+        },
+        "teams": {
+            "type": "linkMultiple",
+            "view": "views/fields/teams"
+        }
+    },
+    "links": {
+        "createdBy": {
+            "type": "belongsTo",
+            "entity": "User"
+        },
+        "modifiedBy": {
+            "type": "belongsTo",
+            "entity": "User"
+        },
+        "assignedUser": {
+            "type": "belongsTo",
+            "entity": "User"
+        },
+        "teams": {
+            "type": "hasMany",
+            "entity": "Team",
+            "relationName": "EntityTeam",
+            "layoutRelationshipsDisabled": true
+        }
+    },
+    "collection": {
+        "orderBy": "createdAt",
+        "order": "desc"
+    },
+    "indexes": {
+        "name": {
+            "columns": [
+                "name",
+                "deleted"
+            ]
+        },
+        "assignedUser": {
+            "columns": [
+                "assignedUserId",
+                "deleted"
+            ]
+        }
+    }
+}
+```

docs/development/entity/entity-company.md

@@ -0,0 +1,176 @@
+# Company Entity
+The Company Entity can be used to create a company or organization distinct from the default "Account" Entity that ships with EspoCRM. It includes address fields and links to Tasks, Meetings, Calls, and Emails (Activities & History) by default.
+
+!!! note
+
+    If you create the entity through the GUI, that file will reside at `custom/Espo/Custom/Resources/metadata/entityDefs/{YourCompanyEntityName}.json`. 
+
+    If you create it as part of a module, the path should be created at `custom/Espo/Modules/{ModuleName}/Resources/metadata/clientDefs/{YourCompanyEntityName}.json`.
+
+## Example entityDefs file
+By default, creating a "Base Entity" from the Admin interface generates the following entityDefs file at `custom/Espo/Custom/Resources/metadata/entityDefs/{YourCompanyEntityName}.json`.
+
+```
+{
+    "fields": {
+        "name": {
+            "type": "varchar",
+            "required": true,
+            "trim": true,
+            "pattern": "$noBadCharacters"
+        },
+        "description": {
+            "type": "text"
+        },
+        "website": {
+            "type": "url",
+            "strip": true
+        },
+        "emailAddress": {
+            "type": "email"
+        },
+        "phoneNumber": {
+            "type": "phone",
+            "typeList": [
+                "Office",
+                "Mobile",
+                "Fax",
+                "Other"
+            ],
+            "defaultType": "Office"
+        },
+        "billingAddress": {
+            "type": "address"
+        },
+        "billingAddressStreet": {
+            "type": "text",
+            "maxLength": 255,
+            "dbType": "varchar"
+        },
+        "billingAddressCity": {
+            "type": "varchar",
+            "trim": true
+        },
+        "billingAddressState": {
+            "type": "varchar",
+            "trim": true
+        },
+        "billingAddressCountry": {
+            "type": "varchar",
+            "trim": true
+        },
+        "billingAddressPostalCode": {
+            "type": "varchar",
+            "trim": true
+        },
+        "shippingAddress": {
+            "type": "address",
+            "view": "crm:views/account/fields/shipping-address"
+        },
+        "shippingAddressStreet": {
+            "type": "text",
+            "maxLength": 255,
+            "dbType": "varchar"
+        },
+        "shippingAddressCity": {
+            "type": "varchar",
+            "trim": true
+        },
+        "shippingAddressState": {
+            "type": "varchar",
+            "trim": true
+        },
+        "shippingAddressCountry": {
+            "type": "varchar",
+            "trim": true
+        },
+        "shippingAddressPostalCode": {
+            "type": "varchar",
+            "trim": true
+        },
+        "createdAt": {
+            "type": "datetime",
+            "readOnly": true
+        },
+        "modifiedAt": {
+            "type": "datetime",
+            "readOnly": true
+        },
+        "createdBy": {
+            "type": "link",
+            "readOnly": true,
+            "view": "views/fields/user"
+        },
+        "modifiedBy": {
+            "type": "link",
+            "readOnly": true,
+            "view": "views/fields/user"
+        },
+        "assignedUser": {
+            "type": "link",
+            "required": false,
+            "view": "views/fields/assigned-user"
+        },
+        "teams": {
+            "type": "linkMultiple",
+            "view": "views/fields/teams"
+        }
+    },
+    "links": {
+        "createdBy": {
+            "type": "belongsTo",
+            "entity": "User"
+        },
+        "modifiedBy": {
+            "type": "belongsTo",
+            "entity": "User"
+        },
+        "assignedUser": {
+            "type": "belongsTo",
+            "entity": "User"
+        },
+        "teams": {
+            "type": "hasMany",
+            "entity": "Team",
+            "relationName": "EntityTeam",
+            "layoutRelationshipsDisabled": true
+        },
+        "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
+        }
+    },
+    "collection": {
+        "orderBy": "createdAt",
+        "order": "desc"
+    },
+    "indexes": {
+        "name": {
+            "columns": [
+                "name",
+                "deleted"
+            ]
+        },
+        "assignedUser": {
+            "columns": [
+                "assignedUserId",
+                "deleted"
+            ]
+        }
+    }
+}
+```