\n \n
\n\n \n ```\n\nThe `Access-Control-Allow-Origin` header (see [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)) can be set in the `data/config.php` with the parameter `leadCaptureAllowOrigin`. The default value is `*`.\n\n```\n'leadCaptureAllowOrigin' => '*',\n```\n\n## Lead assignment distribution\n\nBy utilizing the [Workflow](workflows.md) or the [BPM](bpm.md) tools, you can create an assignment rule that will distribute leads among team users. *Round-Robin* and *Least-Busy* rules are available.\n\nTo apply the rule only for leads that are coming through the lead capture form, you can use a condition that checks the *Campaign* field (assuming that you have created a separate campaign record for the lead capture form).\n\nYou can also utilize a Formula script (Administration > Entity Manager > Lead > Formula) to set some additional fields.\n\n## Hooks\n\nIt's possible to catch a lead capture event with built-in [hooks](../development/hooks.md#additional-default-hooks). Requires coding.\n\n## Exposing entry point\n\n*As of v9.2.*\n\nIf there's no access to your CRM from the internet, you need to configure your server to handle requests to specific entry points to have the lead capture functioning.\n\nSet the config parameter `leadCaptureSiteUrl` with the base URL that will be exposed.\n\nYou need to handle the following requests:\n\n- GET `{siteUrl}?entryPoint=leadCaptureForm&id={id}`\n- GET `{siteUrl}?entryPoint=confirmOptIn&id={id}`\n- POST `{siteUrl}/api/v1/LeadCapture/{apiKey}`\n- OPTIONS `{siteUrl}/api/v1/LeadCapture/{apiKey}`\n- POST `{siteUrl}/api/v1/LeadCapture/form/{id}`\n\n## See also\n\n* [Quick tour](https://app.supademo.com/demo/cme8qhb2r3w9lh3pyo4d2hh6k)\n* [Drip email campaign with BPM](bpm-drip-email-campaign.md)\n\n\n"
},
{
"path": "docs/administration/webhooks.md",
"content": "# Webhooks\n\nWebhooks allow other applications to subscribe to specific events happening in EspoCRM and receive data related to those events. Webhooks are supposed to be created via API by other applications. The webhook has a specific *Event* and *URL*. Every time the event occurs, the system will send POST request with some payload to the specified URL.\n\nWebhooks can be created only by API Users (via an API request) and Administrators. An API User has to have *Webhooks* scope enabled in Roles. An API User has also to have access to all entity types for which webhooks are intended to be created.\n\n* [Subscription](#subscription)\n* [Events](#events)\n* [Webhook requests](#webhook-requests)\n* [Error handling](#error-handling)\n* [Signature checking](#signature-checking)\n* [Config parameters](#config-parameters)\n* [Local host URLs](#local-host-urls)\n* [Debugging](#debugging)\n\n## Subscription\n\n### Creating request\n\n`POST api/v1/Webhook`\n\n```json\n{\n \"event\": \"EVENT\",\n \"url\": \"URL\"\n}\n```\n\nParameters:\n\n* `URL` – string – an endpoint;\n* `skipOwn` – boolean – to skip if the event was initiated by the user owning the webhook (as of v9.2).\n\nA Webhook ID and a secret key will be sent back in the response:\n\n* `id` – an ID of created webhook,\n* `secretKey` – a generated secret key,\n\n\n### Deleting request\n\n`DELETE api/v1/Webhook/WEBHOOK_ID`\n\n### Administration\n\nAn administrator can manage webhooks at Administration > Webhooks. It's possible to remove, edit or create webhooks there.\n\n## Events\n\n!!! note\n\n The list of available entity types can be obtained at Administration > Entity Manager.\n\n### ENTITY_TYPE.create\n\nTriggered when a record is created. All record attributes will be sent in a payload.\n\nExample: `Account.create`\n\n### ENTITY_TYPE.update\n\nTriggered when a record is updated. Only updated record attributes will be sent in a payload.\n\nExample: `Account.update`\n\n### ENTITY_TYPE.delete\n\nTriggered when a record is removed.\n\nExample: `Account.delete`\n\n### ENTITY_TYPE.fieldUpdate.FIELD\n\nTriggered when a specific field is updated. New field attributes will be sent in a payload.\n\nExample: `Account.fieldUpdate.assignedUserId`\n\n!!! note\n\n The list of available fields can be obtained at Administration > Entity Manager > fields.\n\n\n## Webhook requests\n\nEvery webhook request (sent by EspoCRM to a specified URL) is of POST type. A content type is *application/json*.\n\nEvents related to the same hook are sent in batches. The request payload is always an array (even if only one record is sent).\n\nOne event occurred:\n\n```json\n[\n {\n \"id\": \"someId\",\n \"name\": \"some name\"\n }\n]\n```\n\nMultiple events occurred:\n\n```json\n[\n {\n \"id\": \"someId1\",\n \"name\": \"some name 1\"\n },\n {\n \"id\": \"someId2\",\n \"name\": \"some name 2\"\n }\n]\n```\n\nRequest sending is processed by the scheduled job *Process Webhook Queue* (Administration > Scheduled Jobs). By default, it runs every 5 minutes. You can change the scheduling.\n\n## Error handling\n\nWhen EspoCRM is trying to send a webhook request and an error occurs, EspoCRM will process it the following ways:\n\n* errors 400, 401, 403, 404, 405, 408, connection timed out, or connection failed - will try to make another attempt;\n* error 410 - hook will be removed immediately.\n\n## Signature checking\n\nIt's possible to check the authenticity of a webhook request by comparing the signature passed in the *Signature* header with a value calculated on the server that receives the request.\n\nExample for PHP:\n\n```php\n$signature = base64_encode($webhookId . ':' . hash_hmac('sha256', $payload, $secretKey));\n```\n\n* *webhookId* can be obtained from the response upon webhook creation or at Administration > Webhooks;\n* *secretKey* can be obtained from the response upon webhook creation or at Administration > Webhooks;\n* *payload* is a payload of the request.\n\n!!! important\n\n Prior to v9.0, the signature was passed in the *X-Signature* header and constructed in a slightly different manner. *X-Signature* will still be passed after v9.0 and will be available until v11.0. If your script checks *X-Signature*, you need to fix it to *Signature*.\n\n\n## Config parameters\n\nCan be set manually in `data/config.php`.\n\n* *webhookMaxCountPerUser* = 50\n* *webhookQueueEventPortionSize* = 20\n* *webhookQueuePortionSize* = 20\n* *webhookBatchSize* = 50\n* *webhookMaxAttemptNumber* = 4\n* *webhookFailAttemptPeriod* = '10 minutes'\n* *webhookConnectTimeout* = 5 (seconds)\n* *webhookTimeout* = 10 (seconds)\n* *webhookAllowedAddressList*\n\n## Local host URLs\n\n*As of v9.3.2*\n\nBy default, internal URLs (like *http://localhost*) are forbidden. To allow, you need to define the needed address in the *webhookAllowedAddressList* config parameter, in the following format *host:port*.\n\n```\n'webhookAllowedAddressList' => ['localhost:80'],\n```\n\n## Debugging\n\nQueues are stored in two database tables: `webhook_queue_item` and `webhook_event_queue_item`. Webhook Queue Items are available from the UI at Administration > Webhooks > menu in the top-right corner > Webhook Queue Items.\n\nYou can enable [debug mode](troubleshooting.md#debug-mode) to see more details in the log.\n"
},
{
"path": "docs/administration/websocket.md",
"content": "# WebSocket\n\nThe WebSocket enables interaction between a server and a client (browser) without the latter making polling requests. Example: When a new notification is received, the server sends the information to the browser in real time.\n\nOut-of-the-box the WebSocket covers the following features:\n\n* New in-app notifications;\n* New event reminders;\n* Updates in stream on the record detail view;\n* Updates of the detail view.\n\n!!! important\n\n You need to have *zmq* php extension installed.\n\nEnable **Use WebSocket** parameter at Administration > Settings.\n\n## Daemon\n\nYou need to run `websocket.php` as a daemon.\n\n### Using systemd\n\nCreate a file `/etc/systemd/system/espocrm-websocket.service`.\n\n```\n[Unit]\nDescription=EspoCRM WebSocket Service\nRequires=mysql.service\nAfter=mysql.service\nStartLimitIntervalSec=0\n\n[Service]\nType=simple\nRestart=always\nRestartSec=5\nUser=www-data\nExecStart=/usr/bin/php /path/to/espocrm/websocket.php\nStandardError=/path/to/espocrm/data/logs/websocket.log\n\n[Install]\nWantedBy=default.target\n```\n\nCommand to get the service to start on boot:\n\n`systemctl enable espocrm-websocket.service`\n\n\nCommand to start the service:\n\n`systemctl start espocrm-websocket.service`\n\n## SSL support\n\nYou need to set up a proxy that will forward SSL requests to our websocket server and vice-versa.\n\n### Apache\n\nYou need to have *proxy* and *proxy_wstunnel* modules installed.\n\n```\nsudo a2enmod proxy\nsudo a2enmod proxy_wstunnel\n```\n\nIn your Apache config inside the *VirtualHost* section for SSL (`\n
\n\n```\n\nOriginal content can be copied from the file `client/modules/crm/res/templates/campaign/unsubscribe.tpl`.\n\nThe same logic is available for Subscribe Again template. Use `subscribeTemplate` parameter to define a custom template.\n"
},
{
"path": "docs/development/coding-practices.md",
"content": "# Backend Coding Practices\n\n## Namespace structure\n\nWithin a module namespace:\n\n- `Entities\\` – entities;\n- `Controllers\\` – record controllers\n (should not implement any additional logic, only extend the Record controller);\n- `EntryPoints\\` – entry points (accessible by `?entryPoint={name}`);\n- `Hooks\\{EntityType}\\` – hooks (such as before-save, after-save);\n- `Tools\\` – domain level code, for business logic;\n- `Tools\\{DomainName}\\Api\\` – API actions (entry points for API);\n- `Tools\\{DomainName}\\Jobs\\` – jobs;\n- `Tools\\{DomainName}\\Exceptions\\` – domain-level exceptions;\n- `Classes\\` – framework related implementations;\n\n\nThe *Classes* namespace structure (recommendations, not strict rules):\n\n- `Classes\\Select\\{EntityType}\\` – Select framework related implementations;\n- `Classes\\Record\\{EntityType}\\` – Record framework related implementations;\n- `Classes\\Acl\\{EntityType}\\` – ACL framework related implementations;\n- `Classes\\AclPortal\\{EntityType}\\` – ACL framework related implementations related to portals;\n- `Classes\\Jobs\\` – scheduled jobs;\n- `Classes\\AppParams\\` – AppParams implementations;\n- `Classes\\Cleanup\\` – Cleanup implementations;\n- `Classes\\MassAction\\` – MassAction implementations;\n- `Classes\\Action\\` – Action implementations;\n- `Classes\\ConsoleCommands\\` – Action implementations;\n- `Classes\\FieldValidators\\{EntityType}\\{Field}` – field validators;\n"
},
{
"path": "docs/development/coding-rules.md",
"content": "# Coding Rules\n\n### 1\\. Never pass Container into class constructors. Pass all dependencies separately.\n\n❗ Bad:\n\n```php\nentityManager\n ->getRDBRepositoryByClass(Account::class)\n ->select(['id', 'name'])\n ->where(['type' => Account::TYPE_CUSTOMER])\n ->order('createdAt')\n ->findOne();\n```\n\n✔️ Good:\n\n```php\nselect(['id', 'name'])\n ->from(Account::ENTITY_TYPE)\n ->order('createdAt')\n ->limit(0, 10)\n ->build();\n\n$sth = $this->entityManager->getQueryExecutor()->execute($query);\n$rows = $sth->fetchAll();\n```\n\n### 3\\. Specify types for method parameters. Also specify the method return type.\n\n❗ Bad:\n\n```php\nisSomethingWrong()) {\n throw new Error(\"Something is wrong.\");\n }\n\n if ($this->hasNoData()) {\n return null;\n }\n\n return $this->value;\n }\n}\n```\n\n### 5\\. Don't write comments, write self explanatory code.\n\nIn addition: Do not write *phpdoc* for non-public methods and properties. It's OK if you don't write *phpdoc* at all (unless needed for static analysis).\n\nException: Adding comments may be reasonable in some rare cases.\n\n❗ Bad (excessive documenting and commenting):\n\n```php\nsanitizeString($string);\n```\n\n✔️ Good (explaining some non-obvious cases):\n\n```php\nplatform === self::SOME) {\n return;\n}\n```\n\n### 6\\. Import classes in the beginning of the file.\n\n❗ Bad:\n\n```php\nisCached()) {\n foreach ($this->itemList as $item) {\n if (!$this->hasItem($item)) {\n $this->loadItem($item);\n }\n }\n }\n }\n```\n\n✔️ Better:\n\n```php\nisCached()) {\n foreach ($this->itemList as $item) {\n $this->processLoadItem($item);\n }\n }\n }\n```\n\n✔️ Good:\n\n```php\nisCached()) {\n $this->processLoadItems();\n }\n }\n```\n\n### 8\\. Use early returns.\n\n❗ Not good:\n\n```php\nconfig->get('emailMessageMaxSize');\n\n if ($maxSize) {\n $size = $storage->getSize($id);\n\n if ($size > $maxSize) {\n $fetchOnlyHeader = true;\n }\n }\n\n return $fetchOnlyHeader;\n }\n```\n\n✔️ Good:\n\n```php\nconfig->get('emailMessageMaxSize');\n\n if (!$maxSize) {\n return false;\n }\n \n $size = $storage->getSize($id);\n \n return $size > $maxSize;\n }\n```\n\n### 8\\. Avoid too many parameters in methods.\n\nLess is better. Four is too much.\n\n❗ Bad:\n\n```php\ncreateBuilder()\n ->where($where)\n ->offset($offset)\n ->limit($limit)\n ->withAclApplied()\n ->find();\n```\n\n### 9\\. Methods that return values should not change state. Methods that change state should not return values.\n\nNot a strict rule but in most cases should be followed.\n\n❗ Bad:\n\n```php\nisProcessed = true;\n \n // do something\n \n return true;\n }\n}\n```\n\n✔️ Good:\n\n```php\nbaseChecker->check($entity);\n\n // some additional logic\n\n return $result;\n }\n}\n```\n\nThe *protected* visibility should be used very sparsely.\n\n### 11\\. Use DTOs rather than associative arrays or stdClass objects.\n\nUse immutable data transfer objects.\n\n❗ Bad:\n\n```php\n $attribute,\n 'value' => $value,\n 'entityType' => $entityType,\n];\n\n$someObject->process($data);\n```\n\n✔️ Good (cloning):\n\n```php\nwithAttribute($attribute)\n ->withValue($value)\n ->withEntityType($entityType);\n \n$someObject->process($data); \n```\n\n✔️ Good (building):\n\n```php\nsetAttribute($attribute)\n ->setValue($value)\n ->setEntityType($entityType)\n ->build();\n \n$someObject->process($data); \n```\n\n✔️ Good (constructor named parameters):\n\n```php\nprocess($data); \n```\n\n### 12\\. Create domain-level repository classes instead of directly accessing the Entity Manager in business logic.\n\nIt keep business logic independent from persistence details and facilitates testability.\n\n✔️ Good\n\n```php\nrepository->getOrders($params);\n\n // ...\n }\n}\n```\n\n✔️ Good\n\n```php\nrepository->save($order);\n }\n}\n```\n"
},
{
"path": "docs/development/collection.md",
"content": "# Collection\n\nA collection is a list of models. See the [class](https://github.com/espocrm/espocrm/blob/stable/client/src/collection.js).\n\n## Methods\n\n### fetch\n\nFetches a collection (from the back-end). Returns a promise.\n\n```js\ncollection.fetch();\n\ncollection.fetch({\n remove: false,\n more: true,\n});\n```\n\nOptions:\n\n* remove – false will prevent removing current models;\n* more – load next portion of records (show-more).\n\nYou can pass custom options and check them in 'change' event listeners.\n\n### clone\n\nClone a collection. Models are kept identical. Returns a collection instance.\n\n### get\n\nGet a model from a collection by an id.\n\n```js\nconst model = collection.get(id);\n```\n\n### at\n\nGet a model by its position in a collection.\n\n```js\nconst model = collection.at(index);\n```\n\n### forEach\n\nIterates through a collection.\n\n```js\ncollection.forEach(model => {});\n```\n\n### add\n\nAdd a model or multiple models to a collection. Firing an 'add' event for each model, and an 'update' event afterwards.\n\n```js\ncollection.add(model);\ncollection.add([model]);\n```\n\n### remove\n\nRemove a model from a collection. Fires a 'remove' event for a model, and an 'update' event afterwards.\n\n```js\ncollection.remove(id);\ncollection.remove(model, {\n // Suppresses events.\n silent: true, \n});\n```\n\n### reset\n\nEmpties a collection.\n\n### push\n\nAdd a model to the end.\n\n### pop\n\nRemove and return the last model.\n\n### unshift\n\nAdd a model at the beginning.\n\n### shift\n\nRemove and return the first model.\n\n### resetOrderToDefault\n\nResets order parameters to default.\n\n### setOrder\n\nSets order parameters.\n\n```\n@param {string|null} orderBy\n@param {boolean|'asc'|'desc'|null} [order]\n@param {boolean} [setDefault]\n```\n\n### abortLastFetch\n\nAbort the last fetch.\n\n### hasMore\n\nWhether more records can be fetched.\n\n### setOffset\n\nSet an offset.\n\n```js\ncollection.setOffset(offset);\n```\n\n### getWhere\n\nGet a where-clause.\n\n## Properties\n\n### entityType\n\n*string*\n\nAn entity type.\n\n### length\n\n*number*\n\nA current length of a collection.\n\n### total\n\n*number*\n\nA total number of records in the backend.\n\n### offset\n\n*number*\n\nA current offset (for pagination).\n\n### maxSize\n\n*number*\n\nA max size to fetch (for pagination).\n\n### where\n\n*Object*\n\nA where clause.\n\n## Instantiating\n\nWith a factory:\n\n```js\n\nexport default class extends View {\n\n setup() {\n this.wait(this.loadCollection());\n }\n\n async loadCollection() {\n this.collection = await this.getCollectionFactory().create('Account');\n\n await this.collection.fetch();\n }\n}\n```\n\nWithout factory:\n\n```js\nimport View from 'view';\nimport Collection from 'collection';\n\nexport default class extends View {\n\n setup() {\n const collection = new Collection();\n // The URL will be used when fetching from the backend.\n collection.url = 'MyEntityType/someEndPoint'; \n\n this.wait(\n collection.fetch()\n );\n }\n}\n```\n\n## Events\n\nNote: `listenTo` and `listenToOnce` are methods of the *view* class.\n\n### sync\n\nOnce a collection is fetched.\n\n```js\nthis.listenTo(collection, 'sync', (collection, response, options) => {});\n```\n\n### update\n\nOnce a collection is updated.\n"
},
{
"path": "docs/development/confirm-dialog.md",
"content": "# Confirmation dialog\n\nShowing a confirmation modal dialog to a user before doing some actions.\n\nAvailable in views.\n\n```js\n this.confirm({\n message: this.translate('someMessageName', 'messages'),\n confirmText: this.translate('Confirm'), // text of the confirmation button\n }).then(() => {\n // here do some actions\n });\n```\n"
},
{
"path": "docs/development/container-services.md",
"content": "# Container Services\n\nConsole command that prints all available container services with their implementing classes:\n\n```\nbin/command app-info --container\n```\n\nMost often used services are listed below.\n\n## entityManager\n\nClass: `Espo\\ORM\\EntityManager`\n\nA central access point to [ORM](orm.md) functionality.\n\n## metadata\n\nClass: `Espo\\Core\\Utils\\Metadata`\n\nApplication [metadata](metadata.md).\n\n## config\n\nClass: `Espo\\Core\\Utils\\Config`\n\nA main application config.\n\n## ormDefs\n\n*As of v7.0.*\n\nClass: `Espo\\ORM\\Defs\\Defs`\n\nEntity definitions (fields, attributes, relations).\n\n## fileManager\n\nClass: `Espo\\Core\\Utils\\File\\Manager`\n\nProvides functions for reading and storing files.\n\n## applicationState\n\nClass: `Espo\\Core\\ApplicationState`\n\nProvides information about an application, current user, portal.\n\n## log\n\nClass: `Espo\\Core\\Utils\\Log`\n\nA logger. Messages are written into `data/log`.\n\n## user\n\nClass: `Espo\\Entities\\User`\n\nA current user. If an application does not require an authentication, then the *system* user is substituted.\n\n## preferences\n\nClass: `Espo\\Entities\\Preferences`\n\nPreferences of a current user.\n\n## aclManager\n\nClass: `Espo\\Core\\AclManager`\n\nProvides access checking functions for any user.\n\n## acl\n\nClass: `Espo\\Core\\Acl`\n\nProvides access checking functions for a current user. A wrapper for *aclManager*.\n\n## fieldUtil\n\nClass: `Espo\\Core\\Utils\\FieldUtil`\n\nAn utility class for obtaining information about fields.\n\n## dateTime\n\nClass: `Espo\\Core\\Utils\\DateTime`\n\nDate-time utility functions.\n\n## number\n\nClass: `Espo\\Core\\Utils\\NumberUtil`\n\nNumber utility functions.\n\n## fileStorageManager\n\nClass: `Espo\\Core\\FileStorage\\Manager`\n\nStores and reads attachment entities.\n\n## language\n\nClass: `Espo\\Core\\Utils\\Language`\n\nLanguage util of a current user.\n\n## defaultLanguage\n\nClass: `Espo\\Core\\Utils\\Language`\n\nA util for a default language of the system.\n\n## baseLanguage\n\nClass: `Espo\\Core\\Utils\\Language`\n\nA util for *en_US* language.\n\n## formulaManager\n\nClass: `Espo\\Core\\Formula\\Manager`\n\nTo run Formula scripts.\n\n## streamService\n\nClass: `Espo\\Tools\\Stream\\Service`\n\n## applicationConfig\n\n*As of v9.1.*\n\nClass: `Espo\\Core\\Utils\\Config\\ApplicationConfig`\n\n## systemConfig\n\n*As of v9.1.*\n\nClass: `Espo\\Core\\Utils\\Config\\SystemConfig`\n\n## session\n\n*As of v10.0.*\n\nInterface: `Espo\\Core\\Session\\Session`\n"
},
{
"path": "docs/development/custom-buttons.md",
"content": "# Custom buttons & dropdown actions for detail, list, edit views\n\n## In top-right corner\n\nHow to add buttons (or dropdown actions) that will appear in the top-right corner.\n\nAn example for the detail view of the *Lead* entity type.\n\n### Definition\n\nCreate a file (if it doesn't exist) `custom/Espo/Custom/Resources/metadata/clientDefs/Lead.json`:\n\n```json\n{\n \"menu\": {\n \"detail\": {\n \"buttons\": [\n \"__APPEND__\",\n {\n \"label\": \"My Action\",\n \"name\": \"myAction\",\n \"style\": \"default\",\n \"acl\": \"edit\",\n \"aclScope\": \"Lead\",\n \"handler\": \"custom:my-action-handler\",\n \"initFunction\": \"initMyAction\",\n \"actionFunction\": \"myAction\",\n \"checkVisibilityFunction\": \"isMyActionVisible\"\n }\n ]\n }\n }\n}\n```\n\nParameters:\n\n* `name` – A name. Mandatory if a handler is used.\n* `handler` – A handler.\n* `initFunction` – A handler method to run on initialization. Omit if not needed. \n* `acl` – Defines what access level is required to see the button. You can omit this parameter.\n* `aclScope` – What scope to check access to. If omitted, the current scope is used.\n* `checkVisibilityFunction` – A handler method that will be used to determine whether an item is visible. The method should return a boolean value. As of v8.1.\n* `iconClass` – An icon class name.\n* `labelTranslation` – A label translation path. Alternative to *label*.\n* `actionFunction` – An action method in the handler. As of v8.1.\n* `index` – A position index. Supported only for buttons. Use negative values to add to the beginning. As of 9.4.\n\nIn order to add dropdown action, you need to use the `dropdown` key instead of *buttons*.\n\nAvailable *style* values:\n\n* `default`\n* `success`\n* `danger`\n* `warning`\n* `text` (as of v10.0)\n\nIn the parameter `accessDataList`, it's possible to define rules that determine whether an action item is visible to a user. See the `module:utils~AccessDefs` JSDoc type in the [source file](https://github.com/espocrm/espocrm/blob/master/client/src/utils.js).\n\nThe parameter `labelTranslation` defines a label translation path. Useful if you don't want to incorporate a new label but use an existing one. Example: `Global.scopeNamesPlural.Opportunity`. \n\nMenu items defined in the `Global.json` file will be applied for all entity types.\n\nAvailable views (object keys in definitions):\n\n* detail\n* edit\n* list\n\n### Handler class\n\nCreate a file `client/custom/src/my-action-handler.js`:\n\n```js\ndefine(['action-handler'], (Dep) => {\n\n return class extends Dep {\n\n initMyAction() {}\n\n async myAction() {\n this.view.disableMenuItem('myAction');\n\n let response;\n\n try {\n response = await Espo.Ajax.getRequest('Lead/' + this.view.model.id);\n } catch (e) {\n this.view.enableMenuItem('myAction');\n\n return;\n }\n\n console.log(response);\n\n this.view.enableMenuItem('myAction');\n } \n\n isMyActionVisible() {\n return !['Converted', 'Dead', 'Recycled'].includes(this.view.model.attributes.status);\n }\n }\n});\n```\n\n## Dropdown action in detail view\n\nAn action item next to the edit button.\n\nAn example for the *Lead* entity type. Menu items defined in the `Global.json` file will be applied for all entity types.\n\n### Definition\n\nCreate a file (if it doesn't exist) `custom/Espo/Custom/Resources/metadata/clientDefs/Lead.json`:\n\n```json\n{\n \"detailActionList\": [\n \"__APPEND__\",\n {\n \"label\": \"Test Action\",\n \"name\": \"test\",\n \"acl\": \"edit\",\n \"handler\": \"custom:my-action-handler\",\n \"initFunction\": \"initTest\",\n \"checkVisibilityFunction\": \"isTestVisible\",\n \"actionFunction\": \"test\"\n }\n ]\n}\n```\n\nParameters:\n\n* `name` ~ A name. Important if a handler is used.\n* `handler` – A handler.\n* `initFunction` – A handler method to run on initialization. Omit if not needed. \n* `acl` – Defines what access level is required to see the button. You can omit this parameter.\n* `checkVisibilityFunction` – A handler method that will be used to determine whether an item is visible. The method should return a boolean value. As of v8.1.\n* `actionFunction` – An action method in the handler. As of v8.1.\n\n### Handler class\n\nCreate a file `client/custom/src/my-action-handler.js`:\n\n```js\ndefine(['action-handler'], (Dep) => {\n\n return class extends Dep {\n\n initTest() {}\n\n async test() {\n const response = await Espo.Ajax.getRequest('Lead/' + this.view.model.id);\n\n console.log(response);\n } \n\n isTestVisible() {\n return !['Converted', 'Dead', 'Recycled'].includes(this.view.model.attributes.status);\n }\n }\n});\n```\n\n## Dropdown action in detail modal view\n\n*As of v7.2.*\n\nEverything is the same as for the detail view. The only difference is that the metadata parameter name is `modalDetailActionList`.\n\n## Mass action in list view\n\nAn action will available in the *Actions* dropdown when you select records on the list view.\n\n*As of v7.0.*\n\nAn example for *Meeting* entity type.\n\nCreate a file (if it doesn't exist) `custom/Espo/Custom/Resources/metadata/clientDefs/Meeting.json`:\n\n```json\n{\n \"massActionList\": [\n \"__APPEND__\",\n \"test\"\n ],\n \"checkAllResultMassActionList\": [\n \"__APPEND__\",\n \"test\"\n ],\n \"massActionDefs\": {\n \"test\": {\n \"handler\": \"custom:test-handler\",\n \"initFunction\": \"initTest\",\n \"actionFunction\": \"test\"\n }\n }\n}\n```\n\nCreate a handler `client/custom/src/test-handler.js`:\n\n```js\ndefine('custom:test-handler', [], () => {\n\n return class {\n\n constructor(view) {\n this.view = view;\n }\n\n initTest() {\n // called when the list view is loaded\n\n // here you can remove the action on a specific condition\n // this.view.removeMassAction('test');\n \n // const acl = this.view.getAcl();\n // const currentUser = this.view.getUser();\n }\n\n /**\n * @param {{entityType: string, action: string, params: Record}} data\n */\n test(data) { \n // Here you can show a modal or send an ajax request.\n // this.view.createView( ... )\n // Espo.Ajax.postRequest( ...)\n }\n }\n});\n\n```\n\nCreate a language file `custom/Espo/Custom/Resources/i18n/en_US/Meeting.json`:\n\n```json\n{\n \"massActions\": {\n \"test\": \"Test\"\n }\n}\n```\n\nClear cache.\n\nYou can use *Mass Action* framework to handle mass actions in the back-end. Available as of v7.0. Send a POST request to the `MassAction` endpoint with data passed to the action method.\n\n## See more\n\nIn Advanced Pack it's possible to create detail view buttons and dropdown items that run workflow actions. A button can be configured to be visible only if specific conditions are met.\n"
},
{
"path": "docs/development/custom-config-parameters.md",
"content": "# Custom config parameters\n\nIn this article it will be shown how to add custom config parameters and how to make them available on the administration panel.\n\nIn the example it's supposed that your module is named `MyModule`. Replace `MyModule` and `my-module` with your real module name.\n\n### 1. Metadata entityDefs > settings\n\nCreate a file `custom/Espo/Modules/MyModule/Resources/metadata/entityDefs/Settings.json`:\n\n```json\n{\n \"fields\": {\n \"myParameter\": {\n \"type\": \"enum\",\n \"options\": [\"Option 1\", \"Option 2\"],\n \"tooltip\": true\n }\n }\n}\n```\n\n### 2. Metadata app > config\n\nCreate a file `custom/Espo/Modules/MyModule/Resources/metadata/app/config.json`:\n\n```json\n{\n \"params\": {\n \"myParameter\": {\n \"level\": \"admin\"\n }\n }\n}\n```\n\nThe *level* parameter defines availability of the config parameter in the front-end.\n\n* `default` – available for logged-in users (applied by default);\n* `global` – available even before logging in;\n* `system` – never available;\n* `internal` – never available for read, admin can write (useful for passwords, secrets; recommended to use the *password* field type) (as of v7.3);\n* `admin` – available only for admin (read and write);\n* `superAdmin` – available only for super-admin (read and write).\n\nThe *readOnly* [parameter](metadata/app-config.md#readonly) disables the ability to change a parameter value for admin users. \n\n### 3. Metadata app > adminPanel\n\nCreate a file `custom/Espo/Modules/MyModule/Resources/metadata/app/adminPanel.json`:\n\n```json\n{\n \"myPanel\": {\n \"label\": \"My Panel\",\n \"itemList\": [\n {\n \"url\": \"#Admin/mySettings\",\n \"label\": \"My Settings\",\n \"iconClass\": \"fas fa-cog\",\n \"description\": \"myDescription\",\n \"recordView\": \"modules/my-module/views/admin/my-settings\"\n }\n ],\n \"order\": 101\n }\n}\n```\n\n### 4. Language files\n\nCreate a file `custom/Espo/Modules/MyModule/Resources/i18n/en_US/Admin.json`:\n\n```json\n{\n \"keywords\": {\n \"myPanel\": \"some search keyword,another search keyword\"\n },\n \"descriptions\": {\n \"myDescription\": \"Description text.\"\n },\n \"labels\": {\n \"My Settings\": \"My Settings\",\n \"My Panel\": \"My Panel\"\n }\n}\n```\n\n\nCreate a file `custom/Espo/Modules/MyModule/Resources/i18n/en_US/Settings.json`:\n\n```json\n{\n \"fields\": {\n \"myParameter\": \"My Parameter\"\n },\n \"tooltips\": {\n \"myParameter\": \"My parameter tooltip text. Markdown supported.\"\n },\n \"options\": {\n \"myParameter\": {\n \"Option 1\": \"Option 1\",\n \"Option 2\": \"Option 2\"\n }\n }\n}\n```\n\n### 5. View\n\nCreate a file `client/custom/modules/my-module/src/views/admin/my-settings.js`:\n\n```js\ndefine(['views/settings/record/edit'], (Dep) => {\n\n return class extends Dep {\n\n detailLayout = [\n {\n rows: [\n [\n {\n name: 'myParameter',\n },\n false,\n ],\n ]\n }\n ]\n\n // Dynamic logic can de defined.\n dynamicLogicDefs: {}\n\n setup() {\n super.setup();\n \n // Some custom logic can be written here.\n }\n }\n});\n```\n\n### 6. Final step\n\nClear cache.\n\nThe parameter value now can be read in the back-end:\n\n```php\nget('myParameter');\n```\n"
},
{
"path": "docs/development/custom-css.md",
"content": "# Custom CSS file\n\nCreate a file `custom/Espo/Custom/Resources/metadata/app/client.json`.\n\n```json\n{\n \"cssList\": [\n \"__APPEND__\",\n \"path/to/your/file.css\"\n ]\n}\n```\n\nMake sure the CSS file is readable by the webserver. It's recommended to put it in `client/custom/css` or `client/custom/modules/{module-name}/css` directory. \n\nThen clear cache.\n"
},
{
"path": "docs/development/custom-entity-type.md",
"content": "# Custom Entity Type\n\nThis article gives information about how to create custom entity types manually (without using the UI).\n\nIn the example, the entity type will be defined in the `custom/Espo/Modules/MyModule` directory which corresponds to the `Espo\\Modules\\MyModule` namespace. You can also define in `custom/Espo/Custom` directory which corresponds to the `Espo\\Custom` namespace.\n\nThe entity type name created in the example is `MyEntity`.\n\nAfter all needed files are created, you need to run rebuild (Administration > Rebuild). It will clear cache and create the database table.\n\n## Metadata\n\n### entityDefs\n\n[Reference](metadata/entity-defs.md)\n\nFile: `custom/Espo/Modules/MyModule/Resources/metadata/entityDefs/MyEntity.json`\n\nDefines entity definitions: fields, links, indexes and parameters.\n\nExample:\n\n```json\n{\n \"fields\": {\n \"name\": {\n \"type\": \"varchar\",\n \"maxLength\": 100,\n \"required\": true\n },\n \"status\": {\n \"type\": \"enum\",\n \"maxLength\": 9,\n \"options\": [\n \"Draft\",\n \"Started\",\n \"Completed\",\n \"Canceled\"\n ],\n \"default\": \"Draft\",\n \"style\": {\n \"Started\": \"primary\",\n \"Completed\": \"success\",\n \"Canceled\": \"info\"\n }\n },\n \"assignedUser\": {\n \"type\": \"link\"\n },\n \"teams\": {\n \"type\": \"linkMultiple\"\n },\n \"createdAt\": {\n \"type\": \"datetime\",\n \"readOnly\": true\n }\n },\n \"links\": {\n \"assignedUser\": {\n \"type\": \"belongsTo\",\n \"entity\": \"User\"\n },\n \"teams\": {\n \"type\": \"hasMany\",\n \"entity\": \"Team\",\n \"relationName\": \"entityTeam\"\n }\n },\n \"indexes\": {\n \"name\": {\n \"columns\": [\"name\"]\n }\n },\n \"collection\": {\n \"textFilterFields\": [\"name\"],\n \"orderBy\": \"createdAt\",\n \"order\": \"desc\"\n }\n}\n```\n\n### scopes\n\n[Reference](metadata/scopes.md)\n\nFile: `custom/Espo/Modules/MyModule/Resources/metadata/scopes/MyEntity.json`\n\nDefines scope parameters.\n\nExample:\n\n```json\n{\n \"module\": \"MyModule\",\n \"entity\": true,\n \"object\": true,\n \"acl\": true,\n \"tab\": true,\n \"importable\": true\n}\n```\n\n### clientDefs\n\n[Reference](metadata/client-defs.md)\n\nFile: `custom/Espo/Modules/MyModule/Resources/metadata/clientDefs/MyEntity.json`\n\nDefines entity type parameters for the frontend.\n\nExample:\n\n```json\n{\n \"controller\": \"controllers/record\"\n}\n```\n\nWithout the *controller* parameter the entity type won't be available in the frontend. *controllers/record* is a build-in standard CRUD controller in the frontend.\n\n## Entity class\n\nFile: `custom/Espo/Modules/MyModule/Entities/MyEntity.php`\n\nExample:\n\n```php\nget('name');\n }\n\n public function setName(string $name): self\n {\n $this->set('name', $name);\n\n return $this;\n }\n\n public function getStatus(): string\n {\n return $this->get('status');\n }\n\n public function setStatus(string $status): self\n {\n $this->set('status', $status);\n\n return $this;\n }\n\n public function getAssignedUserId(): ?string\n {\n $this->get('assignedUserId');\n\n return $this;\n }\n\n public function setAssignedUserId(?string $assignedUserId): self\n {\n $this->set('assignedUserId', $assignedUserId);\n\n return $this;\n }\n\n public function getTeams(): LinkMultiple\n {\n /** @var LinkMultiple */\n return $this->getValueObject('teams');\n }\n\n public function setTeams(LinkMultiple $teams): self\n {\n $this->setValueObject('teams', $teams);\n\n return $this;\n }\n\n public function getCreatedAt(): DateTime\n {\n /** @var DateTime */\n return $this->getValueObject('createdAt');\n }\n}\n```\n\n## Controller class\n\nFile: `custom/Espo/Modules/MyModule/Controllers/MyEntity.php`\n\nA Controller class is needed if you need to have CRUD operations available via the API. That includes the frontend, as the frontend communicates with the backend via the API.\n\nExample:\n\n```php\n {\n \n return class extends BaseFieldView {\n\n // Templates for all view modes.\n detailTemplateContent = ` ... `\n listTemplateContent = ` ... `\n editTemplateContent = ` ... ` \n searchTemplateContent = ` ... `\n \n setup() {}\n }\n});\n```\n\nSee out-of-the-box field types for examples:\n\n* `client/src/views/fields/` — views\n\n### Translation\n\nThe label is used in Entity Manager can be set in `custom/Espo/Custom/Resources/i18n/en_US/Admin.json` in the section `fieldTypes`.\nIf you need to add translation to other language, use [language code](https://en.wikipedia.org/wiki/ISO_639-1)_[Country Code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) instead of `en_US`.\n\nThen you need to clear cache at the administration panel.\n\n### Backend validator\n\nYou can define a validator class in a field metadata file in the `validatorClassName` parameter. See the [barcode field](https://github.com/espocrm/espocrm/blob/stable/application/Espo/Resources/metadata/fields/barcode.json) as an example.\n"
},
{
"path": "docs/development/custom-views.md",
"content": "# Custom views\n\n## Record views\n\nEspoCRM framework provides abilities to define custom views for certain entity types. They must be defined in `clientDefs` category of metadata.\n\n`custom/Espo/Custom/Resources/metadata/clientDefs/YourEntityType.json`\n\n```json\n{\n \"views\": {\n \"list\": \"custom:views/your-entity-type/list\",\n \"detail\": \"custom:views/your-entity-type/detail\",\n \"edit\": \"custom:views/your-entity-type/edit\"\n },\n \"recordViews\": {\n \"list\": \"custom:views/your-entity-type/record/list\",\n \"detail\": \"custom:views/your-entity-type/record/detail\",\n \"edit\": \"custom:views/your-entity-type/record/edit\"\n }\n}\n```\n\n### Detail view\n\n`client/custom/src/views/your-entity-type/record/detail.js`\n\nThe view 'views/record/detail' contains all panels with fields, relations and other data you can see on detail view. It doesn't contain header and buttons in the top-right corner.\n\n```javascript\ndefine('custom:views/your-entity-type/record/detail', ['views/record/detail'], (DetailRecordView) => {\n\n return class extends DetailRecordView {\n\n // custom template, omit if you don't need it\n // template = 'custom:your-entity-type/record/detail'\n \n // custom central view, omit if you don't need it\n // middleView = 'custom:views/your-entity-type/record/detail-middle'\n \n // custom side column view, omit if you don't need it\n // sideView = 'custom:views/your-entity-type/record/detail-side'\n \n // custom bottom view, omit if you don't need it\n // bottomView = 'custom:views/your-entity-type/record/detail-bottom'\n\n setup() {\n super.setup();\n\n this.hideField('someField');\n this.showField('someField');\n\n // custom initialization logic, like binding listening to model changes\n this.listenTo(this.model, 'change:myField', () => {\n this.model.set('anotherField', this.model.get('myField') + ' Hello');\n\n this.hideField('someField');\n this.showField('someField');\n this.setFieldRequired('someField');\n this.setFieldNotRequired('someField');\n\n this.setFieldReadOnly('someField');\n this.setFieldNotReadOnly('someField');\n\n this.hidePanel('activities');\n this.showPanel('history');\n });\n }\n\n afterRender() {\n super.afterRender();\n }\n }\n});\n\n```\n\nYou are able to create a custom template with the following path: `client/custom/res/templates/your-entity-type/record/detail.tpl`\n\n`client/custom/src/views/your-entity-type/detail.js`\n\nDetail view contains a record view and header view.\n\n### Edit view\n\n`client/custom/src/views/your-entity-type/edit.js`\n`client/custom/src/views/your-entity-type/record/edit.js`\n\nThe same as detail but it is used when record is being created or edited not in inline-edit mode.\n\n### List view\n\n`client/custom/src/views/your-entity-type/list.js`\n\nList view contains Record/List view, Header and Search Form View.\n\n`client/custom/src/views/your-entity-type/record/list.js`\n\nThe views 'views/list/record' contains rows of records.\n\n### Extending from specific view\n\nIt's worth to mention that you need to inherit your view class from specific class for your entity if one already exists.\n\n```javascript\ndefine('custom:views/email/record/detail', ['views/email/record/detail'], (EmailDetailRecordView) => {\n return class extends EmailDetailRecordView {}\n});\n```\n\n## Field views\n\nCustom views for specific fields should be specified in entityDefs section of metadata.\n\nExample for Address field of Account entity type.\n\n`custom/Espo/Custom/Resources/metadata/entityDefs/Account.json`\n\n\n```json\n{\n \"fields\": {\n \"address\": {\n \"view\": \"custom:views/account/fields/address\"\n } \n }\n}\n```\n\n`client/custom/src/views/account/fields/address.js`\n\n```js\ndefine('custom:views/fields/address', ['views/fields/address'], (AddressFieldView) => {\n\n return class extends AddressFieldView {\n \n setup() {\n super.setup();\n // some initialization\n }\n\n afterRender() {\n super.afterRender();\n // your customizations executed after the field is rendered\n }\n }\n});\n```\n\n## See also\n\n* [View setup handlers](frontend/view-setup-handlers.md)\n"
},
{
"path": "docs/development/customize-standard-fields.md",
"content": "# Customizing existing fields\n\n## Customizing field type\n\nAn example for the *Address* field type.\n\nCreate a file `custom/Espo/Custom/Resources/metadata/fields/address.json`.\n\n```json\n{\n \"view\": \"custom:views/fields/address\"\n}\n```\n\nCreate a file `client/custom/src/views/fields/address.js`.\n\n```js\ndefine(['views/fields/address'], (AddressFieldView) => {\n\n return class extends AddressFieldView {\n\n //detailTemplateContent = ' ... '\n //editTemplateContent = ' ... '\n //listTemplateContent = ' ... '\n //listLinkTemplateContent = ' .. '\n \n setup() {\n super.setup();\n }\n\n afterRender() {\n super.afterRender();\n // your customizations executed after the field is rendered\n }\n }\n});\n```\n\nCreate a template file (if needed) `client/custom/res/templates/fields/address/detail.tpl`.\n\n## Customizing specific field\n\n### Changing field type of existing field\n\nAn example for the *Meeting*'s *Name* field.\n\nCreate (or edit if exists) a file `custom/Espo/Custom/Resources/metadata/entityDefs/Meeting.json`.\n\n```json\n{\n \"fields\": {\n \"name\": {\n \"type\": \"enum\"\n }\n }\n}\n```\n\n### Custom view for specific field\n\nAn example for the *Meeting*'s *Name* field.\n\nCreate (or edit if exists) a file `custom/Espo/Custom/Resources/metadata/entityDefs/Meeting.json`.\n\n```json\n{\n \"fields\": {\n \"name\": {\n \"view\": \"custom:views/meeting/fields/name.js\"\n }\n }\n}\n```\n\nFile `client/custom/src/views/meeting/fields/name.js`:\n\n```js\ndefine(['views/fields/varchar'], (VarcharFieldView) => {\n\n return class extends VarcharFieldView {\n \n setup() {\n super.setup();\n // some initialization\n }\n\n afterRender() {\n super.afterRender();\n // your customizations executed after the field is rendered\n }\n }\n});\n```\n"
},
{
"path": "docs/development/db-indexes.md",
"content": "# Database indexes\n\nProper database indexes can drastically improve a performance of list view loading, reports, search operations etc.\n\nAfter changes you need to rebuild database. It's better to do from CLI to avoid timeout issue.\n\nCommand to run rebuild:\n\n```\nphp rebuild.php\n```\n\n## Defining indexes\n\nIndexes are defined in metadata > entityDefs.\n\n### Example\n\nFor *Lead* entity type.\n\n`custom/Espo/Custom/Resources/metadata/entityDefs/Lead.json`:\n\n\n```json\n{\n \"indexes\": {\n \"myIndexNameOne\": {\n \"columns\": [\"columnName\"] \n },\n \"myIndexNameTwo\": {\n \"columns\": [\"columnNameOne\", \"columnNameTwo\"] \n },\n \"myUniqueIndexName\": {\n \"type\": \"unique\",\n \"columns\": [\"id\", \"columnNameOne\", \"columnNameTwo\"] \n }\n }\n}\n```\n\nNote: Column names should be in camel case.\n\nYou need to run rebuild after changes.\n\n## Forcing index usage in ORM\n\nYou need to specify an index name in *useIndex* param.\n\n```php\ngetQueryBuilder()\n ->select()\n ->from($entityType) \n ->where($whereClause)\n ->useIndex('myIndexNameOne')\n ->build();\n \n$collection = $entityManager->getRDBRepository($entityType)\n ->clone($query)\n ->find();\n```\n\n## Relationship table indexes\n\nIn entityDefs:\n\n```json\n{\n \"links\": {\n \"linkName\": {\n \"additionalColumns\": {\n \"role\": {\n \"type\": \"varchar\"\n }\n },\n \"indexes\": {\n \"role\": {\n \"columns\": [\"role\"]\n }\n }\n }\n }\n} \n```\n"
},
{
"path": "docs/development/di.md",
"content": "# Dependency Injection\n\nThe Dependency Injection framework provides needed dependencies to classes (usually via a constructor). For example, if your hook needs the EntityManager service, you just define it as a constructor parameter.\n\nFor example, your controller has a dependency on some service class. That service class has other dependencies (e.g. the entity manager, some utility classes), these dependencies can have their own dependencies and so on. You don't need to instantiate dependencies, you just define them in class constructors and the framework provides them automatically.\n\n```\n- MyController\n - MyService\n - EntityManager (container service)\n - MyUtilityClass1\n - EntityManager (container service)\n - FileStorageManager (container service)\n - MyUtilityClass2\n```\n\nIn this article:\n\n* [Container services](#container-services)\n* [Injectable factory](#injectable-factory)\n* [Binding](#binding)\n* [See also](#see-also)\n\nThere are two classes responsible for the dependency injection in EspoCRM:\n\n* Container – `Espo\\Core\\Container` [class](https://github.com/espocrm/espocrm/blob/master/application/Espo/Core/Container.php);\n* InjectableFactory – `Espo\\Core\\InjectableFactory` [class](https://github.com/espocrm/espocrm/blob/master/application/Espo/Core/InjectableFactory.php).\n\n## Container services\n\nThe Container contains services. These services are supposed to be used in multiple places throughout the system. **Lazy initialization** is used, meaning that a service is not loaded until it's asked (as a dependency).\n\nContainer services are defined:\n\n* in [metadata](metadata.md) (app > containerServices);\n* by loader classes (in `Espo\\Core\\Loaders` namespace);\n\n!!! note\n\n The best practice is not to require the *container* in your classes, and never use it directly. A specific service can be required in a constructor or with Aware interface.\n\nConsole command that prints all available container services with their implementation classes:\n\n```\nbin/command app-info --container\n```\n\nMost used container services are listed [here](container-services.md).\n\n### Defining\n\nIf you need to define your custom container services, do it in metadata. In your module or in the custom folder:\n\n* `custom/Espo/Modules/{YourModule}/Resources/metadata/app/containerServices.json`;\n* `custom/Espo/Custom/Resources/metadata/app/containerServices.json`.\n\nWhen defining in metadata there are 2 options:\n\n* specify a class for a service;\n* specify a loader that loads a service (the loader should implement `Espo\\Core\\Container\\Loader` interface).\n\nA definition example:\n\n```json\n{\n \"myService1\": {\n \"className\": \"Espo\\\\Modules\\\\MyModule\\\\MyService1\"\n },\n \"myService2\": {\n \"loaderClassName\": \"Espo\\\\Modules\\\\MyModule\\\\MyService2Loader\"\n }\n}\n```\n\nThen you need to bind a class name to the service.\n\nFile `custom/Espo/Modules/MyModule/Binding.php`:\n\n```php\nbindService('Espo\\\\Modules\\\\MyModule\\\\MyService1', 'myService1');\n }\n}\n```\n\nNeeded dependencies will be passed to a class constructor upon instantiation. Parameter type hinting and binding (processed on application start) will be used (via reflection) to detect dependencies.\n\nExample:\n\n```php\ninjectableFactory->create(Something::class);\n }\n}\n```\n\n### Constructor injection\n\n*A recommended way.*\n\nBinding and constructor parameter names are used to detect service dependencies.\n\nResolving process:\n\n* Tries to resolve by binding (see below about binding); exits if success;\n* Tries to resolve by a parameter name, assuming that the parameter name matches the service name and the type hint matches the service class; exits if success;\n* Creates a new instance if the type hint is a class.\n\nIf a dependency is not a service, a new instance will be created every time the dependency is requested. See below.\n\n```php\nentityManager;\n // $this->metadata;\n }\n}\n```\n\nUsing setter injections may be reasonable when you are extending from an existing class and want to add additional dependencies.\n\nLimitation: Only container services can be injected via setters.\n\n!!! note\n\n It's not a recommended way to inject dependencies. Use it as a last resort if you don't want to modify an existing constructor signature.\n\n### Manual instantiating\n\nThis way is supposed to be utilized in factory classes.\n\n```php\ncreate(SomeClass::class);\n```\n\nYou can specify constructor injections explicitly using *createdWith* method. Those that are not specified, will be tried to be resolved using *ReflectionClass*.\n\n```php\ncreateWith($className, [\n 'parameterName1' => $value1,\n 'parameterName2' => $value2,\n]);\n```\n\nFactory example:\n\n```php\ninjectableFactory->createWith(SomeType::class, [\n 'userId' => $userId, \n ]);\n } \n}\n```\n\nIt's also possible to pass a binding container when creating with the injectable factory. More info below.\n\n## Binding\n\nThere is the ability to bind interfaces to implementations and bind parameter names to specific values. Binding is used for resolving dependencies passed through a constructor.\n\nCustom binding can be set up in a `Binding` class of a module:\n\n* `Espo\\Modules\\{ModuleName}\\Binding`\n* `Espo\\Custom\\Binding`\n\n!!! note\n\n The module order parameter is used when binding is processed. Meaning that modules with a lower order value will be processed first.\n\nCLI command to print all bindings:\n\n```\nbin/command app-info --binding\n```\n\nThe default binding is set up in `Espo\\Binding`.\n\n### Example\n\nFile `custom/Espo/Modules/MyModule/Binding.php`:\n\n```php\nbindService('Espo\\\\SomeServiceName', 'someServiceName')\n ->bindImplementation('Espo\\\\SomeInterface', 'Espo\\\\SomeImplementation');\n\n $binder\n ->bindService('Espo\\\\SomeServiceName $name', 'anotherServiceName');\n \n $binder\n ->for('Espo\\\\SomeClass')\n ->bindImplementation('Espo\\\\SomeInterface', 'Espo\\\\SomeImplementation')\n ->bindValue('$paramName', 'Some Value')\n ->bindCallback(\n 'Espo\\\\AnotherClass', \n // Callback arguments are resolved automatically.\n function (SomeDependency $dependency) { \n return $dependency->getSomething();\n }\n );\n }\n}\n```\n\nExplanation:\n\n* If any class requires `Espo\\SomeServiceName`, give the container service `someServiceName`.\n* If any class requires `Espo\\SomeInterface`, give an instance of `Espo\\SomeImplementation`.\n* If any class requires `Espo\\SomeServiceName ` and a parameter name is `$name`, then give `anotherServiceName` service.\n* When `Espo\\SomeClass` requires `Espo\\SomeInterface`, give an instance of `Espo\\SomeImplementation`.\n* When `Espo\\SomeClass` is instantiated, pass the value 'Same Value' for the parameter `$paramName`.\n* When `Espo\\SomeClass` is instantiated, use the callback to resolve a value of the parameter with the type `Espo\\AnotherClass`.\n\n### Binding to implementation\n\nBind an interface to a specific implementation.\n\n```php\nbindImplementation(SomeInterface::class, SomeImplementation::class);\n```\n\n### Binding to service\n\nBind an interface to a specific [service](container-services.md).\n\n```php\n$binder->bindService(SomeInterface::class, 'someServiceName');\n```\n\n### Binding to factory\n\n*As of v7.0.*\n\nBind an interface to a specific factory so that a specific dependency will be created by a specific factory. The factory should implement `Espo\\Core\\Binding\\Factory` interface.\n\n```php\nbindFactory(SomeInterface::class, SomeFactory::class);\n```\n\n### Binding to callback\n\nA callback will be used for creating a specific instance. The callback can have its own dependencies.\n\n```php\nbindCallback(SomeInterface::class, function (SomeDependency $dependency) {\n // Create an instance here.\n return $instance;\n});\n```\n\n### Using with Injectable Factory\n\n*As of v7.0.*\n\nIt's possible to override default binding when creating instances with the injectable factory (usually this will be processed in your factory classes).\n\nThe binding will be applied to all dependencies of the class, including dependencies of dependencies and so on.\n\nExample:\n\n```php\nbindInstance(SomeInterface::class, $someInstance)\n ->inContext(SomeClass::class, function (ContextualBinder $binder): void {\n // Bind dependencies of `SomeClass`.\n $binder->bindValue('$parameterName', 'some value');\n })\n ->build();\n \n$instance = $injectableFactory->createWithBinding(SomeClass::class, $bindingContainer);\n```\n\nThe passed binding has a higher priority than the default binding (the default binding is applied globally to all objects resolved via DI).\n\n## See also\n\n* [Container services](container-services.md)\n"
},
{
"path": "docs/development/duplicate-check.md",
"content": "# Custom duplicate check\n\nDuplicate check is performed upon record creation. Optionally, it can be enabled for record update.\n\n*As of v7.0.*\n\nYou need to define a class name in metadata: recordDefs > {entityType} > duplicateWhereBuilderClassName. The class should implement `Espo\\Core\\Duplicate\\WhereBuilder` interface.\n\n### Example\n\nCreate `custom/Espo/Custom/Resources/metadata/recordDefs/Lead.json`:\n\n```json\n{\n \"duplicateWhereBuilderClassName\": \"Espo\\\\Custom\\\\Classes\\\\DuplicateWhereBuilders\\\\Lead\"\n}\n```\n\nCreate a file `custom/Espo/Custom/Classes/DuplicateWhereBuilders/Lead.php`:\n\n```php\nget('firstName') || $entity->get('lastName')) {\n $orBuilder->add(\n Cond::and(\n Cond::equal(\n Cond::column('firstName'),\n $entity->get('firstName')\n ),\n Cond::equal(\n Cond::column('lastName'),\n $entity->get('lastName')\n )\n )\n );\n\n $toCheck = true;\n }\n \n // Here you can add more conditions.\n \n if (!$toCheck) {\n return null;\n }\n\n return $orBuilder->build();\n }\n}\n```\n\nYou can find built-in duplicate where-builders [here](https://github.com/espocrm/espocrm/tree/master/application/Espo/Classes/DuplicateWhereBuilders). You can reuse them for your entity.\n\n## Checking for duplicates when update\n\nDisabled by default. Can be enabled in metadata: recordDefs > {entityType} > updateDuplicateCheck.\n\n```json\n{\n \"updateDuplicateCheck\": true\n}\n```\n"
},
{
"path": "docs/development/dynamic-handler.md",
"content": "# Dynamic Handler (complex dynamic forms)\n\nDynamic Handler provides the ability to manipulate the form (detail/edit views) appearance.\n\nNote that you can make forms dynamic with [Dynamic Logic](../administration/dynamic-logic.md) feature. Dynamic Handler is intended for more complex tasks where Dynamic Logic can be useless.\n\nAn example for the *Account* entity type.\n\nCreate a file `custom/Espo/Custom/Resources/metadata/clientDefs/Account.json`:\n\n```json\n{\n \"dynamicHandler\": \"custom:account-dynamic-handler\"\n}\n```\n\nCreate a file `client/custom/src/account-dynamic-handler.js`:\n\n```js\n\ndefine('custom:account-dynamic-handler', ['dynamic-handler'], (Dep) => {\n\n return class extends Dep {\n\n // Called on initialization.\n init() {\n this.control();\n\n // Invoke 'control' method every time assignedUserId gets changed.\n this.recordView.listenTo(this.model, 'change:assignedUserId', () => this.control());\n \n // Changing another attribute on status change.\n this.recordView.listenTo(this.model, 'change:status', (model, value, options) => {\n if (!options.ui) {\n // Skip if the change was initiated not by a user interaction.\n // Important.\n return;\n }\n \n if (value === 'Some Status') {\n setTimeout(() => this.model.set('someField', 'someValue'), 1);\n }\n });\n }\n\n control() { \n // if assigned user is not empty\n if (this.model.get('assignedUserId')) { \n this.recordView.showField('sicCode');\n\n this.recordView.setFieldRequired('type');\n this.recordView.setFieldReadOnly('teams');\n\n // set options\n // actual for enum/array/multi-enum/checklist/varchar fields types\n this.recordView.setFieldOptionList('type', ['Test', 'Hello']);\n\n this.recordView.showPanel('activities');\n \n return;\n }\n\n this.recordView.hideField('sicCode');\n this.recordView.setFieldNotRequired('type');\n this.recordView.setFieldNotReadOnly('teams');\n this.recordView.setFieldOptionList('type', ['Test']);\n this.recordView.hidePanel('activities');\n }\n }\n});\n```\n\nThen, clear cache.\n\n!!! note\n\n If you set model attributes from a model-change listener callback, you might need to use *setTimeout* with a zero or a small interval value. It will prevent some side effects.\n\n## Multiple dynamic handlers\n\nIt's possible to add multiple dynamic handlers to for one entity type. This allows different extensions to have their own dynamic handler.\n\nIn metadata > YourEntityType > clientDefs:\n\n```json\n{\n \"dynamicHandlerList\": [\n \"__APPEND__\",\n \"custom:my-dynamic-handler\"\n ]\n}\n```\n\n## Record view methods\n\nThe list of record view methods that may be useful in a dynamic handler.\n\n* hideField\n* showField\n* setFieldReadOnly\n* setFieldNotReadOnly\n* setFieldRequired\n* setFieldNotRequired\n* setFieldOptionList\n* resetFieldOptionList\n* showPanel\n* hidePanel\n* stylePanel\n* unstylePanel\n\n## See also\n\n* [Example for multi-enum fields](examples/dynamic-logic-multi-enum.md)\n"
},
{
"path": "docs/development/email-sending.md",
"content": "# Email Sending\n\nExample:\n\n```php\nemailFactory->create();\n \n $email->setSubject('Subject');\n $email->setBody('Email Body');\n $email->addToAddress('some@address.com');\n $email->setFromAddress('some@address.com'); // optional; if not specified, the system address will be used\n $email->setIsPlain(); // Html is by default\n \n $smtpParams = SmtpParams::create(); // build SMTP params (optionally)\n\n $this->emailSender\n ->withSmtpParams($smtpParams) // optional\n ->withAttachments([$attachment]) // optional, to send with attachments\n ->send($email);\n }\n}\n```\n"
},
{
"path": "docs/development/entry-points.md",
"content": "# Entry Points\n\nEntry points offer distinct access routes to the application, each serving different functions apart from the REST API.\n\nEntry points are accessed by the following URL: `https://your-site-url?entryPoint={entryPointName}`. Note that *entryPointName* must start with a lower case letter.\n\nUsage examples:\n\n* file downloading;\n* rendering a web form that does not require authentication.\n\nEntry point classes are located in `Espo\\Module\\{ModuleName}\\EntryPoint` namespace.\n\n## Creating entry point\n\nAssuming that our module is named *ModuleName*.\n\nCreate a file `custom/Espo/Custom/Modules/ModuleName/EntryPoints/MyEntryPoint.php`:\n\n```php\nwithData(['key' => 'value']);\n\n $this->actionRenderer->write($response, $params);\n }\n}\n```\n"
},
{
"path": "docs/development/examples/dynamic-logic-multi-enum.md",
"content": "# Example: Dynamic handler for multi-enum fields\n\nSee [the dynamic handler documentation](../dynamic-handler.md).\n\nIn this example we have two multi-enum fields `continents` and `countries`. We will make the logic that depending on selected continents only countries of those continents will be available for selection.\n\n1\\. Create (or open if exists) a file `custom/Espo/Custom/Resources/metadata/clientDefs/YourEntityType.json` (`YourEntityType` is the name of your entity type):\n\n```json\n{\n \"dynamicHandler\": \"custom:my-dynamic-handler\"\n}\n```\n\n2\\. Create a file `client/custom/src/my-dynamic-handler.js`:\n\n```js\ndefine('custom:my-dynamic-handler', ['dynamic-handler'], (Dep) => {\n\n return class extends Dep {\n\n init() {\n this.controlFields();\n this.recordView.listenTo(this.model, 'change:continents', () => this.controlFields());\n }\n\n controlFields() {\n const selectedContinentList = this.recordView.model.get('continents') || [];\n\n const continentList = ['Africa', 'Asia', 'Europe', 'America'];\n\n const countryMap = {\n 'Africa': ['Nigeria', 'Ethiopia'],\n 'Asia': ['India', 'Pakistan'],\n 'Europe': ['United Kingdom', 'France'],\n 'America': ['United States', 'Canada', 'Brazil'],\n };\n\n const countryList = [];\n\n for (const continent of selectedContinentList) {\n countryList = countryList.concat(\n countryMap[continent] || []\n );\n }\n\n this.recordView.setFieldOptionList('countries', countryList);\n }\n }\n});\n```\n\n3\\. Clear cache at Administration > Clear Cache.\n\n4\\. You need to refresh a page in your browser.\n"
},
{
"path": "docs/development/extension-packages.md",
"content": "# Making extension package\n\n!!! note\n\n It's recommended to use the [ext-template](https://github.com/espocrm/ext-template) repository for extension development.\n\nExtensions allow you to add extra functionality to EspoCRM. They can be installed at Administrator panel.\n\nThe file structure of the package:\n\n* `manifest.json` – a file that contains extension properties;\n* `files/` – a directory that contains extension files;\n* `scripts/` – a directory that contains extension scripts.\n\n## Manifest\n\n```json\n{\n \"name\": \"Extension Name\",\n \"version\": \"1.0.0\",\n \"acceptableVersions\": [\n \">=7.4.0\"\n ],\n \"php\": [\n \">=8.1\"\n ],\n \"releaseDate\": \"2019-10-22\",\n \"author\": \"Your name\",\n \"description\": \"Description of your extension\"\n}\n```\n\nSyntax of `version` is described by the v2.0.0 the [SemVer](http://semver.org) specification. It's possible to define [ranges](https://getcomposer.org/doc/articles/versions.md#version-range) in `acceptableVersions`.\n\n## Files\n\nAll extension files should be placed in `files` directory. They will be copied to EspoCRM core directory.\n\n## Scripts\n\nFor different purposes EspoCRM supports the following types of scripts. All of them should be placed in `scripts` directory.\n\n* `BeforeInstall.php` – a script executed before an installation process;\n* `AfterInstall.php` – executed once the installation process is finished;\n* `BeforeUninstall.php` – executed before uninstallation process;\n* `AfterUninstall.php` – executed once the uninstallation process is finished.\n\nExample:\n\n```php\ngetByClass(Config::class);\n \n $configWriter = $container->getByClass(InjectableFactory::class)\n ->create(ConfigWriter::class)\n \n $tabList = $config->get('tabList') ?? [];\n \n if (!in_array('MyCustomEntity', $tabList)) {\n $tabList[] = 'MyCustomEntity';\n \n $configWriter->set('tabList', $tabList);\n }\n \n $configWriter->save();\n }\n}\n```\n\n## Package\n\nIn the end, we need to pack all these files into a ZIP archive.\n\n## Template repository\n\nYou can use this [template repository](https://github.com/espocrm/ext-template) to create a git repository for your extension.\n\n## Recommendations\n\n!!! note\n\n It's recommended to give some prefix to names of your custom entity types. E.g. `MyPrefixMyEntityTypeName`, this prefix can be the name of your company.\n It will prevent possible conflicts with other extensions.\n"
},
{
"path": "docs/development/frontend/ajax.md",
"content": "# Ajax Requests\n\nThe *Espo.Ajax* object is used to make requests to Espo API endpoints. See the [source file](https://github.com/espocrm/espocrm/blob/master/client/src/ajax.js) with JSDoc for more info. An API base path `api/v1` is prepended to each request URL. \n\nGET:\n\n```js\nEspo.Ajax.getRequest(url, data, options)\n .then(response => {})\n .catch(xhr => {});\n```\n\nPOST:\n\n```js\nEspo.Ajax.postRequest(url, data, options)\n .then(response => {})\n .catch(xhr => {\n if (xhr.status === 403) {\n // Prevent error handling in the global handler.\n xhr.errorIsHandled = true;\n // Do something.\n }\n });\n```\n\nExample:\n\n```js\nEspo.Ajax.getRequest('MyController/action/getSomeDataById', {id: id})\n .then(response => {\n // A parsed response.\n console.log(response);\n });\n```\n\n## Request options\n\n* `[timeout] {Number}` A timeout in milliseconds.\n* `[headers] {Object.\n
\n\n
\n \n
\n \n Custom text\n
\n\n {{translate 'unsubscribed' category='messages' scope='Campaign'}}\n
\n\n
\n \n \n
\n```\n\n## Dropdown\n\n```html\n\n \n \n \n \n
\n```\n\nThe class `pull-right` is used to align the menu to the right side.\n\n## Panel\n\n```html\n\n
\n```\n\nStyle classes:\n\n* `panel-default`\n* `panel-success`\n* `panel-danger`\n* `panel-warning`\n* `panel-info`\n* `panel-primary`\n\n\nPanel body classes:\n\n* `panel-body-form` – for panels containing a form;\n\n## Table\n\n```html\n\n
\n Title
\n\n
\n- \n \n
\n \n
\n```\n\n## Grid\n\n### Columns\n\n12 columns system:\n\n```html\n\n (field-element)\n
\n\n \n \n \n
\n```\n\n```html\n\n \n \n
\n```\n\n```html\n\n \n
\n```\n\nSupported screen widths:\n\n* `xs` – phones, 480px;\n* `sm` – tablets, 768px;\n* `md` – medium, 992px;\n* `lg` – large, 1200px;\n\n### Auto-fill grid\n\n```html\n\n \n \n \n
\n```\n\nSizes:\n\n* `xxs`\n* `xs`\n* `sm`\n* `md`\n\n## Type\n\n### Text\n\nStyle:\n\n* `text-soft`\n* `text-muted`\n* `text-primary`\n* `text-success`\n* `text-danger`\n* `text-warning`\n* `text-info`\n* `text-bold`\n* `text-italic` (as of v8.0)\n* `text-strikethrough` (as of v8.2)\n\nSize:\n\n* `text-large`\n* `text-2em`\n* `text-3em`\n* `text-4em`\n* `text-5em`\n* `text-6em`\n\n\n### Label\n\n```html\nText\n```\n\nStyle classes:\n\n* `label-default`\n* `label-primary`\n* `label-success`\n* `label-danger`\n* `label-warning`\n* `label-info`\n\nSize classes:\n\n* `label-md`\n\n## Misc\n\nCentering:\n\n* `center-align` – applies `text-align: center`;\n\nA horizontally centered block:\n\n* `block-center`\n* `block-center-sm`\n* `block-center-md`\n\nA container that horizontally & vertically centers its child:\n\n* `container-centering`\n\nBorder radius:\n\n* `radius-left` – forces an element to have border radius on the left;\n* `radius-right` – forces an element to have border radius on the right;\n\nFloating:\n\n* `pull-left` – applies `float: left`;\n* `pull-right` – applies `float: right`;\n\nCancelling margins:\n\n* `no-margin` – cancels margins for an element contained in a panel and other containers;\n* `no-side-margin` – cancels side margins for an element contained in a panel and other containers;\n\nMargins:\n\n* `margin` – applies a margin to all sides;\n* `margin-top-sm`\n* `margin-top`\n* `margin-top-2x`\n* `margin-bottom-sm`\n* `margin-bottom`\n* `margin-bottom-2x`\n* `margin-bottom-3x`\n* `margin-bottom-4x`\n"
},
{
"path": "docs/development/frontend/monkey-patching.md",
"content": "# Monkey patching\n\n[Monkey patching](https://en.wikipedia.org/wiki/Monkey_patch) allows you to dynamically extend any frontend class.\n\n\n!!! warning\n\n Monkey patching is not considered an upgrade-safe method and should be used as a last resort.\n\n1\\. Define the JS file that will be loaded with the Espo page.\n\nCreate `custom/Espo/Custom/Resources/metadata/app/client.json`:\n\n```json\n{\n \"scriptList\": [\n \"__APPEND__\",\n \"client/custom/my-patch.js\"\n ],\n \"developerModeScriptList\": [\n \"__APPEND__\",\n \"client/custom/my-patch.js\"\n ]\n}\n```\n\nNote that *developerModeScriptList* is only needed when you use the developer mode.\n\nAfter that, clear cache.\n\n2\\. Create a patching JS file.\n\nCreate `client/custom/my-patch.js`:\n\n```js\n/**\n * In this example, we extend the login view.\n */\nrequire(['views/login'], View => {\n\n const defaultAfterRender = View.prototype.afterRender;\n\n // Extending the `afterRender` method.\n View.prototype.afterRender = function () {\n defaultAfterRender.call(this);\n\n // Custom code here.\n console.log(\"Custom login view is rendered.\");\n };\n});\n```\n\nNote that you can patch multiple classes in one file.\n"
},
{
"path": "docs/development/frontend/record-panels.md",
"content": "# Custom panel on record (detail & edit) view\n\nAn example for *Account* entity type.\n\nCreate a file `custom/Espo/Custom/Resources/metadata/clientDefs/Account.json`:\n\n```json\n{\n \"sidePanels\": {\n \"detail\": [\n \"__APPEND__\",\n {\n \"name\": \"myTestPanel\",\n \"label\": \"My Test Panel\",\n \"view\": \"custom:views/account/panels/my-test-panel\",\n \"aclScope\": \"Account\",\n \"acl\": \"edit\"\n }\n ]\n }\n}\n```\n\nWe have defined a side panel for *detail* view. The following views are available:\n\n* detail\n* edit\n* detailSmall\n* editSmall\n\nYou can also define a bottom panel. Use *bottomPanels* key instead.\n\n\nThe values of parameters *aclScope* and *acl* mean, that the panel will be visible only if the user has *edit* access to *Account* entity type. You can omit both parameters.\n\nCreate a file `client/custom/src/views/account/panels/my-test-panel.js`:\n\n```js\ndefine(['views/record/panels/side'], (SidePanelView) => {\n\n return class extends SidePanelView {\n\n templateContent = '{{viewObject.someKey}}
'\n\n setup() {\n this.someKey = 'Hello';\n }\n }\n});\n\n```\n\nNote, that if you define a bottom panel, you need to extend from `views/record/panels/bottom`.\n\nSee more [information](../view.md) about views.\n\n"
},
{
"path": "docs/development/frontend/save-error-handlers.md",
"content": "# Save error handlers\n\nWhen a record is being saved, it's possible to throw an exception in the backend and then handle it in the frontend.\n\nIn the backend the exception should be thrown with the *reason* parameter in the body. It can be done from a before-create or before-update [record hooks](../metadata/record-defs.md#beforereadhookclassnamelist).\n\nOnly `Conflict` and `Error` exceptions are supported.\n\n```php\n 'someValue1',\n 'someKey2' => 'someValue2',\n ])\n);\n```\n\n!!! note\n\n It's also possible to throw exceptions with formula in [API before-save script](../../administration/api-before-save-script.md).\n\nDefine a handler in metadata.\n\n`custom/Espo/Custom/Resources/metadata/clientDefs/{EntityType}.json`:\n\n```json\n{\n \"saveErrorHandlers\": {\n \"myReason\": \"custom:my-error-handler\"\n }\n}\n```\n\nIt's also possible to define handlers for all entity types in `custom/Espo/Custom/Resources/metadata/clientDefs/Global.json`.\n\nCreate a handler `client/custom/src/my-error-handler.js`:\n\n```js\n\ndefine('custom:my-error-handler', [], function () {\n\n return class {\n constructor(view) {\n /** @type {module:views/record/detail.Class} */\n this.view = view;\n }\n\n process(data) {\n Espo.Ui.error('Some error message.', true);\n \n // Some logic.\n }\n }\n});\n```\n"
},
{
"path": "docs/development/frontend/templates.md",
"content": "# Templates\n\nA template of a [view](../view.md) is used to render an HTML. Before rendering, the view passes data to the template. Templates can be stored in separate .tpl files or defined right in a the view's `templateContent` property. [Handlebars](https://handlebarsjs.com) library is used for templating.\n\n## Expressions\n\nExpressions are enclosed by double curly braces `{{}}`.\n\n```\n{{name}}\n```\n### Path\n\nWith dot-separated paths it's possible to look up in objects.\n\n```\n{{person.firstName}}\n```\n\n### Changing context\n\nInside `{{#each}}` blocks you can change a context to parent with `../`.\n\n```\n{{#each people}}\n {{../prefix}} {{name}}\n{{/each}}\n```\n\n### HTML escaping\n\nValues returned by the `{{expression}}` are HTML-escaped. You can suppress escaping by using triple braces.\n\n```\n{{text}} – escaped\n{{{text}}} – unescaped\n```\n\nExpressions rendering child views should be unescaped.\n\n### Whitespaces\n\nTemplate whitespace can be omitted from either side of any mustache statement by adding a `~` character by the braces.\n\n```\n{{#each items ~}}\n \n{{~/each}}\n```\n\n### Sub-expressions\n\n```\n{{complexText (translate 'myMessage' category='messages' scope='MyScope')}\n```\n\n## Helpers\n\n### if\n\nAn if block conditional helper.\n\n```\n{{#if value}}\n\n{{/if}}\n```\n\n```\n{{#if value}}\n\n{{else}}\n\n{{/if}}\n```\n\n### unless\n\nAn inversion of the if block.\n\n### each\n\nAn iteration block helper.\n\n```\n{{#each array}}\n {{this}} – item\n {{@index}} – index\n{{/each}}\n```\n\n```\n{{#each object}}\n {{this}} – item\n {{@key}} – key\n{{/each}}\n```\n\n### lookup\n\nAccessing an object property by a key or an array item by an index.\n\n```\n{{lookup object 'property'}}\n```\n\n### ifEqual\n\nCompares two values for equality.\n\n```\n{{#ifEqual value1 value2}}\n\n{{/ifEqual}}\n```\n\n```\n{{#ifEqual value1 value2}}\n\n{{else}}\n\n{{/ifEqual}}\n```\n\n### ifNotEqual\n\nCompares two values for inequality.\n\n### get\n\nGets an attribute value from a model.\n\n```\n{{get model 'name'}}\n```\n\n### translate\n\nTranslates a label.\n\n```\n{{translate label}}\n{{translate field category='fields' scope='Account'}}\n```\n\n### translateOption\n\nTranslates an enum option.\n\n```\n{{translateOption 'optionKey' field='myField' scope='MyEntityType'}}\n```\n\n### complexText\n\nPrints a parsed Markdown text.\n\n```\n{{complexText text}}\n```\n\n### hyphen\n\nConverts a camelCase to hyphen.\n\n```\n{{hyphen stringValue}}\n```\n\n### toDom\n\nConvert a string from camelCase to hyphen and replace dots with hyphens. Useful for DOM attributes.\n\n```\ndata-{{toDom this}}=\"{{lookup ../this this}}\"\n```\n\n### breaklines\n\nReplaces line breaks with `` tags.\n\n```\n{{breaklines text}}\n```\n\n### basePath\n\nA client base path.\n" }, { "path": "docs/development/frontend/view-setup-handlers.md", "content": "# View Setup Handlers\n\n*As of v7.0*\n\nViewSetupHandlers framework provides the ability to customize existing views w/o extending. Multiple handlers can be attached to a view.\n\nIn clientDefs:\n\n```json\n{\n \"viewSetupHandlers\": {\n \"list\": [\n \"__APPEND__\",\n \"custom:some-handler-1\"\n ],\n \"record/search\": [\n \"__APPEND__\",\n \"custom:some-handler-2\"\n ]\n }\n}\n```\n\nCan be defined:\n\n* for a scope (clientDefs > {ScopeName})\n* globally (clientDefs > Global)\n\nHandlers are processed in the `setup` method of the view.\n\nThe following types are supported:\n\n* list – main list view;\n* detail – main detail view;\n* edit – main edit view;\n* record/list – list record view;\n* record/search – search view;\n* record/detail – detail record view;\n* record/edit – detail record view;\n* record/kanban – kanban record view;\n* login – the login view; only in Global scope; as of v8.3.0;\n\n!!! important\n\n The `__APPEND__` element is needed in the beginning of arrays to establish extending of existing items that can be defined by other modules.\n\nHandler example:\n\n```js\n\ndefine('custom:some-handler', [], () => {\n\n class Handler {\n \n /**\n * @param {import('view').default} view\n */\n constructor(view) {\n this.view = view;\n }\n\n process() {\n this.listenTo(this.view, 'after:render', () => {\n // Do something with view after render.\n });\n\n this.view.listenTo(this.view.model, 'change', () => {});\n }\n }\n\n // Establish event support. If needed.\n Object.assign(Handler.prototype, Backbone.Events);\n\n return Handler;\n});\n```\n\nThe `process` method can return Promise. In this case the view will wait until the promise is resolved before proceeding to rendering.\n" }, { "path": "docs/development/hooks.md", "content": "# Hooks\n\nThe Hooks framework provides the ability to catch some actions in the system in order to call custom logic.\n\nCommon hooks for all entity types (called from the ORM Repository class):\n\n- *beforeSave* – just before a record is saved;\n- *afterSave* – after a record is saved;\n- *beforeRemove* – before a record is removed;\n- *afterRemove* – after a record is removed;\n- *afterRelate* – when two records are related through a many-to-many relationship;\n- *afterUnrelate* – when two records are unrelated through a many-to-many relationship;\n- *afterMassRelate*\n- *lateAfterSave* – after a record is saved, after the transaction is committed (as of v10.0);\n- *lateAfterRemove* – after a record is removed, after the transaction is committed (as of v10.0);\n\n## Creating hook\n\n* create a file `custom/Espo/Custom/Hooks/{EntityType}/{HookName}.php` (you can also use a module directory);\n* declare a hook action method with a name the same as a hook name (e.g. *beforeSave*);\n* clear cache in Administration.\n\n!!! warning\n\n {HookName} must be unique per entity type. If there are two hooks with the same name\n for the same entity type (defined in different modules), only the first one will be applied (honoring the module order).\n\n## Hook order\n\nIf you have several hooks related to the same entity type, you can set the order property with an integer value.\n\n```\npublic static int $order = 10;\n```\n\nAscending order is applied – a hook with the smallest order number runs first.\n\nIf the *order* property is omitted, the value *9* is applied for the hook.\n\nOrder values of existing hooks:\n\n* Before-Save formula script: *11*\n* After-Save workflow actions: *99* (in Advanced Pack)\n\n### Interfaces\n\n*As of v7.4.*\n\nThere are interfaces for built-in hooks. It's recommended that your hooks implement these interfaces. This makes it easier for a developer to obtain needed data (passed to the hook) as each interface has a unique method signature. The list of interfaces:\n\n* `Espo\\Core\\Hook\\Hook\\BeforeSave`\n* `Espo\\Core\\Hook\\Hook\\AfterSave`\n* `Espo\\Core\\Hook\\Hook\\BeforeRemove`\n* `Espo\\Core\\Hook\\Hook\\AfterRemove`\n* `Espo\\Core\\Hook\\Hook\\AfterRelate`\n* `Espo\\Core\\Hook\\Hook\\AfterUnrelate`\n* `Espo\\Core\\Hook\\Hook\\AfterMassRelate`\n* `Espo\\Core\\Hook\\Hook\\LateAfterSave`\n* `Espo\\Core\\Hook\\Hook\\LateAfterRemove`\n\n## Example\n\nThis example sets an Account Name for new Leads, if it's not set.\n\n`custom/Espo/Custom/Hooks/Lead/MyHook.php`\n\n```php\n $options\n */\n public function beforeSave(Entity $entity, array $options): void\n {\n if ($entity->isNew() && !$entity->get('accountName')) { \n $entity->set('accountName', 'No Account');\n }\n }\n}\n```\n\n## Global hooks\n\nIf you need to apply a hook for all entities, you can use common hooks. To do this, put your hook class to `Common` directory, for example, `custom/Espo/Custom/Hooks/Common/{HookName}.php`.\n\n## Additional default hooks\n\n#### TargetList\n\n* *afterOptOut* – when a target (recipient) clicks an opt-out link, data are passed in the 3rd $data argument;\n* *afterCancelOptOut* – when a target subscribes again;\n* *afterOptIn* – when a target opts-in through Lead Capture, data are passed in the 3rd $data argument;\n\n#### Meeting / Call\n\n* *afterConfirmation* – when an event attendee clicks on accept/decline/tentative link; details are passed in the 3rd argument $data;\n\n#### Contact\n\n* *afterLeadCapture* – when a contact (existing in crm) opts-in through Lead Capture, leadCaptureId is passed in the 3rd argument $data;\n* *afterOptOut*\n* *afterCancelOptOut*\n\n#### Lead\n\n* *afterLeadCapture* – when a lead opts-in through Lead Capture, leadCaptureId is passed in the 3rd argument $data;\n* *afterOptOut*\n* *afterCancelOptOut*\n\n#### LeadCapture\n\n* *afterLeadCapture* – when a target (lead or contact) opts-in through Lead Capture, target data are passed in the 3rd argument $data;\n\n#### CampaignTrackingUrl\n\n* *afterClick* - when a target (lead/contact/account) opened a tracking url in email;\n\n#### Examples\n\n`custom/Espo/Custom/Hooks/TargetList/MyHook.php`\n\n```php\nhookManager->process($entityType, $hookType, $entity, $options);\n```\n\n!!! note\n\n A hook name can't start with `set`. It's reserved for a dependency injection.\n\n## Tips\n\nAvoid saving the same record in beforeSave hooks.\n\nIn afterSave hooks, re-saving the same record usually should be avoided as it can disrupt following hooks. If saving is needed, consider passing SKIP_ALL, KEEP_NEW and KEEP_DIRTY save options to the *saveEntity* method or run an update query instead (using the query builder).\n" }, { "path": "docs/development/how-to-create-a-dashlet.md", "content": "# Custom dashlets\n\nCreate a file `custom/Espo/Custom/Resources/metadata/dashlets/{DASHLET_NAME}.json` with your dashlet configuration.\n\nHere you need to define `\"view\"`, and you can set 'aclScope', and 'options'.\n\nIf it's typical list dashlet, use `\"view\":\"views/dashlets/abstract/record-list\"`, if not, create own [view](custom-views.md).\n\n## Options\n\nBy default in dashlet options you can set _Title_ and _Auto-refresh Interval_.\n\nAdditional option fields you can set in `\"options\"` > `\"fields\"`.\n\nAlso you can define other options, if your view needs more data. You will be able to access options data from a view with the method `getOption('optionName')`.\n\n## Example\n\nCreate a file `custom/Espo/Custom/Resources/metadata/dashlets/MyDashlet.json`:\n\n```json\n{\n \"view\": \"custom:views/dashlets/my-dashlet\",\n \"aclScope\": \"Account\",\n \"options\": {\n \"fields\": {\n \"title\": {\n \"type\": \"varchar\",\n \"required\": true\n },\n \"autorefreshInterval\": {\n \"type\": \"enumFloat\",\n \"options\": [0, 0.5, 1, 2, 5, 10]\n }\n },\n \"layout\": [\n {\n \"rows\": [\n [\n {\"name\": \"title\"},\n {\"name\": \"autorefreshInterval\"}\n ]\n ]\n }\n ]\n }\n}\n```\naclScope set to Account means that only users who have access to Account scope will be able to add this dashlet.\n\n\nThere you can find how default dashlets defined: `application/Espo/Modules/Crm/Resources/metadata/dashlets`.\n\nCreate a view file `client/custom/src/views/dashlets/my-dashlet.js`:\n\n```js\ndefine(['views/dashlets/abstract/base'], (BaseView) => {\n\n return class extends BaseView {\n name = 'MyDashlet'\n\n templateContent = `\n
My Dashlet
\n \n `\n }\n});\n```\n\n## Translation\n\nTranslation to dashlet is in `Global` scope, in `\"dashlets\"` section.\n\n__After that don't forget to Clear Cache in Administration.__\n" }, { "path": "docs/development/how-to-start.md", "content": "# How to get started\n\n*(for developers)*\n\nIn this article:\n\n* [Option A. Extension development](#option-a-extension-development)\n* [Option B. Using git repository](#option-b-using-git-repository)\n* [Configuration for development](#configuration-for-development)\n* [Where to put customizations](#where-to-put-customizations)\n\n## Option A. Extension development\n\nUse this approach to customize Espo for a specific business. \n\nBy utilizing the [ext-template](https://github.com/espocrm/ext-template) repository, you can craft an installable extension for EspoCRM. Your repository will contain only your custom files. The ext-template tools allow you to run your extension in an Espo instance for testing purposes. See more info in the repository's readme.\n\nIt is possible to [install](autoload.md) additional composer libraries in your extension.\n\n## Option B. Using git repository\n\nUsing the main EspoCRM repository. Contributors should use this approach.\n\n1. Clone [https://github.com/espocrm/espocrm](https://github.com/espocrm/espocrm) repository (or a forked one) to your local computer.\n2. Change to the project's root directory: `cd path/to/espocrm`.\n3. Install [Composer](https://getcomposer.org/doc/00-intro.md) if not installed (v2.0 or greater).\n4. Install npm if not installed (v8.0 or greater).\n5. Install [Grunt](https://gruntjs.com/installing-grunt).\n6. Run `composer install` if Composer is installed globally (or, `php composer.phar install`, if locally).\n7. Run `npm ci`.\n\nThen, you can build by running `grunt`.\n\nTo build a proper *config.php* file and populate database you can run installation. Open `http(s)://{YOUR_CRM_URL}/install` location in the browser. It's assumed that your webserver is properly [configured](../administration/server-configuration.md).\n\n!!! note\n\n Some dependencies require php extensions that you might not have installed. You can skip these requirements by installing with a flag *--ignore-platform-reqs*: `composer install --ignore-platform-reqs`.\n\nYou also need to enable [developer mode](#configuration-for-development).\n\nAfter building, you will be able to run the instance in your browser right from the project root directory, considering that your web server is properly configured.\n\n### Building\n\n1. Change to the project's root directory.\n2. Run Grunt with `grunt`.\n\nThe build will be created in the `build` directory.\n\n!!! note\n\n By default, grunt installs composer dependencies. You can skip it by running `grunt offline`.\n\n\n#### Javascript transpiling\n\nBuilding with *grunt* includes the transpiling step. You can also run it manually with the following commands.\n\nTranspile all:\n\n```\nnode js/transpile\n```\n\nTranspile a specific file (can be useful for a file watcher in an IDE):\n\n```\nnode js/transpile -f $FilePathRelativeToProjectRoot$\n```\n\n### Branches\n\n* *fix* – upcoming maintenance release; fixes should be pushed to this branch;\n* *master* – develop branch; new features should be pushed to this branch;\n* *stable* – last stable release.\n\n### Upgrade packages\n\nPreparation:\n\n1. Fetch tags to your git repository from the remote: `git fetch --tags`.\n2. Checkout to a needed version tag (or don't if you want to test upgrade to the most recent commit).\n3. Build EspoCRM with grunt (see above how to build).\n\nBuild the upgrade package with the command:\n\n```\nnode diff {version_from}\n```\n\nThe package will be created in the `build` directory.\n\n### Using custom builds for production\n\nOne may want to maintain a forked and customized repository to use it for production. Note that this is not an officially supported approach but it's still viable.\n\nPrinciples:\n\n1. Merge with upstream.\n2. Build upgrades by yourself.\n3. Production instance should be installed from a build (artifact). It should not be the same as the development repository.\n4. Do not apply upgrades against the development repository, upgrade the production instance.\n\n## Configuration for development\n\nEspoCRM instance configuration for development. Config parameters should be set in `data/config.php`.\n\nThe developer mode:\n\n```php\n'isDeveloperMode' => true,\n```\n\n!!! note\n\n The developer mode won't work on a release instance. It requires the *frontend* folder from the repository and *client/lib/transpiled* which should contain all JS files separately and transpiled.\n\nYou can force using some additional cache in the developer mode. Can be reasonable as the application can run very slow w/o cache.\n\n```php\n'useCacheInDeveloperMode' => true,\n```\n\n## Where to put customizations\n\n### Option A. Custom dirs\n\n* `custom/Espo/Custom/` – for metadata and all files pertaining to backend\n* `client/custom/` – for client files\n\n### Option B. Module dirs\n\n* `custom/Espo/Modules/{YourModuleName}/` – for metadata and all files pertaining to backend\n* `client/custom/modules/{your-module-name}/` – for client files\n\nThis method is the only appropriate method when developing an extension. The ext-template's initialization created needed folders automatically. The important advantage of using ext-template is the ability to use ESM modules in the frontend, which significantly improves the development experience.\n" }, { "path": "docs/development/index.md", "content": "# Developer Documentation\n\n### General\n\n* [Getting started](how-to-start.md)\n* [Making extension package](extension-packages.md)\n* [Modules](modules.md)\n* [Tests](tests.md)\n* [Translation](translation.md)\n* [Coding rules](coding-rules.md)\n\n### Backend\n\n* [Dependency injection](di.md)\n* [Metadata](metadata.md)\n* [ORM](orm.md)\n* [Select Builder](select-builder.md)\n* [API actions](api-action.md)\n* [Services](services.md)\n* [Hooks](hooks.md)\n* [ACL](acl.md)\n* [Entry points](entry-points.md)\n* Misc\n * [Coding practices'](coding-practices.md) \n * [Autoload](autoload.md)\n * [Entity type](custom-entity-type.md)\n * [Container services](container-services.md)\n * [Template helpers (PDF)](template-custom-helper.md)\n * [Formula functions](new-function-in-formula.md)\n * [Scheduled jobs](scheduled-job.md)\n * [Duplicate checking](duplicate-check.md)\n * [Database indexes](db-indexes.md)\n * [App params](app-params.md)\n * [Jobs](jobs.md)\n * [Email sending](email-sending.md)\n * [Calculated fields](calculated-fields.md)\n * [Config parameters](custom-config-parameters.md)\n * [Attachments](attachments.md)\n\n### Frontend\n\n* [View](view.md)\n* [Model](model.md)\n* [Collection](collection.md)\n* [Templates](frontend/templates.md)\n* [HTML & CSS](frontend/html-css.md)\n* [Ajax requests](frontend/ajax.md)\n* [Controller & routing](frontend/controller.md)\n* [Dependency injection](frontend/dependency-injection.md)\n* [Modal dialogs](modal.md)\n* [Confirmation dialogs](confirm-dialog.md)\n* [Custom views (for records and fields)](custom-views.md)\n* [View setup handlers](frontend/view-setup-handlers.md)\n* [Save error handlers](frontend/save-error-handlers.md)\n* [Dynamic forms with dynamic handler](dynamic-handler.md)\n* Fields\n * [Custom field type](custom-field-type.md)\n * [Customizing existing fields](customize-standard-fields.md)\n* Misc\n * [Buttons & dropdown actions for detail/edit/list views](custom-buttons.md)\n * [Custom panels on record view](frontend/record-panels.md)\n * [Including custom CSS file](custom-css.md)\n * [Custom dashlets](how-to-create-a-dashlet.md) \n * [Link-multiple field with primary record](link-multiple-with-primary.md)\n * [Monkey patching](frontend/monkey-patching.md)\n * Campaigns\n * [Custom unsubscribe page](campaign-unsubscribe-template.md)\n\n\n### API\n\n* [API Overview](api.md)\n" }, { "path": "docs/development/jobs.md", "content": "# Jobs\n\nSometimes it's reasonable to execute some actions in background. For example, when sending an email, to prevent a user to wait until sending is processed. \n\n### Scheduling\n\n```php\ncreate()\n ->setClassName($jobClassName) // should implement `Espo\\Core\\Job\\Job` interface\n ->setQueue(QueueName::Q0) // optional\n ->setGroup('some-group-name') // optional\n ->setData([\n 'someKey' => $someValue,\n ])\n ->schedule();\n```\n\nYou can pass JobSchedulerFactory as a constructor dependency.\n\n### Job\n\n```php\nNeed to create a `contacts` linkMultiple field with a primary for our custom entity *Stock*. \n>\n\n### Step 1\n\nCreate (or edit) `custom/Espo/Custom/Resources/metadata/entityDefs/Stock.json`:\n\n```json\n{\n \"fields\": {\n \"contacts\": {\n \"type\": \"linkMultiple\",\n \"view\": \"custom:views/stock/fields/contacts\"\n },\n \"contact\": {\n \"type\": \"link\"\n }\n },\n \"links\":{\n \"contact\": {\n \"type\": \"belongsTo\",\n \"entity\": \"Contact\",\n \"foreign\": \"stocksPrimary\"\n },\n \"contacts\": {\n \"type\": \"hasMany\",\n \"entity\": \"Contact\",\n \"foreign\": \"stocks\",\n \"layoutRelationshipsDisabled\": true\n }\n }\n}\n```\n\n### Step 2\n\n`custom/Espo/Custom/Resources/metadata/entityDefs/Contact.json`\n\n```json\n{\n \"links\":{\n \"stocksPrimary\": {\n \"type\": \"hasMany\",\n \"entity\": \"Stock\",\n \"foreign\": \"contact\",\n \"layoutRelationshipsDisabled\": true\n },\n \"stocks\": {\n \"type\": \"hasMany\",\n \"entity\": \"Stock\",\n \"foreign\": \"contacts\"\n }\n }\n}\n```\n\n### Step 3\n`custom/Espo/Custom/Hooks/Stock/AfterSave.php`\n\n```php\nisAttributeChanged('contactId')) {\n return;\n }\n \n $contactId = $entity->get('contactId');\n $fetchedContactId = $entity->getFetched('contactId');\n \n $relation = $this->entityManager\n ->getRDBRepository($entity->getEntityType())\n ->getRelation($entity, 'contacts');\n\n if (!$contactId) {\n $relation->unrelateById($fetchedContactId);\n \n return;\n }\n \n $relation->relateById($contactId); \n }\n}\n```\n\n### Step 4\n`client/custom/src/views/stock/fields/contacts.js`\n\n```js\ndefine(['views/fields/link-multiple-with-primary'], (Dep) => { \n return class extends Dep {\n primaryLink = 'contact'\n }\n});\n```\n\n### Step 5\n\nRun Rebuild.\n\n### Step 6\n\nExecute an SQL query:\n\n```sql\nUPDATE stock\nJOIN contact_stock\nON contact_stock.stock_id = stock.id AND contact_stock.deleted = 0\nSET stock.contact_id = contact_stock.contact_id\n```\n" }, { "path": "docs/development/metadata/acl-defs.md", "content": "# aclDefs\n\nPath: metadata > aclDefs > {ScopeName}.\n\nDefines access control parameters for a specific scope (or entity type).\n\n## accessCheckerClassName\n\nAn access checking class. Should implement `Espo\\Core\\Acl\\AccessChecker` interface.\n\nCan optionally implement more interfaces that define what actions can be checked.\n\nInterfaces for access checking:\n\n* `Espo\\Core\\Acl\\AccessChecker` – access to a scope;\n* `Espo\\Core\\Acl\\AccessCreateChecker` – access to a create operation for a scope;\n* `Espo\\Core\\Acl\\AccessReadChecker` – access to a read operation for a scope;\n* `Espo\\Core\\Acl\\AccessEditChecker` – access to an edit operation for a scope;\n* `Espo\\Core\\Acl\\AccessDeleteChecker` – access to a delete operation for a scope;\n* `Espo\\Core\\Acl\\AccessStreamChecker` – access to the stream for a scope;\n* `Espo\\Core\\Acl\\AccessEntityCreateChecker` – access to a create operation for an entity;\n* `Espo\\Core\\Acl\\AccessEntityReadChecker` – access to a read operation for an entity;\n* `Espo\\Core\\Acl\\AccessEntityEditChecker` – access to an edit operation for an entity;\n* `Espo\\Core\\Acl\\AccessEntityDeleteChecker` – access to a delete operation for an entity;\n* `Espo\\Core\\Acl\\AccessEntityStreamChecker` – access to the stream of an entity.\n\nCombined interfaces:\n\n* `Espo\\Core\\Acl\\AccessEntityCREDChecker` – access to create/read/edit/delete of an entity (combined);\n* `Espo\\Core\\Acl\\AccessEntityCREDSChecker` – access to create/read/edit/delete/stream of an entity (combined).\n\n\nDefault class: `Espo\\Core\\Acl\\DefaultAccessChecker`.\n\n\n## ownershipCheckerClassName\n\nAn ownership checking class.\n\nShould implement one of the following interfaces:\n\n* `Espo\\Core\\Acl\\OwnershipOwnChecker` – whether a user is an owner of an entity;\n* `Espo\\Core\\Acl\\OwnershipTeamChecker` – whether an entity belongs to a user team.\n\nDefault class: `Espo\\Core\\Acl\\DefaultOwnershipChecker`.\n\n## portalAccessCheckerClassName\n\nThe same as `accessCheckerClassName` but for the portal.\n\n## portalOwnershipCheckerClassName\n\nThe same as `ownershipCheckerClassName` but for the portal.\n\nCan implement additional interfaces:\n\n* `Espo\\Core\\Portal\\Acl\\OwnershipAccountChecker`\n* `Espo\\Core\\Portal\\Acl\\OwnershipContactChecker`\n\n## assignmentCheckerClassName\n\nAn assignment checking class.\n\nShould implement `Espo\\Core\\Acl\\AssignmentChecker` interface.\n\nDefault class: `Espo\\Core\\Acl\\DefaultAssignmentChecker`.\n\n## readOwnerUserField\n\nIndicates what field is used for ownership checking. If an entity uses a field other than *assignedUser* or *assignedUsers*, you need to specify that field.\n\n## linkCheckerClassNameMap \n\n*Object.{{{record}}}
\n `,\n\n // If true, clicking on the backdrop will close the dialog.\n // Can be 'static', true or false.\n backdrop = true \n\n setup() {\n // action buttons\n this.buttonList = [\n {\n name: 'doSomething', // handler for 'doSomething' action is bellow\n text: this.translate('Some Action', 'labels', 'MyScope'), // button label \n style: 'danger',\n onClick: () => this.actionDoSomething(),\n },\n {\n name: 'cancel',\n label: 'Cancel',\n },\n ];\n \n const title = this.options.title || ''; // assuming it's passed from our parent view\n\n this.headerText = title; \n // this.headerHtml = this.getHelper().escapeString(title);\n\n this.formModel = new Model();\n\n // define fields\n this.formModel.setDefs({\n fields: {\n 'someString': {\n type: 'varchar', // field type\n view: 'views/fields/varchar', // optional, to define custom view\n required: true, // field param\n },\n 'someCheckbox': {\n type: 'bool',\n },\n }\n });\n\n this.createView('record', 'views/record/edit-for-modal', {\n model: this.formModel,\n selector: '.record', \n detailLayout: [ // form layout\n {\n rows: [\n [\n {\n name: 'someString',\n labelText: this.translate('someString', 'fields', 'MyScope'),\n },\n {\n name: 'someCheckbox',\n labelText: this.translate('Some Checkbox', 'labels', 'MyScope'),\n },\n ],\n ],\n },\n ],\n });\n }\n\n async actionDoSomething() {\n /** @type {import('views/record/edit').default} */\n const recordView = this.getView('record');\n\n const isValid = recordView.processFetch();\n\n if (!isValid) { \n return;\n }\n\n Espo.Ui.notify(' ... ');\n \n const response = await Espo.Ajax.postRequest('MyScope/action/doSomething', {\n id: this.options.id, // passed from the parent view\n someString: this.formModel.attributes.someString,\n someCheckbox: this.formModel.attributes.someCheckbox,\n });\n\n Espo.Ui.success(this.translate('Done'));\n\n // We assume that the event 'done' will be caught by the parent view.\n this.trigger('done', response);\n\n // Close the modal dialog.\n this.close();\n }\n }\n});\n```\n\nParent view calling our modal view:\n\n```js\nthis.createView('dialog', 'custom:views/modals/my-dialog', {\n id: this.model.id,\n title: this.model.get('name'), \n}, view => {\n view.render();\n\n this.listenToOnce(view, 'done', response => {\n console.log(response);\n })\n});\n```\n\n## Simple dialog w/o separate view\n\n```js\nthis.createView('dialog', 'views/modal', {\n templateContent: '{{complexText viewObject.options.message}}
',\n headerText: 'Hello world',\n backdrop: true,\n message: 'Some *message*\\n\\nHello world!',\n buttonList: [\n {\n name: 'doSomething',\n label: this.translate('Do Something'),\n onClick: () => {\n // Do something.\n this.close();\n },\n style: 'primary',\n },\n {\n name: 'close',\n label: this.translate('Close'),\n }\n ],\n}, view => {\n view.render();\n});\n```\n" }, { "path": "docs/development/model.md", "content": "# Model\n\nA model instance usually represents a single entity record. See the [class](https://github.com/espocrm/espocrm/blob/stable/client/src/model.js).\n\n## Methods\n\n### set\n\nSets an attribute or multiple attributes.\n\n```js\n// Set one attribute.\nmodel.set('attributeName', value);\n\n// Multiple at once.\nmodel.setMultiple({\n attributeName1: value1,\n attributeName2: value2,\n});\n\n// With options.\nmodel.setMultiple(attributes, {\n // suppresses 'change' events\n silent: true, \n});\n```\n\nYou can pass custom options and check them in 'change' event listeners.\n\n### get\n\nGets an attribute.\n\n```js\nconst value = model.get('attributeName');\n// or model.attributes.attributeName;\n\n// all attributes\nconst attributes = Espo.Utils.cloneDeep(model.attributes);\n```\n\n### save\n\nSaves the model (to the back-end).\n\n```js\n// Assuming model.id is set.\ntry {\n await model.save()\n} catch() {\n // Error occurred.\n return;\n}\n```\n\n### fetch\n\nFetches the model (from the backend). Loads attribute values to the model. Returns a promise.\n\n```js\n// Assuming model.id is set.\nasync model.fetch();\n```\n\n### getClonedAttributes\n\nGet cloned attributes. Returns an object.\n\n```js\nconst attributes = model.getClonedAttributes();\n```\n\n### populateDefaults\n\nPopulate default values.\n\n```js\nmodel.populateDefaults();\n```\n\n### setDefs\n\nSets field and link defs. May be needed if a model instantiated explicitly, not by the factory.\n\n```js\nmodel.setDefs({\n fields: {},\n links: {},\n});\n```\n\n## Properties\n\n### id\n\n*string*\n\nA record ID.\n\n### entityType\n\n*string*\n\nAn entity type.\n\n### urlRoot\n\n*string*\n\nA root API URL to use for syncing with the backend. For non-new records, an ID part will be appended.\n\n### url\n\n*string*\n\nAn API URL to use for syncing with the backend. If specified, urlRoot will be omitted.\n\n### attributes\n\n*Record*\n\nAttribute values.\n\n```js\nconst name = model.attributes.name;\n```\n\n## Instantiating\n\nModel-factory is available in views. The model-factory allows you to create a model instance of a specific entity type.\n\n```js\nexport default class extends View {\n\n setup() { \n // Use wait to hold off rendering until model is loaded. \n this.wait(this.loadModel());\n }\n\n async loadModel() {\n this.model = await this.getModelFactory().create('Account');\n\n // entityType is set by the factory.\n //const entityType = this.model.entityType;\n\n this.model.id = this.options.id;\n\n await model.fetch(); \n }\n}\n```\n\nInstantiating w/o factory:\n\n```js\nimport View from 'view';\nimport Model from 'model';\n\nexport default class extends View {\n\n setup() {\n const model = new Model();\n\n // URL will be used when fetching and saving.\n model.urlRoot = 'MyModel'; \n model.id = 'someId';\n \n this.wait(\n // This performs `GET MyModel/someId` API call.\n model.fetch(); \n );\n }\n}\n```\n\n## Events\n\nNote: `listenTo` and `listenToOnce` are methods of the *view* class.\n\n### change\n\nWhen model attributes get changed (not necessarily synced with backend).\n\n```js\nthis.listenTo(model, 'change', (model, options) => {\n if (this.model.hasChanged('someAttribute')) {\n // someAttribute is changed\n }\n \n if (options.ui) {\n // changed via UI\n // this options is set by field view\n }\n\n // The 'action' option indicates how the change originated.\n // Possible values: fetch, save, ui, cancel-edit.\n console.log(options.action);\n\n // If you want to change the same model within this handler,\n // use setTimeout with a zero delay to avoid a potential loop.\n});\n\nthis.listenToOnce(model, 'change:someAttribute', (model, value, options) => {\n // someAttribute is changed\n});\n```\n\n### sync\n\nModel synced with backend.\n\n```js\nthis.listenTo(model, 'sync', (model, response, options) => {\n // Synced with backend – fired after fetch or save.\n\n // The 'action' option indicates how the sync originated.\n // Possible values: fetch, save, destroy.\n console.log(options.action);\n});\n```\n\n### destroy\n\nOnce model is removed (after *DELETE* request).\n\n## Additional events\n\nDefined in the application.\n\n### after:relate\n\nOnce relationship panel updated. Available on the detail view.\n\n### after:relate:{link}\n\nOnce a specific relationship panel updated. Available on the detail view.\n\n### update-all\n\nThis event is not fired. But you can fire it to refresh all relationship panels. Available on the detail view.\n\n### update-related:{link}\n\nFire this event to refresh a specific relationship panel. Available on the detail view.\n\n\n## Other\n\nPassing model to a child view:\n\n```js\nthis.createView('someName', 'custom:views/some-view', {\n model: this.model,\n});\n```\n\nOr:\n\n```js\nconst view = new MyView({model});\n```\n" }, { "path": "docs/development/modules.md", "content": "# Modules\n\nThe best practice is to place customizations in a module directory:\n\n* `custom/Espo/Modules/{YourModule}/` – backend (CamelCase name);\n* `client/custom/modules/{your-module}/` – frontend (hyphen name).\n\n## Order\n\nEvery module has its *order* property. The order is used by the system to define which module to load first. For example, if two modules have some metadata with the same key, the metadata of the module that has a higher order will be used. If two modules have the controller classes with the same name, then the class of the module that has a higher order will be used.\n\nThe *order* property is defined in `custom/Espo/Modules/{YourModule}/Resources/module.json`:\n\n```json\n{\n \"order\": 16\n}\n```\n\nRequires clearing cache after changes.\n\n## Routes\n\nA module can define additional [API routes](api-action.md#routing). They are defined in `custom/Espo/Modules/{YourModule}/Resources/routes.json`.\n\nRequires clearing cache after changes.\n\n## Composer\n\nYou can create a `composer.json` in your module directory to include 3rd party libraries. To let Espo know about these libraries, you need to create an [autoload configuration file](autoload.md) in your module.\n\n## JS modules\n\nWhen referencing ES (or AMD) modules located in an Espo module, use the path: `module/{your-module}/*`. Example: `module/my-module/views/fields/my-field`.\n\nWhen using [ext-template](https://github.com/espocrm/ext-template), the path to your Espo module will be automatically written in *jsconfig.json*. That will allow an IDE to properly locate module files. \n" }, { "path": "docs/development/new-function-in-formula.md", "content": "# Custom functions for Formula\n\nEspoCRM provides the ability to create custom functions that can be used in formula-script. \n\nCreate a file `custom/Espo/Custom/FormulaFunctions/MyContains.php` with the code:\n\n```php\n 2) {\n $offset = $arguments[2];\n \n return strpos($haystack, $needle, $offset) !== false;\n }\n \n return strpos($haystack, $needle) !== false;\n }\n}\n```\n\nCreate a file `custom/Espo/Custom/Resources/metadata/app/formula.json` and add the code:\n\n```json\n{\n \"functionClassNameMap\": {\n \"myNamespace\\\\myContains\": \"Espo\\\\Custom\\\\FormulaFunctions\\\\MyContains\"\n },\n \"functionList\": [\n \"__APPEND__\",\n {\n \"name\": \"myNamespace\\\\myContains\",\n \"insertText\": \"myNamespace\\\\myContains(HAYSTACK, NEEDLE, OFFSET)\"\n }\n ]\n}\n```\n\nClear cache.\n\n" }, { "path": "docs/development/orm-value-objects.md", "content": "# Value Objects\n\n*As of v7.0.*\n\n* Value objects are immutable.\n* Value objects contain modification methods that return a cloned instance.\n* Default value objects are available in the namespace `Espo\\Core\\Field`.\n* It's possible to register custom value object for a specific field type or for a specific field.\n\nWhen defining getters and setters in an Entity class, it's recommended to use value objects for such field types:\n\n* date\n* datetime\n* datetimeOptional\n* address\n* currency\n\nAll field types with registered value object:\n\n* date\n* datetime\n* datetimeOptional\n* address\n* currency\n* email\n* phone\n* link\n* linkParent\n* linkMultiple\n\nBaseEntity's methods *getValueObject* and *setValueObject* will work for field types with registered value object.\n\n```php\ngetValueObject($field);\n$entity->setValueObject($field, $valueObject);\n$entity->setValueObject($field, null);\n```\n\nGetter and setter:\n\n```php\nget('dateDue');\n\n if ($rawValue === null) {\n return null;\n }\n\n return Date::fromString($rawValue);\n }\n\n public function setDateDue(?Date $dateDue): self\n {\n $this->setValueObject('dateDue', $dateDue);\n\n return $this;\n }\n}\n\n```\n\n## Supported field types\n\n### Address\n\n```php\ngetBillingAddress() ?? new Address();\n\n$country = $address->getCountry();\n$city = $address->getCity();\n```\n\n```php\nwithCity($city)\n ->withCountry($country)\n ->withPostalCode($postalCode);\n\n$accountEntity->setBillingAddress($address);\n```\n\n### Currency\n\n```php\nconvert($value, 'EUR');\n\n$opportunityEntity->setAmount($valueInEur);\n```\n\n### Email address, Phone number\n\n```php\ngetEmailAddressGroup();\n\n$primary = $emailAddressGroup->getPrimary();\n\n$modifiedEmailAddressGroup = $emailAddressGroup\n ->withAddedEmailAddress(\n EmailAddress::create('address@test.com')->optedOut()\n );\n\n$accountEntity->setEmailAddressGroup($modifiedEmailAddressGroup);\n```\n\nThe same is available for phone numbers.\n\n### Date, DateTime, DateTimeOptional\n\n```php\ngetCloseDate();\n\n$opportunityEntity->setCloseDate(\n $closeDate->modify('+1 month')\n);\n```\n\n### Link, Link-Parent, Link-Multiple\n\n```php\ngetId())\n ->withColumnValue('role', 'Decision Maker');\n\n$contacts = LinkMultiple::create([$contact->getId()]);\n```\n\n## Registering\n\n!!! note\n\n Registering own value object types might be excessive as it's possible to manually handle value object creation and consumption in getter and setters of an entity.\n\nRegistering a custom value object type for a specific field type.\n\nFor a field type you need to define 2 parameters in metadata > fields > {fieldType}:\n\n* `valueFactoryClassName` – implementation of `Espo\\ORM\\Value\\ValueFactory` interface;\n* `attributeExtractorClassName` – implementation of `Espo\\ORM\\Value\\AttributeExtractor` interface.\n\nIt's also possible to register a value object for a specific field in metadata > entityDefs > {entityType} > fields > {fieldName}:\n\n* `valueFactoryClassName`;\n* `attributeExtractorClassName`.\n" }, { "path": "docs/development/orm.md", "content": "# ORM\n\nEspoCRM utilizes own built-in ORM (object-relational mapping). Create, update, read, delete and search operations are performed via the Entity Manager instance.\n\nThe *EntityManager* is available as a [*container service*](di.md). It's a central access point for ORM functionalities.\n\nA *Repository* class serves for fetching and storing records. Base classes: `Espo\\ORM\\Repositories\\RDBRepository`, `Espo\\Core\\Repositories\\Database`. *RDB* stands for a *relational database*.\n\nAn *Entity* class represents a single record. Each [entity type](../administration/terms-and-naming.md#entity-type) has its own entity class. Base class: `Espo\\Core\\ORM\\Entity`, interface: `Espo\\ORM\\Entity`.\n\nAn *EntityCollection* is a collection of entities. It's returned by *find* operations. An *SthCollection* is a collection of entities, consuming much less memory than EntityCollection. Collections are iterable.\n\nThe ORM uses a data-mapper approach. Note that it does not have an identity map – fetching the same record multiple times in a row will return different instances (of the same record).\n\n## See also\n\n* [Complex expressions](../user-guide/complex-expressions.md)\n* [Value objects](orm-value-objects.md)\n* [Custom entity type](custom-entity-type.md)\n* [Entity definitions](metadata/entity-defs.md)\n\n## Injecting Entity Manager\n\nThe Entity Manager is available as a [*Container*](di.md) service.\n\nA class with the `entityManager` dependency:\n\n```php\ngetNewEntity($entityType);\n```\n\nOr type hinted:\n\n```php\ngetRDBRepositoryByClass(MyEntity::class)->getNew();\n```\n\n!!! note\n\n It creates a new instance but doesn't store it in DB. The entity doesn't have an ID yet.\n\n### Fetch existing entity\n\n```php\ngetEntityById($entityType, $id);\n```\n\nOr type hinted:\n\n```php\ngetRDBRepositoryByClass(MyEntity::class)->getById($id);\n```\n\n### Store entity\n\n```php\nsaveEntity($entity);\n```\n\n#### Save options\n\nSave with options:\n\n```php\nsaveEntity($entity, [SaveOption::SILENT => true]);\n```\n\nAvailable options:\n\n* skipAll – skip all additional processing;\n* skipHooks – skip all hooks; workflows, formula will be ignored;\n* silent – workflows will be ignored, modifiedAt and modifiedBy fields won't be changed;\n* skipCreatedBy – createdBy won't be set to the current user;\n* skipModifiedBy – modifiedBy won't be set to the current user;\n* createdById – override createdBy with a passed user ID;\n* modifiedById – override modifiedBy.\n\nOptions in constants available here: `Espo\\Core\\ORM\\Repository\\Option\\SaveOption`.\n\n### Create and store entity\n\nStores the record in DB and returns an entity instance.\n\n```php\ncreateEntity($entityType, [\n 'name' => 'Test',\n 'status' => 'Hello',\n]);\n```\n\n### Remove entity\n\nSoft-deletes the record.\n\n```php\nremoveEntity($entity);\n```\n\n### Get attribute value\n\nReturn the value of a given attribute. An attribute usually corresponds to a column in DB.\n\n```php\nget('attributeName');\n```\n\n!!! note\n\n As EspoCRM supports custom fields and relationships which are added dynamically without the need to compile, attribute accessor methods *get*, *set* and *has* were introduced. For type safety, consider creating getters and setters for needed attributes in your custom Entity class. Use these methods in your business logic code.\n\n### Has attribute value\n\nChecks whether an attribute is set. Note: If it's set to *null*, it will return *true*. An attribute may not be set if the entity was fetched with only a specified attribute list.\n\n```php\nhas('attributeName'); // true or false\n```\n\n### Set attribute value\n\nOne:\n\n```php\nset('attributeName', 'Test Value');\n```\n\nMultiple:\n\n```php\nsetMultiple([\n 'name' => 'Test Name',\n 'assignedUserId' => '1',\n]);\n```\n\n### Clear attribute value\n\nThis will unset the attribute. If you save the Entity after that, it will not change the value to NULL in database. Very rarely used. Not recommended.\n\n```php\nclear('attributeName');\n```\n\n### Fetched attributes\n\nCheck whether an attribute was changed.\n\n```php\ngetFetched('attributeName');\n\n// check whether an attribute was changed since the last syncing with DB\n$attributeChanged = $entity->isAttributeChanged('attributeName');\n```\n\n### Get all attribute values\n\nReturns all attributes with their values.\n\n```php\ngetValueMap();\n```\n\n### Delete from DB\n\nDeletes the record permanently.\n\n```php\ngetRDBRepository($entityType)->deleteFromDb($id);\n```\n\n## Repository\n\nUse ORM's repositories to fetch and save entities. A repository instance is instantiated per entity type.\n\n!!! note\n\n It may be reasonable to wrap all interactions with the repository in a higher-level class (usually also called a Repository), so that your business-logic classes do not depend directly on the Entity Manager. This improves testability.\n\nGet a repository by an entity class:\n\n```php\n`.\n$accountRepository = $entityManager->getRDBRepositoryByClass(Account::class);\n```\n\n```php\ngetRDBRepositoryByClass(Account::class)\n ->getById($id);\n```\n\nNote: To be able to fetch the repository by an entity type, your [custom entity](custom-entity-type.md#entity-class) needs to have the *ENTITY_TYPE* constant.\n\nGet a repository by an entity type:\n\n```php\ngetRDBRepository($entityType);\n```\n\n### Find\n\n```php\ngetRDBRepository($entityType)\n ->where([\n 'type' => 'Customer',\n ])\n ->find();\n```\n\nDescending order:\n\n```php\ngetRDBRepository($entityType)\n ->limit(0, 10)\n ->order('createdAt', 'DESC')\n ->find();\n```\n\nComplex order:\n\n```php\ngetRDBRepository($entityType)\n ->order([\n ['createdAt', 'ASC'],\n ['name', 'DESC'],\n ])\n ->find();\n```\n\nOr:\n\n```php\ngetRDBRepository($entityType)\n ->order('createdAt', 'ASC')\n ->order('name', 'DESC')\n ->find();\n```\n\nOr:\n\n```php\ngetRDBRepository($entityType)\n ->order(\n Expr::concat(\n Expr::column('firstName'),\n Expr::column('lastName')\n ),\n 'DESC', \n )\n ->find();\n```\n\nOrdering by a value list:\n\n```php\ngetRDBRepository('Opportunity')\n ->order('LIST:stage:Prospecting,Qualification,Proposal')\n ->find();\n```\n\nFeeding a query to a repository:\n\n```php\ngetRDBRepository($entityType)\n ->clone($query)\n ->limit(0, 10)\n ->find();\n```\n\nFinding the first one:\n\n```php\ngetRDBRepository($entityType)\n ->where([\n 'type' => 'Customer',\n ])\n ->findOne();\n```\n\nYou can use *getRDBRepositoryByClass* for type safety:\n\n```php\ngetRDBRepositoryByClass(Account::class)\n ->findOne();\n\n// Static analysis infers the entity's type.\n```\n\n### Get new\n\nPrepare a new entity without saving it:\n\n```php\ngetRDBRepositoryByClass(Account::class)\n ->getNew();\n```\n\n### Save\n\nSave an entity:\n\n```php\ngetRDBRepositoryByClass(Account::class)\n ->save($account);\n```\n\n### Remove\n\nRemove an entity (soft delete):\n\n```php\ngetRDBRepositoryByClass(Account::class)\n ->remove($account);\n```\n\n## Relations\n\n!!! note\n\n As of v8.4, the *getRelation* method is available in the *EntityManager*. `$entityManager->getRelation($entity, 'relationName');` Before, it could be accessed from a repository.\n\n### Find related\n\nHas-Many:\n\n```php\ngetRelation($account, 'opportunities')\n ->find();\n\n// Filter.\n$opportunityCollection = $entityManager\n ->getRelation($account, 'opportunities')\n ->limit(0, 10)\n ->where($whereClause)\n ->find();\n\n// First one.\n$opportunity = $entityManager\n ->getRelation($account, 'opportunities')\n ->order('createdAt', 'DESC')\n ->findOne();\n```\n\nBelongs-To or Has-One:\n\n```php\ngetRelation($task, 'account')\n ->findOne();\n```\n\nFiltering by a relation column:\n\n```php\ngetRelation($targetList, 'leads')\n ->where(['@relation.optedOut' => false])\n ->find();\n```\n\n*optedOut* is a column in the middle table.\n\n### Relate entities\n\n```php\ngetRelation($account, 'opportunities')\n ->relate($opportunity);\n\n$entityManager\n ->getRelation($account, 'opportunities')\n ->relateById($opportunityId);\n\n// With relationship column setting.\n$entityManager\n ->getRelation($account, 'contacts')\n ->relate($contact, ['role' => 'CEO']);\n```\n\n### Unrelate entities\n\n```php\ngetRelation($account, 'opportunities')\n ->unrelate($opportunity);\n\n$entityManager\n ->getRelation($account, 'opportunities')\n ->unrelateById($opportunityId);\n```\n\n### Update columns\n\n```php\ngetRelation($account, 'contacts')\n ->updateColumns($contact, ['role' => 'CEO']);\n\n$entityManager\n ->getRelation($account, 'contacts')\n ->updateColumnsById($contactId, [\n 'role' => 'CEO', // relationship column\n ]);\n```\n\n### Check whether related\n\n```php\ngetRelation($account, 'opportunities')\n ->isRelated($opportunity);\n```\n\n### Managing from within Entity class\n\n*As of v9.0.*\n\nA developer can add getter and setters to an Entity class which will allow to read and set related records.\n\nIn a custom entity type class, you can define getter and setters for relationships. If you call the same getter multiple times, it will return the same instance. It's useful when the same related entity is accessed in multiple hooks during save. After save, the map will be reset – the getter won't return the same instance as before save.\n\nGet one:\n\n```php\nrelations->getOne('account');\n}\n```\n\nSet one:\n\n```php\nsetRelatedLinkOrEntity('account', $account);\n}\n```\n\nGet many:\n\n```php\n\n */\npublic function getAccounts(): Traversable\n{\n /** @var Traversable{{{someKeyName}}}
\n {{viewObject.someParam1}}
\n{{someParam2}}
\n \n \n `\n\n // Alternatively, a template can be defined in a separate file.\n // The `custom` prefix indicates that the base path is `client/custom/res/templates`. \n //template = 'custom:test/my-custom-view'\n\n // Initializing. Called on view creation, the view is not yet rendered.\n setup() {\n // Calling the parent `setup` method, can be omitted.\n super.setup();\n \n // Instantiate some property.\n this.someParam1 = 'test 1';\n\n this.addHandler('focus', '.record input[data-name=\"hello\"]', (event, target) => {\n // Do something.\n });\n\n // When we create a child view in the setup method, rendering of the view is held off\n // until the child view is loaded (ready), the child view will be rendered along with the parent view.\n // The first argument is a key name that can be used to access the view further.\n // The second argument is a view name.\n // The method returns a promise that resolves to a view object.\n this.createView('someKeyName', 'custom:test/my-custom-child-view', {\n // A relative selector of the DOM container.\n selector: '.some-test-container',\n // Or a full selector.\n //fullSelector: '#some-id',\n // Pass some parameter.\n someParam: 'test',\n }); \n \n // Options passed from the parent view.\n console.log(this.options); \n \n // A model can be passed from the parent view.\n console.log(this.model);\n \n // All event listeners are recommended to be initialized in the `setup` method.\n\n // Use listenTo & listenToOnce methods for listening to events of another object\n // to prevent memory leakage.\n\n // Subscribe to model change.\n // Subscribing with the `listenTo` method guarantees automatic unsubscribing on view removal,\n // so there won't be a memory leak.\n this.listenTo(this.model, 'change', () => {\n // Whether a specific attribute changed.\n if (this.model.hasChanged('someAttribute')) {\n const value = this.model.get('someAttribute');\n }\n });\n \n // Subscribe to model sync (saved or fetched). Fired only once.\n this.listenToOnce(this.model, 'sync', () => {});\n \n // Subscribe to a DOM event. `cid` contains an ID unique among all views.\n // Requires explicit unsubscribing on view removal.\n $(window).on('some-event.' + this.cid, () => {});\n\n // Translating a label.\n const translatedLabel = this.translate('myLabel', 'someCategory', 'MyScope');\n }\n\n // Called after contents is added to the DOM.\n afterRender() { \n // The view container (DOM element).\n console.log(this.element); \n \n // Accessing a child view.\n const childView = this.getView('someKeyName');\n \n // Checking whether a view is set.\n const hasSomeView = this.hasView('someKeyName');\n \n // Destroying a child view, also removes it from DOM.\n this.clearView('someKeyName');\n \n // Initializing a reference to some DOM element.\n this.$someElement = this.$el.find('.some-element');\n }\n \n // Data to be passed to the template.\n data() {\n return {\n someParam2: 'test 2',\n };\n }\n \n // Called when the view is removed.\n // Useful for destroying event listeners initialized for the view.\n onRemove() {\n $(window).off('some-event.' + this.cid);\n }\n \n // A custom method.\n someMethod1(value) {\n // Create and render a child view.\n this.createView('testKey', 'custom:test/my-another-custom-child-view', {\n selector: '.another-test-container', \n value: value,\n })\n .then(view => view.render());\n }\n \n someMethod2() {\n // To proceed only when the view is rendered.\n // Useful when the method can be invoked by a caller before the view is rendered.\n this.whenRendered().then(() => {\n // Do something with DOM.\n });\n }\n }\n}\n```\n\nSee more about [templates](frontend/templates.md).\n\nSee [the source file](https://github.com/yurikuzn/bull/blob/master/src/bull.view.js) of the view class.\n\n## Waiting for some data loaded before rendering\n\nSometimes we need to get some data loaded asynchronously before the view is rendered. For this purpose we can use the `wait` method inside the `setup` method. \n\nThe `wait` method can receive a promise:\n\n```js\nsetup() {\n this.wait(\n Promise.all([\n this.model.fetch(),\n this.model.collection.fetch(),\n ])\n );\n}\n```\n\nThe model factory returns a promise, so we can pass it to the `view` method:\n\n```js\nsetup() {\n this.wait(\n this.getModelFactory().create('Case')\n .then(model => {\n model.id = this.model.id;\n\n return model.fetch();\n })\n .then(data => {\n console.log(data);\n })\n );\n}\n```\n\nWait until a model is fetched. The `fetch` method returns a promise.\n\n```js\nsetup() {\n this.wait(\n this.model.fetch()\n );\n}\n```\n\nWait for multiple independent promises:\n\n```js\nsetup() {\n this.wait(\n this.model.fetch()\n );\n \n this.wait(\n Espo.Ajax.getRequest('SomeUrl')\n );\n}\n```\n\n```js\nsetup() {\n this.wait(\n Promise.all([\n this.model.fetch(),\n Espo.Ajax.getRequest('SomeUrl'),\n ])\n );\n}\n```\n\nA simple way to wait:\n\n```js\nsetup() {\n // This holds off the rendering.\n this.wait(true);\n\n Espo.Ajax.getRequest('Some/Request')\n .then(response => {\n // This cancels waiting and proceeds to rendering.\n this.wait(false); \n });\n}\n```\n\n!!! note\n\n Feel free to use the async/await syntax instead of explicit promises.\n\n### setup\n\nCalled internally on initialization. Put initialization logic here. Options passed by the parent view are available in `this.options`.\n\n### afterRender\n\nCalled internally after render. Put manipulation with DOM here.\n\n### onRemove\n\nCalled internally on view removal. Reasonable for unsubscribing.\n\n### createView\n\nCreates a child view. When we create a child view in the setup method, rendering of the view is held off until the child view is loaded (ready), the child view will be rendered along with the parent view. The first argument is a key name that can be used to access the view further (with `getView` method). The second argument is a view name. The method returns a promise that resolves to a view object.\n\nArguments:\n\n* *viewKey* – a view key;\n* *viewName* – a view name (path);\n* *options* – options.\n\nStandard options (all are optional):\n\n* *selector* – a relative CSS to the view selector (as of v7.3);\n* *model* – a model;\n* *collection* – a collection.\n\nIt's important that every view have their actual selector so that the application knows how to access them (for re-rendering).\n\n### clearView\n\nRemoves a child view.\n\nArguments:\n\n* *viewKey* – a view key.\n\n### getView\n\nGet a child view by a key.\n\nArguments:\n\n* *viewKey* – a view key.\n\n### assignView\n\n*As of v7.5.*\n\nAssign a view instance as a child view.\n\nArguments:\n\n* *viewKey* – a view key;\n* *view* – a view instance;\n* *selector* – a relative CSS selector.\n\n```js\nthis.assignView('someKey', new SomeView(options), 'some-selector');\n```\n\n### reRender\n\nRe-renders a view. Usually, called from inside the view. Returns a promise resolved once rendering is finished.\n\nArguments:\n\n* *force* – *boolean* – force rendering if the view was not rendered before.\n\n### render\n\nRenders a view. Should be called if the view is called not in the *setup* method (after the view is already ready or rendered). Returns a promise resolved once rendering is finished.\n\n```js\ntemplateContent = `\n{{{someKeyName}}}
\n`\n\nsetup() {\n this.createView('someKeyName', 'custom:test/my-custom-child-view', {}); \n}\n\nasync actionShowModal() {\n const view = await this.createView('dialog', 'custom:test/my-modal-view', {selector: '[data-name=\"someName]'})\n \n this.listenToOnce(view, 'some-event', eventData => {\n console.log(eventData);\n \n this.clearView('dialog');\n });\n\n await view.render();\n}\n```\n\n### whenRendered\n\nReturns the promise resolving when the view is rendered.\n\n```js\nthis.whenRendered().then(() => doSomethingWithDom());\n```\n\n### data\n\nThe method is called internally when rendering. Should return a key => value data (*Object.\n {{#each paymentRequests}}\n {{#if (equal status 'Pending') }}\n Payment Link {{number}}
\n {{/if}}\n {{/each}}\n
`. Good: `
`.\n\n### Charset issues\n\nIf some characters are not displayed in generated PDF files, it can be usually solved by changing the font in the template. For the Arabic language, use 'AlArabiya' font, for Chinese, use 'CID-0 cs'.\n\n\n### Access to templates\n\nAn administrator can add the *Templates* tab under Administration > User Interface. Access to templates must be defined in Roles (the *Templates* scope).\n\n### Page numbering\n\nPlaceholders are only available in footer (and also header if the header is set to be printed on each page).\n\n* `{pageNumber}` – the current number of the page\n\n### Page breaking\n\nIn places where you need to have an explicit page break, add:\n\n```\n{{pagebreak}}\n```\n\n### Condition checking\n\n#### Conditional rendering attribute x-if\n\n*As of v8.4.*\n\n```\n\n
\n```\n\nHelpers:\n\n* if\n* unless\n* ifEqual\n* ifNotEqual\n* equal\n* notEqual\n\n#### if\n\n```\n{{#if value}}\n {{value}}\n{{/if}}\n```\n```\n{{#if value}}\n {{value}}\n{{else}}\n No value\n{{/if}}\n```\n\n```\n{{#if condition1}}\n \n{{else if condition2}}\n\n{{else}}\n\n{{/if}}\n```\n\n#### unless\n\nOpposite to *if*.\n\n```\n{{#unless value}}\n No value\n{{/unless}}\n```\n\n```\n{{#unless value}}\n No value\n{{else}}\n {{value}}\n{{/unless}\n```\n\n#### ifEqual\n\n```\n{{#ifEqual a b}}\n a is equal b\n{{else}}\n a is not equal b\n{{/ifEqual}}\n```\n\n#### ifNotEqual\n\nOpposite to *ifEqual*.\n\n#### equal\n\n*As of v8.4.*\n\nReturns boolean.\n\n```\n{{#if (equal status 'Active')}}\n ...\n{{/if}}\n```\n\n#### notEqual\n\n*As of v8.4.*\n\nReturns boolean.\n\n```\n{{#if (notEqual status 'Active')}}\n ...\n{{/if}}\n```\n\n### Each iterator\n\nLooping through a list of items.\n\nExample:\n\n```\n{{#each contacts}}\n Contact name: {{name}}\n{{/each}}\n```\n\nArray (list):\n\n```\n{{#each array}}\n {{this}} – item\n {{@index}} – index\n{{/each}}\n```\n\nObject (map):\n\n```\n{{#each map}}\n {{this}} – item\n {{@key}} – key\n{{/each}}\n```\n\n!!! important\n\n Using `` and `` tags along with `{{#each}}` helper should be avoided as it breaks the markup of the *contenteditable* element. Use the *iterate* attribute instead.\n\nWith *iterate* attribute (as of v8.2):\n\n```html\n\n \n
\n```\n\nDisplaying certain number of items in one row:\n\n```\n{{#each contacts}}\n {{#ifMultipleOf @key 3}}
{{/ifMultipleOf}}{{name}} \n{{/each}}\n```\n\n!!! important\n\n The scope is changed inside an iteration block. To access parent scope attributes, use `../`.\n\nAccess the parent scope:\n\n```\n{{#each contacts}}\n Root record name: {{../name}}\n Contact name: {{name}}\n{{/each}}\n```\n\n### Lookup\n\nYou can use this helper to access object's and array's items.\n\nIn object (map):\n\n```\n{{lookup map key}}\n```\n\nIn an array:\n\n```\n{{lookup teamsIds index}}\n```\n\nLink-multiple example:\n\n```\n![](\"{{file)
\n```\n\nwhere `imageFieldNameId` – the name of an image field, concatenated with the suffix *Id*.\n\n\n### Date & time formatting\n\nSee info about [date formatting](../administration/date-formatting.md).\n\nFormat *Date-Time* field:\n\n```\n{{dateFormat createdAt_RAW format='MMMM DD, YYYY' timezone='Europe/London'}}\n```\n\nFormat *Date* field:\n\n```\n{{dateFormat closeDate_RAW format='YYYY MMMM DD'}}\n```\n\nPrint formatted *now*:\n\n```\n{{dateFormat now_RAW format='MMMM DD, YYYY HH:mm'}}\n```\n\nPrint formatted *today*:\n\n```\n{{dateFormat today_RAW format='MMMM DD,YYYY'}}\n```\n\nSpecific language:\n\n```\n{{dateFormat createdAt_RAW format='MMMM DD' language='de_DE'}}\n```\n\n### Number formatting\n\nTo display float numbers without a fractional part (as integer), use the following expression:\n\n```\n{{numberFormat quantity_RAW decimals=0}}\n```\n\nWhere `quantity` is a field name.\n\nCustom formatting for currency values:\n\n```\n{{numberFormat unitPrice_RAW decimals=2 decimalPoint=',' thousandsSeparator=' '}}\n```\n\nValue `10000.5` will be printer as `10 000,50`.\n\nNote that `_RAW` is appended to the field name.\n\n### Currency symbol\n\nA ready value prepared for all currency fields:\n\n```\n{{amountCurrencySymbol}}\n```\n\nUsing a helper (as of v9.3):\n\n```\n{{currencySymbol 'USD'}}\n```\n\nExample for a currency field named *amount*:\n\n```\n{{currencySymbol amountCurrency}}\n```\n\nwhere `amount` is a field name (of *currency* type).\n\n### Text field\n\nTo display text fields (multi-line) use triple braces:\n\n```{{{description}}}```.\n\nPrint Markdown (as of v8.1):\n\n```\n{{markdownText fieldName_RAW}}\n```\n\n### Related records\n\n*Many-to-many and one-to-many.*\n\nIt's possible to loop through a link collection.\n\nThe maximum number of records is 100. It can be changed with a config parameter *htmlizerLinkLimit*.\n\n!!! example\n\n Printing contact names and roles of an opportunity:\n\n ```\n {{#each contacts}}\n Name: {{name}},\n Role: {{opportunityRole}},\n Contact's Account Type: {{account.type}}\n {{/each}}\n ```\n\n Where *contacts* is a relationship name. You can obtain relationship names at Administration > Entity Manager.\n\n\n!!! example\n\n Example, printing contact names of an opportunity:\n\n ```\n {{#each contactsIds}}\n {{var this ../contactsNames}}\n {{/each}}\n ```\n\n### Multi-enum & Array fields\n\nPrinting selected items:\n\n```\n{{#each fieldName}}\n {{./this}}\n{{/each}}\n```\n\n### Checklist field\n\n```\nOption 1: {{checkboxTag fieldName option='Option 1' color='blue'}}\nOption 2: {{checkboxTag fieldName option='Option 2' color='blue'}}\nOption 3: {{checkboxTag fieldName option='Option 3' color='blue'}}\n```\n\n### Barcode field\n\n```\n{{barcodeImage barcodeField_RAW type='EAN8' width=60 height=30 fontsize=14 text=true padding=0}}\n```\n\nWhere *barcodeField* is the name of your barcode field.\n\nParameters *fontsize*, *text*, and *padding* are supported only in the TCPDF engine.\n\n(TCPDF only)\n\nAvailable types:\n\n* CODE128\n* CODE128A\n* CODE128B\n* CODE128C\n* EAN13\n* EAN8\n* EAN5\n* EAN2\n* UPC\n* UPCE\n* ITF14\n* pharmacode\n* QRcode\n\n### Raw values\n\nTo access a raw value of a specific attribute, you need to add a suffix `_RAW` to the attribute name. The raw value is a not formatted value. Raw date-time values are strings with values in the UTC timezone.\n\n!!! example\n\n Example (applying another format to the raw value):\n\n ```\n {{numberFormat quantity_RAW decimals=0}}\n ```\n\n *quantity* is a field name.\n\n### Maps\n\nIt's possible to print Google Maps image in PDF. See [here](../administration/maps.md#printing-in-pdf).\n\n### Custom helpers\n\nSee how to create custom helpers [here](../development/template-custom-helper.md).\n\nHelpers can be useful when the same part is used throughout many templates, for example, a header or footer. Printing of such parts can be delegated to a helper.\n\nHelpers can be also used for data formatting.\n"
},
{
"path": "docs/user-guide/products.md",
"content": "# Products\n\nThe Products feature is available in the [Sales Pack](https://www.espocrm.com/extensions/sales-pack/) extension.\n\nProducts can be added as line items in Quotes, Sales Orders, Invoices, Credit Notes, Delivery Orders, Receipt Orders, Purchase Orders, and Opportunities.\n\nThe *Product* entity type is available for customization in the Entity Manager. You can add custom fields to the Product as well as custom relationships between the Product and other entity types.\n\nA product record has 3 price fields: *Cost*, *List* and *Unit*. The list and unit prices are available only if product-level prices are enabled (in settings). There is the ability to automatically calculate the *Unit Price* using different formulas according to a selected *Pricing Type*. Prices can also be defined in Price Books. Note that it’s possible – and often advisable – to define prices exclusively in Price Books while leaving the list and unit price fields in the product record empty.\n\nProducts can be associated with Tax Classes, enabling automated tax application based on defined tax rules. Whenever a product is added to a document, the appropriate tax will be applied to the item.\n\nWith the Inventory Management feature enabled, you can track the availability of each product item. The *Is Inventory* field must be checked in the product record to enable inventory tracking.\n\nProducts can be printed to PDF. See more detail [here](quotes.md#templates).\n\nThe ability to add products as line items of an Opportunity is disabled by default. An administrator needs to add the *Items* panel under Administration > Entity Manager > Opportunity > Layouts > Bottom panels.\n\nIn this article:\n\n* [Categories](#categories)\n* [Variants](#variants)\n* [Properties](#properties)\n\n## Categories\n\nEach product can be linked to a category. Categories can be arranged in a hierarchical tree structure, where each category may include subcategories.\n\nThe Product Category is a separate entity type. Access to it is controlled by Roles.\n\n\n\n## Variants\n\n*As of Sales Pack v2.0.*\n\n### Product Attributes\n\nBefore being able to create products with variants, you need to create some Product Attributes. Product attributes are available under: Products > the top-right menu > Product Attributes.\n\nEvery product attribute is supposed to have a specific set of options. Add needed options on the Product Attribute detail view.\n\nExamples of attributes with their options:\n\n* Size – XS, S, M, L, XL\n* Color – Red, Blue, White, Black\n\n### Template Products\n\nA Template Product serves as a root for variants. Product variants inherit properties of its template, some properties can be overridden in variants.\n\nTo create a product with variants you need to create a template product. Click **Create Product** from the **Products** page, select *Template* **Type**. Then, in the **Template** tab, add needed attributes. For every attribute, select options needed options. Then **Save** the Product.\n\nAfter that, you need to generate variants. From the template product detail view, open the **Variants** tab in the bottom, click **Generate**. It will generate all possible combinations according to attributes and options of the product template.\n\nYou can remove variants that you don't need. E.g. a Red shirt is not produced in the XS size, hence, you need to remove the XS-Red variant.\n\nYou can re-generate variants. It will create all missing combinations.\n\n!!! important\n\n Once a product variant is references somewhere in the system (e.g. in a sales order), you should not remove that variant. Otherwise, after you re-generate it, it will be a different product record with a different ID.\n\n For the same reason, it's not recommended to add additional attributes to product templates, variants of which are already referenced.\n\n### Miscellaneous\n\nWhen you select a template product (e.g. in a Quote), a modal dialog will appear prompting to select a specific variant.\n\nInventory quantity is tracked on the variant level. When viewing the quantity of a Template product, the sum of all variants will be shown.\n\nAn Inventory Number cannot be associated with a Product Template. It should be associated with a specific Variant.\n\nIt's possible to specify Product fields that should be **synced** between Template and Variants. Administration > Entity Manager > Products > Edit > Variant sync fields. These fields will be read-only in Variants. Whenever the field value is changed in the Template, it will be automatically copied to the Variants. By default, the *Status* field is selected as synced.\n\n## Properties\n\nA product can marked as Sellable, Purchasable, or Subscribable.\n\n### Item Type\n\n*As of v4.0.*\n\nTwo options are available: Goods or Services. If Goods is selected, the product can be used in deliveries, receipts, and transfers, and it allows inventory tracking.\n\n### Allow Fractional Quantity\n\nIf enabled, it will be possible to use fractional quantity values for a product.\n\n### Track Inventory\n\nAvailable if the *Inventory Transactions* feature is enabled in the system. If the *Track Inventory* parameter is disabled in a product, its quantity won't be tracked.\n\nNote: In the earlier versions this parameter was called *Is Inventory*.\n\n### Inventory Number Type\n\nCan be empty, Batch or Serial. See more about inventory numbers [here](../extensions/sales-pack/inventory-management.md#inventory-numbers).\n\n### Removal strategy\n\nAvailable if *Inventory Number Type* is not empty. Determines how Inventory Numbers will be sorted when a user picks a number for a delivery or transfer order.\n\nAvailable options:\n\n* FIFO – first in, first out; sorted by *Incoming Date* in ascending order;\n* FEFO – first expired, first out; sorted by *Expiration Date* in ascending order;\n* LIFO – last in, first out; sorted by *Incoming Date* in descending order.\n\n### Expiration Days\n\nAvailable if *Inventory Number Type* is not empty. A number of days that is automatically added to the current date to determine an *Expiration Date* of an Inventory Number when the number is created in the system. Note that the Expiration Date then can be changed by a user.\n\n### Tax Classes\n\nTax classes allow the system to automatically select an appropriate Tax Code for a product. For example, a product can have a tax class named 'Zero-rated'. A tax item rule will map this tax class to a tax code with a zero rate. Then, every time the product is added to a document line, that tax code will be automatically set.\n"
},
{
"path": "docs/user-guide/quotes.md",
"content": "# Quotes\n\nThe Quotes feature is available in [Sales Pack](https://www.espocrm.com/extensions/sales-pack/).\n\nA quote is a formal pricing document that outlines specific products or services, along with their quantities and associated prices, offered to a customer.\n\nThe Quote entity type has a relationship with Opportunity type. You can add the *Quotes* panel to the Opportunity detail view at Administration > Layout Manager > Opportunities > Bottom Panels. When creating a new quote linked to an opportunity, it transfers opportunity items to the quote.\n\nYou can add the Quotes panel to the Account detail view to be able to see related quotes: Administration > Layout Manager > Accounts > Bottom Panels.\n\nIn the article:\n\n* [Converting from Opportunity](#converting-from-opportunity)\n* [Generating Sales Orders and Invoices from Quote](#generating-sales-orders-and-invoices-from-quote)\n* [Total values layout](#total-values-layout)\n* [Quote Items](#quote-items)\n* [Printing to PDF](#printing-to-pdf)\n* [Sending in email](#sending-in-email)\n* [Automatic numbering](#automatic-numbering)\n* [Copying values from product to quote item](#copying-values-from-product-to-quote-item)\n* [Locking](#locking)\n* [Automation with Workflows or BPM](#automation-with-workflows-or-bpm)\n\n## Converting from Opportunity\n\nMethod 1. Create a new quote, on the form, specify a needed opportunity. Data will be copied from the opportunity to the created quote.\n\nMethod 2. Create a new quote from Quotes relationship panel on the detail view of the opportunity. Note: The administrator needs to add the panel in the Layout Manager.\n\n## Generating Sales Orders and Invoices from Quote\n\nYou are able to create a Sales Order and an Invoice from an existing Quote.\n\nMethod 1. Create a new sales order or invoice, on the form, specify the needed quote. Data will be copied from the quote to the created sales order or invoice.\n\nMethod 2. Create a new sales order or invoice from the corresponding relationship panel on Quote detail view.\n\n## Total Values Layout\n\nThe layout of total value fields (in the bottom on detail view) can be modified at Administration > Layout Manager > Quotes > Bottom Total.\n\n## Quote Items\n\nA Quote has a list of items. Each item can represent a certain product or a service with description, quantity, tax rate, list price, and unit price fields. It's possible to sort items manually.\n\nThere is the ability to add custom fields for the Quote Item entity type using the Entity Manager.\n\n### Quote Items layout\n\nThe layout of quote items can be modified at Administration > Layout Manager > Quote Items > List (Item).\n\n### Discount Rate\n\nIt's possible to specify a discount in percents. To have this ability, the administrator should add the *Discount (%)* field to the *List (Item)* layout.\n\n## Printing to PDF\n\nQuotes can be printed to PDF. This action is available in the dropdown next to Edit button on the quote’s detail view. Then, you will be prompted to select a Template. More info about printing to PDF is available [here](printing-to-pdf.md).\n\n### Templates\n\nAn example template is available by default. You can create new templates (Quotes list view > top-right dropdown menu > Templates) as well as edit existing ones.\n\nFor more precise template editing, you can use the Code View mode.\n\nYou can print fields ofa Quote record as well as fields of related records by utilizing placeholders in your template.\n\nExamples:\n\n`{{accountName}}` – Account name,\n\n`{{{billingAddressStreet}}}` – street,\n\n`{{account.type}}` – type of related Account,\n\n`{{assignedUser.lastName}}` – last name of the assigned user.\n\nIf your line item is a product, you can print product’s fields.\n\nExamples:\n\n`{{product.length}}`,\n\n`{{product.color}}`.\n\nIn examples, the length and color are custom fields of the Product entity type.\n\nLooping through quote items:\n\n```\n \n {{order}} \n {{name}} \n {{quantity}} \n {{product.weight}} \n {{listPrice}} \n {{unitPrice}} \n {{amount}} \n \n```\n\nOr:\n\n```\n\n {{order}} \n {{name}} \n {{quantity}} \n {{product.weight}} \n {{listPrice}} \n {{unitPrice}} \n {{amount}} \n\n```\n\nIt's possible to print image fields:\n\n```\n\n```\n\nWhere `imageId` – the name of the custom image field concatenated with the suffix `Id`.\n\nFor product line item:\n\n```\n\n```\n\nTo display float numbers (like quantity, unitPrice etc.) without a fractional part (as integer), use the following expression:\n\n```\n{{numberFormat quantity_RAW decimals=0}}\n```\n\nCustom formatting for currency values:\n\n```\n{{numberFormat unitPrice_RAW decimals=2 decimalPoint=',' thousandsSeparator=' '}}\n```\n\nValue `10000.5` will be printer as `10 000,50`.\n\nTo display text fields (multiline), use triple braces: `{{{description}}}`.\n\n#### Quote Items attributes\n\nYou can use these attributes in a template inside the loop `{{#each itemList}}` or ``:\n\n* name\n* quantity\n* listPrice\n* unitPrice\n* discount\n* amount\n* unitWeight\n* weight\n* taxRate\n* order\n* description\n\nAll fields can be found at Administration > Entity Manager > Quote Items > Fields.\n\n## Sending in email\n\nA Quote PDF can be sent in an email as an attachment. Open a quote record, click the dropdown next to Edit button, and then click Email PDF.\n\nThe default email template can be set by the administrator: Administration > Sales Pack Settings > Email Templates.\n\nTo have the Quote entity selected as the email's parent, the administrator should add the Quote entity type to the parent type list. Administration > Entity Manager > Email > Fields > Parent > Entity List. As of v3.0.\n\n## Automatic numbering\n\nBy default, the *Number* field is auto-incremented. You can disable auto-increment at Administration > Entity Manager > Quote > Fields > number. It's also possible to make the number field read-only.\n\nThe prefix of the next number, the next number itself and the quantity of digits in the number can be configured at Administration > Entity Manager > Quote > Fields > numberA.\n\nBy default, there is no *Name* field on the *Detail* layout. The *Number* is used as a name. You can add the Number field at Administration > Entity Manager > Quote > Layouts > Detail.\n\nBy default, the *Name* field is synced with *Number*. To be able to specify arbitrary names, you need to disable the *Sync with Number* and *Read-only* parameters at Administration > Entity Manager > Quote > Fields > Name.\n\n## Copying values from product to quote item\n\nField values can be transferred from a product to a quote item upon product selection. Field names you want to be copied should coincide in Product and Quote Item entity type.\n\nYou can select which fields you need to be copied at Administration > Entity Manager > Quote Item > Fields > Product > Fields to Copy.\n\n## Locking\n\nA Quote can be locked if it's completed or canceled. When a record is locked, a specific fields become read-only. An administrator can configure the field list at: Administration > Entity Manager > Quote > Edit.\n\nIf the settings parameter *Forbid order unlocking* is checked, once a record is locked, it can be unlocked only by an administrator.\n\n## Automation with Workflows or BPM\n\nThe following service actions are available in Workflows and BPM tools:\n\n* Add Quote Items\n* Convert Currency\n* Send in Email\n\n## See also\n\n* [Custom calculations for Quote totals](../development/quote-custom-calculations.md)\n"
},
{
"path": "docs/user-guide/reports.md",
"content": "---\nsearch:\n boost: 2\n---\n\n# Reports\n\nThe Reports feature is available in [Advanced Pack](https://www.espocrm.com/extensions/advanced-pack/). It provides the analytic capabilities and two additional functionalities: report panels and custom list view filters.\n\nThere are three types of reports:\n\n* List\n* Grid\n* Joint Grid\n\nIn this article:\n\n* [List reports](#list-reports)\n* [Grid reports](#grid-reports)\n* [Joint Grid reports](#joint-grid-reports)\n* [Filters](#filters)\n* [Displaying on dashboard](#displaying-on-dashboard)\n* [Email sending](#email-sending)\n* [Printing to PDF](#printing-to-pdf)\n* [Syncing with Target Lists](#syncing-with-target-lists)\n* [List view filters based on reports](#report-filters)\n* [Reports panels](#report-panels)\n* [Portal access](#portal-access)\n* [Formula functions](#formula-functions)\n\nSee also:\n\n* [Complex expressions](complex-expressions.md)\n* [Quick tour](https://app.supademo.com/demo/cmca8j4uc1gy18qszrhdt68jy)\n\n\n## List Reports\n\nA List report displays the list of records that meet the specified criteria.\n\nTo create a new list report, click on the *Reports* tab and then click the *Create Report* button. Then, select the entity type to which your report will apply.\n\nIn the *Columns* field, select the fields you would like to have displayed in the report. Underneath, you can configure how each column is displayed with the following parameters:\n\n* Width – width in percents;\n* Align – how to align data: left or right;\n* Link – value will be displayed as a link leading to the record detail view;\n* Export Only – the column won't be displayed in report results on the UI, but it will be available in export;\n* Not Sortable – the column cannot be ordered by, some fields are not available for sorting;\n* Hidden – the column will be hidden but can be optionally shown in the report result view.\n\nChoose the needed sorting in the *List Order* field.\n\nIn the *Filters* section, you can specify criteria that determine what records will be included in your report. You can use logical operators 'OR' and 'AND' here.\n\n*Runtime Filters* lets you narrow down the results each time you run the report, without needing to edit the report itself. It's useful when the report structure stays the same, but you want to change the criteria dynamically – like choosing a specific date range, customer, or status before generating the results.\n\nYou can *export* list report results to XLSX (spreadsheet) and CSV formats.\n\nAn example of list report results:\n\n\n\nWhere list reports can be also utilized:\n\n* Scheduled workflows – to do some scheduled actions over records that met criteria specified by a list report.\n* Scheduled BPM processes – to start BPM processes for records that met some criteria.\n* Sync with target lists – to add records that met some criteria to target lists, more info [below](#syncing-with-target-lists).\n* List view filters – to filter records on the list view according to the criteria specified in the list report, more info [below](#report-filters).\n* Panels on the detail view – to display related records that met some criteria on the side panel, more info [below](#report-panels).\n* Applying assignment rule – to assign records that met specific criteria by workflow or BPM.\n\n### Results view\n\nThe results view can be accessed under: Report detail view > Results View button (top-right corner). Here, the report is displayed in full width. You can show or hide specific columns as well as resize them.\n\n## Grid Reports\n\nGrid reports display summarized values, can be grouped by one or two fields, and support chart visualization.\n\nTo create a new grid report, click on the *Reports* tab and then click the *Create Report* button. Then, select the entity type to which your report will apply.\n\nWhen choosing the *Entity Type* for a grid report, consider the following. The *Entity Type* should contain the field that data will be aggregated by. For example, if you need to sum by the opportunity amount, choose the Opportunity entity type. If you need to aggregate by fields from different entity types, consider creating separate grid reports for each entity type and then use a Joint Report to join them into one.\n\nAn example of grid report results showing revenue grouped by a user:\n\n\n\n!!! tip\n\n When dealing with long tables with many columns, you can use Shift + Mouse Wheel to scroll horizontally. It can also be helpful to use the Result View, which displays the report data in full width.\n\n### Group By\n\nIn the *Group By* field, pick one or two fields you want your report data be grouped by. For date fields, it's possible to apply grouping by year, quarter, month, week, and day. If you leave the Group By field empty, the report will not apply any grouping.\n\nThere is the ability to craft a [complex expression](complex-expressions.md) for grouping. Complex expressions are internally translated into SQL statements. Complex expressions offer various use cases. For instance, the MAP function can be used to group data by region rather than by country.\n\nExample:\n\n```\nMAP:(\n account.billingAddressCountry,\n 'United States', 'United States',\n 'Germany', 'Europe',\n 'France', 'Europe',\n 'Italy', 'Europe',\n 'Other'\n)\n```\n\nA report grouped by two fields is called *two-dimensional*.\n\nThe results table for two-dimensional Grid reports can be displayed in two modes:\n\n- Regular – columns represent the first grouping field, and rows represent the second grouping field.\n- Normalized – unpivoted (flattened), with both grouping fields displayed in rows.\n\n### Columns\n\nIn the *Columns* field, select one or more **aggregate** functions applied to a specific field.\n\nFunctions:\n\n* COUNT – number of records;\n* SUM – summation, applied to Currency, Int and Float fields;\n* MIN – minimal value;\n* MAX – maximal value;\n* AVG – average value.\n\nIf a report is grouped by a link field, then it's possible to include fields from the linked record without an aggregate function applied to it. In the example below, the report for Opportunities with grouping by Campaign with Campaign.Budget column included.\n\nIt's possible to add **non-aggregated columns**. In this case, records will be displayed for each group. Note that if your report deals with a big number of records, it can run much slower.\n\nNon-grouping grid report with non-aggregated columns:\n\n\n\nGrouping grid report with non-aggregated columns:\n\n\n\nThere is the ability to craft [complex expressions](complex-expressions.md) for columns. Complex expressions are internally translated into SQL statements.\n\n### Order by\n\nThe *Order By* field defines how the report results will be sorted.\n\n### Filters section\n\nIn the *Filters* section, you can specify criteria to limit data displayed in the report results. You can use logical operators 'OR' and 'AND' here. See more info [below](#filters).\n\n### Runtime filters\n\n*Runtime Filters* lets you narrow down the results each time you run the report, without needing to edit the report itself.\n\n!!! note\n\n Specifying a runtime filter can be also useful for dashlets and report panels. It allows you to have filters applied to a particular dashlet or panel.\n\n### Charts\n\nGrid report allows displaying results in chart form.\n\nThere are the following chart types available:\n\n* Bar (Horizontal);\n* Bar (Vertical);\n* Bar Grouped (Horizontal) (only for report with grouping by 2 columns);\n* Bar Grouped (Vertical) (only for report with grouping by 2 columns);\n* Pie (only for report with grouping by 1 column);\n* Line.\n\nBar:\n\n\n\nBar Grouped:\n\n\n\nLine:\n\n\n\nPie:\n\n\n\n### Export\n\nIt's possible to export grid report results to XLSX (spreadsheet) and CSV formats. Both a results table and chart are exported to XLSX.\n\n!!! important\n\n If a Grid report contains non-aggregated columns, the chart is not printed on the spreadsheet.\n\n### Access\n\nBy checking *Apply access control*, the report result will not include records that the current user does not have access to.\n\nIf a regular user does not have edit access to the *Apply access control* field (via field level security in Roles), all reports they create will have the *Apply access control* automatically checked.\n\n## Joint Grid reports\n\nJoint Grid reports combine multiple Grid reports. A combined report can bring together data from reports that target different entity types.\n\nGrid reports selected for a Joint report must use either one grouping field or none.\n\nIf you need to aggregate by fields from different entity types, consider creating separate Grid reports for each entity type and then use the Joint report type to combine them into one.\n\nSome usage examples:\n\n* Lead count / Contact count;\n* Revenue by month / Campaign Budget by month;\n* Revenue by user / Lead count by User.\n\nYou can create a new Joint Grid report from the dropdown menu in the top-right corner in the Reports list view.\n\nColors of chart columns are determined by chart colors set in the respective sub-reports.\n\nRuntime filters are not supported in Joint reports. Only regular filters specified in each sub-report can be used.\n\nNon-aggregate columns are not supported in Joint reports.\n\n## Filters\n\n### Field filter\n\nField filters are simple to use. They allow to filter by specific fields of a target entity type as well as fields of related records. For example, you can filter Opportunities by a field of the Account entity type.\n\n\n\n### OR group\n\nOR means that at least one condition in the group must be met.\n\n\n\n### AND group\n\nAND means that all conditions in the group must be met.\n\n### NOT IN group\n\nNOT IN provides the ability to filter records that don't meet specified criteria. E.g. listing accounts that don't have any opportunity with 'Closed Won' or 'Closed Lost' status.\n\n!!! note\n\n It's recommended to avoid using NOT IN group when possible, by using filters 'Not Equals', 'None of', etc. instead. NOT IN group uses a sub-query that can negatively affect report performance in some cases.\n\n\n\n### IN group\n\nIN is similar to AND group but utilizes a sub-query.\n\nThe example of usage: Filtering accounts that have opportunities of both 'Closed Won' and 'Negotiation' stages.\n\n\n\n### Complex Expression\n\nFor more advanced use. You can apply a database function to a certain database column and compare it with a result calculated by a [formula](../administration/formula.md) expression.\n\n!!! note\n\n If you need to compare just with a simple string value you should put it into single quotes `'some string'`.\n\n!!! note\n\n Formula functions intended to interact with the entity record will not work here because the formula is not applied to a specific record.\n\nApplying function to a column and comparing with a result of formula:\n\n\n\nComparing the result of the custom complex expression and the result of the formula expression:\n\n\n\n* Complex expression is translated into an SQL statement and becomes a part of an SQL query.\n* Formula is executed before running the report and the result value is substituted into an SQL query.\n* Comparison operator is substituted into an SQL query between the complex expression statement and the formula result value.\n\nMore info about complex expressions is available [here](complex-expressions.md).\n\n!!! example\n\n Filter record that were created after less than 12 month from the creation of a related account. For example, it can be used to show sales only from new customers.\n\n ```\n LESS_THAN:(\n TIMESTAMPDIFF_MONTH:(\n account.createdAt,\n createdAt\n ),\n 12\n )\n ```\n\n### Having group\n\nThe Having group provides the ability to filter records with using aggregate functions COUNT, SUM, MAX, MIN, AVG.\n\nSome use cases:\n\n* List of accounts having more than one opportunity. `COUNT / opportunities.id / Greater Than / 1`.\n* Grid report showing accounts grouped by industry where revenue is more than 1,000. `SUM / opportunities.amount / Greater Than / 1000`.\n\n## Displaying on dashboard\n\nYou can display any report on the dashboard. In order to do it, you need to add the Report dashlet to the dashboard and then pick the needed report from the dashlet options.\n\nFor grid reports it's possible to display:\n\n* Chart\n* Chart & Total\n* Total\n* Table\n\nFor list reports it's possible to display:\n\n* List\n* Total (number or records)\n\nFor list reports, you can either display the list or records or only the total number of records.\n\nDashlet with only totals displayed:\n\n\n\n## Email sending\n\nIt's possible to set up the system send report results to certain users on a regular basis according to specified time. This must be configured for certain reports individually.\n\nThe Max number of records that can be sent in an email by default is set to 3000. You can increase it by adding the parameter to data/config.php: `'reportSendingListMaxCount' => 5000`.\n\n## Printing to PDF\n\n!!! note\n\n A user needs to have access to the *Template* scope in Roles.\n\n You need to have at least one PDF Template record for the Report entity type. The template can be created at Administration > PDF Templates.\n\nTo print a Report: on the Report detail view on the *Report* panel, from the dropdown next to the *Edit* button, click *Print to PDF*.\n\nIn a PDF template, `{{reportTable}}` helper is used to print a report results table.\n\nExample:\n\n```\n{{reportTable border=1 borderColor=\"#333\" cellpadding=2 fontSize=9}}\n```\n\nAvailable attributes:\n\n* border – a border with;\n* borderColor;\n* cellpadding;\n* fontSize;\n* color – a text color;\n* flip – to flip table, true or false;\n* width – a table width, a CSS parameter (as of v3.1).\n\n## Syncing with Target Lists\n\nIt's possible to have target lists synced with list report results. It's convenient for mass email when you would like to send emails only to contacts that meet some criteria at the moment of sending. This feature is available in the detail view of any target list in the *Sync with Reports* panel.\n\n## Report filters\n\nThe Report Filters feature allows you to create custom primary filters for list views. These filters can also be used in specific formula functions.\n\nAn administrator can create custom list view filters based on specific reports. Available under: Administration > Report Filters. It's possible to specify teams that will have access to the filter.\n\n!!! note\n\n The layout, that is specified in the report, is not applied to the list view when the filter is selected.\n\n\n\nReport filters can utilized in *Record List* dashlets (as a primary filter).\n\nReport filters can be utilized in [formula functions](../administration/formula.md#filter):\n\n* `record\\count`\n* `record\\findOne`\n* `record\\findRelatedOne`\n* `record\\findRelatedMany`\n* `entity\\sumRelated`\n* `entity\\countRelated`\n\n## Report panels\n\nThe Report Panels feature allows you to create custom detail view panels that display report results.\n\nAn administrator can create custom side and bottom panels for the detail view of the specific entity type. It's possible to specify teams that will have access to the panel.\n\nBoth Grid and List reports can be used.\n\nFor grid reports it's possible to display:\n\n* Chart\n* Chart & Total\n* Total\n* Table (as of v2.7.0)\n\nFor list reports it's possible to display:\n\n* List\n* Total (number or records)\n\nThe order of side panels can be customized under: Administration > Entity Manager > {Entity Type} > Layouts > Side Panels (Detail).\n\nThe order of bottom panels can be customized under: Administration > Entity Manager > {Entity Type} > Layouts > Bottom Panels.\n\nThe report panel displays results related to the record that is viewed. The first found relationship is used. If a report has an appropriate runtime filter, then it will be used to filter report results. The runtime filter must be a field of a Link, Link-multiple or Link-parent type. \"For example, if a report is for Opportunity and has a runtime filter Account, that filter will be automatically applied when the report panel is added to the Account detail view.\n\n## Portal access\n\nSpecific reports can be allowed for specific portals. For this, you need to add the portal in the *Portals* field of the Report. The Portal Role assigned to the portal should have defined access to the *Reports* scope with the *Read* action set to *all*.\n\nIt's possible to add a report dashlet to the portal dashboard.\n\n!!! note\n\n For grid reports which are meant be available in the portal, it's usually reasonable to enable [Apply ACL](#access).\n\n## Formula functions\n\n### report\\export\n\n`report\\export(REPORT_ID, [USER_ID])`\n\n*As of v3.6.*\n\nGenerates an XLSX export file and returns an attachment ID. An optional USER_ID allows you to apply access restrictions for a specific user. Note that generated attachments have the role `Export File`, hence they will be automatically deleted by the cleanup job. To prevent deletion, you can change the role to `Attachment`.\n\n## See also\n\n* [Complex expressions](complex-expressions.md)\n* [Billing transactions](https://www.espocrm.com/blog/tutorial-billing-transactions/)\n"
},
{
"path": "docs/user-guide/sales-management.md",
"content": "# Sales Management\n\nIn this article:\n\n* [Leads](#leads)\n* [Opportunities](#opportunities)\n* [Accounts](#accounts)\n* [Currency](#currency)\n* [Sales analytics](#sales-analytics)\n* [See also](#see-also)\n\n## Leads\n\nA Lead represents a person or organization that is not currently a customer but has the potential to be. Creating a new Lead record is usually the first step in the sale process. As more information about the Lead is gathered, the Lead is expected to be converted into an Account, Contact, and/or Opportunity.\n\nNew Leads are typically created in the following scenarios:\n\n* manually by CRM users;\n* through the API (e.g. through a web form);\n* automatically by a Workflow rule.\n\nBy utilizing the [Workflows](../administration/workflows.md) tool, an administrator can set up the system to apply a specific assignment rule to new Leads. *Round-Robin* and *Least-Busy* rules are available. For more complex business flows, it's recommended to utilize the [BPM tool](../administration/bpm.md).\n\nUsers can also create a Lead from an Email – from the top-right dropdown menu.\n\nTo prevent overlooking of new Leads, users can add the *Lead* entity type to the *Global Auto-follow* list in Preferences. Then, they will automatically follow every new Lead created in the system they have access to.\n\nIt may be useful to enable the Kanban view for Leads. It can be enabled under: Administration > Entity Manager > Lead > Edit > Kanban View.\n\n### Target lists\n\nLeads can be added to Target Lists, which is useful for both marketing and organizing purposes. A user can use the Target Lists filter in the Leads list view to segment leads by the selected target list for further processing.\n\n### Converting\n\nTo convert a Lead, you need to click *Convert* button on the Lead detail view. Then, you can check to what record types you want to convert: Account, Contact, and/or Opportunity.\n\nA converted Lead won't be removed from the system. It will have status *Converted*, records it was converted to, will be available in the *Converted To* panel on the right.\n\nNote that Leads cannot be converted to Accounts if the system is set to the B2C mode.\n\n## Opportunities\n\nAn Opportunity represents a potential deal or closed sale.\n\n!!! note\n\n Opportunities with the *Closed Won* stage are taken into account in the default sales dashlets. Using Opportunities to calculate revenue is an option that may be suitable for small businesses.\n\nFor Opportunities, the Kanban view is enabled by default. Users can switch between the List and Kanban views.\n\n### Stage\n\nThe following opportunity stages are available by default:\n\n* Prospecting\n* Qualification\n* Proposal\n* Negotiation\n* Closed Won\n* Closed Lost\n\nAn administrator can define custom stages depending on the business workflow of the company: Administration > Entity Manager > Opportunity > Fields > Stage. It's also possible to define custom probability values for each stage.\n\n### Probability\n\nThe Opportunity probability is an estimated percentage chance that the sale will be won. The *Closed Won* status has a 100% probability, the *Closed Lost* – zero. Other stages has their specific probabilities between 0% and 100%. The probabilities can be modified in the Entity Manager.\n\n!!! note\n\n Probabilities can be utilized in revenue forecasting.\n\n## Accounts\n\nAccounts play a central role in EspoCRM. They represent companies and organizations your business works with.\n\nAn Account has relationships with the following records:\n\n- Contacts\n- Opportunities\n- Cases\n- Documents\n\nUsers can subscribe to a particular Account record to see updates that concern that Account.\n\nAccount records can be added to Target Lists, which you can use for marketing purposes or for organizing your data.\n\n## Currency\n\nAn administrator can define available currencies and their rates at Administration > Currency.\n\nIt's possible to convert currency of existing Opportunities:\n\n* on the list view: select needed records and then click *Convert Currency* in the *Actions* dropdown;\n* on the detail view: click the dropdown next to the *Edit* button, then *Convert Currency*.\n\n## Sales analytics\n\nThe following charts are available on the dashboard by default:\n\n* Sales by Month\n* Opportunities by Lead Source\n* Opportunities by Stage\n* Sales Pipeline\n\nBy utilizing the [Reports tool](reports.md), it's possible to view sales statistics based on specific criteria. Report charts can be displayed on the dashboard.\n\n### Revenue forecast\n\nAvailable with Reports from Advanced Pack.\n\n1. Create a new grid report for Opportunity entity type.\n2. Add 'MONTH: Close Date' to Group By field.\n3. Add 'SUM: Amount Weighted' to Columns field.\n4. Add 'Close Date' to Runtime Filters field.\n5. Select 'Bar (vertical)' chart type.\n\nThis report will show the revenue forecast based on probabilities of Opportunities.\n\nUsers who have access to this report will be able to add it on their dashboards.\n\n## See also\n\n* [Quick tour on Leads](https://app.supademo.com/demo/cmhc0w8ns14v6fatilwlycmjn)\n* [Quick tour on Opportunities](https://app.supademo.com/demo/cmhkj43rn1k3xu1hm0zxfmhb6)\n* [Quick tour on Accounts](https://app.supademo.com/demo/cmhxas59c35xb17y0s8mr6co6)\n* [Who are leads? Lead conversion in 3 steps](https://www.espocrm.com/tips/lead-conversion/)\n"
},
{
"path": "docs/user-guide/sales-orders.md",
"content": "# Sales Orders\n\nThe Sales Orders feature is available in [Sales Pack](https://www.espocrm.com/extensions/sales-pack/) extension.\n\nA Sales Order is a document representing a confirmed customer order, and contains a group of products or services with their quantities and prices.\n\nYou can add the Sales Orders panel to the Account detail view to be able to see related sales orders. At Administration > Layout Manager > Accounts > Bottom Panels.\n\nYou can add the Sales Orders panel to the Opportunity detail view at Administration > Layout Manager > Opportunities > Bottom Panels.\n\nIn the article:\n\n* [Converting from Opportunity or Quote](#converting-from-opportunity-or-quote)\n* [Generating Invoices from Sales Order](#generating-invoices-from-sales-order)\n* [Total Values Layout](#total-values-layout)\n* [Sales Order Items](#sales-order-items)\n* [Delivery](#delivery)\n* [Printing to PDF](#printing-to-pdf)\n* [Sending in email](#sending-in-email)\n* [Automatic numbering](#automatic-numbering)\n* [Copying values from product to sales order item](#copying-values-from-product-to-sales-order-item)\n* [Locking](#locking)\n* [Automation with Workflows or BPM](#automation-with-workflows-or-bpm)\n\n## Converting from Opportunity or Quote\n\nMethod 1. Create a new sales order. On the form, select an opportunity or a quote. Data will be copied from the opportunity/quote to the created sales order.\n\nMethod 2. Create a new sales order from the Sales Orders relationship panel on the detail view of the opportunity/quote.\n\n## Generating Invoices from Sales Order\n\nYou are able to create Invoices from an existing Sales Order record.\n\nMethod 1. Create a new invoice. On the form, select a needed sales order. Data will be copied from the sales order to the created invoice.\n\nMethod 2. Create a new invoice from the Invoices relationship panel on the detail view of the sales order record.\n\n## Total Values Layout\n\nThe layout of total value fields (in the bottom on detail view) can be modified at Administration > Layout Manager > Sales Orders > Bottom Total.\n\n## Sales Order Items\n\nA Sales Order has the list of items. Each item can represent a certain product or a service with description, quantity, tax rate, list price, and unit price fields. It's possible to sort items manually.\n\nThere is the ability to add custom fields to the Sales Order Item entity type using the Entity Manager.\n\n### Sales Order Items Layout\n\nThe layout of Sales Order Items can be modified at Administration > Layout Manager > Sales Order Items > List (Item).\n\n### Discount Rate\n\nIt's possible to specify a discount in percents. To have this ability, an administrator should add the *Discount (%)* field to the *List (Item)* layout.\n\n## Delivery\n\nA Delivery Order can be created from a Sales Order. A button in the top-right corner will appear when the Sales Order is eligible for delivery. The Sales Order must have at least one Product of *Goods* product type to have the ability to create a delivery. \n\n## Printing to PDF\n\nSales Orders can be printed to PDF. This action is available in the dropdown next to the Edit button on the sales order’s detail view. Then, you will be prompted to select a template. More info about printing to PDF is available [here](printing-to-pdf.md).\n\n### Templates\n\nSee the documentation [for quote templates](quotes.md#templates).\n\n## Sending in email\n\nA Sales Order PDF can be send in an email as an attachment. Open a sales order record, click the dropdown next to the Edit button and then click Email PDF.\n\nThe default email template can be set by the administrator: Administration > Sales Pack Settings > Email Templates.\n\nTo have the Sales Order entity selected as the email's parent, the administrator should add the Sales Order entity type to the parent type list. Administration > Entity Manager > Email > Fields > Parent > Entity List. As of v3.0.\n\n## Automatic numbering\n\nBy default, the *Number* field is auto-incremented. You can disable auto-increment at Administration > Entity Manager > Sales Order > Fields > number. It's also possible to make the number field read-only.\n\nThe prefix of the next number, the next number itself and the quantity of digits in the number can be configured at Administration > Entity Manager > Sales Order > Fields > numberA.\n\nBy default, there is no *Name* field on the *Detail* layout. The *Number* is used as a name. You can add the Number field at Administration > Entity Manager > Sales Order > Layouts > Detail.\n\nBy default, the *Name* field is synced with *Number*. To be able to specify arbitrary names, you need to disable the *Sync with Number* and *Read-only* parameters at Administration > Entity Manager > Sales Order > Fields > Name.\n\n## Copying values from product to sales order item\n\nField values can be transferred from a product to a sales order item upon product selection. Field names you want to be copied should coincide in the Product and the Sales Order Item entity types.\n\nYou can select which fields you need to be copied: Administration > Entity Manager > Sales Order Item > Fields > Product > Fields to Copy.\n\n## Locking\n\nA Sales Order can be locked if it's completed or canceled. When a record is locked, a specific fields become read-only. An administrator can configure the field list at: Administration > Entity Manager > Sales Order > Edit.\n\nIf the settings parameter *Forbid order unlocking* is checked, once a record is locked, it can be unlocked only by an administrator.\n\n## Automation with Workflows or BPM\n\nThe following service actions are available in Workflows and BPM tools:\n\n* Add Sales Order Items\n* Convert Currency\n* Send in Email\n\n## See also\n\n* [Custom calculations for Quote totals](../development/quote-custom-calculations.md)\n"
},
{
"path": "docs/user-guide/shortcuts.md",
"content": "# Shortcut keys\n\n*As of v7.2.*\n\n!!! note\n\n On Mac OS, the CMD key (⌘) is the equivalent of the Ctrl.\n\n## General\n\n* `Ctrl + Middle-Click` – open a record in a quick view modal (when applied on a record link);\n\n## Record list\n\n* `Ctrl + Enter` – apply search filter;\n* `Ctrl + Space` – create new record;\n* `Ctrl + /` – focus on search-bar;\n* `Ctrl + <` – previous primary filter;\n* `Ctrl + >` – next primary filter;\n* `Ctrl + Arrow Left` – previous page;\n* `Ctrl + Arrow Right` – next page;\n\n!!! note \"Tip\"\n\n A combination `Ctrl + Middle-Click` (on a record link) followed by `Ctrl + Space` can be used for quick edit.\n\n## Record detail\n\n* `Ctrl + Space` – switch to edit;\n* `Ctrl + \\` – switch through tabs;\n* `Ctrl + Arrow Left` – previous record;\n* `Ctrl + Arrow Right` – next record;\n\n## Record edit\n\n* `Ctrl + Enter` – save and exit;\n* `Esc` – cancel;\n* `Ctrl + S` – save and continue editing;\n* `Ctrl + Alt + Enter` – save and create new (from the create view);\n\n## Calendar\n\n* `Arrow Left` – previous range;\n* `Arrow Right` – next range;\n* `Home` – move to today;\n* `Minus` – zoom out (timeline);\n* `Plus` – zoom in (timeline);\n* `1..6` – switch between view modes, refresh if the current mode;\n* `Ctrl + Space` – create event;\n\n## Image preview\n\n* `Arrow Left` – previous image;\n* `Arrow Right` – next image;\n\n## Emails\n\n* `Ctrl + Delete` – move selected emails to Trash;\n* `Ctrl + Backspace` – move selected emails to Archive (as of v8.3);\n* `Ctrl + I` – mark selected emails as Important or Not Important;\n* `Ctrl + M` – move selected emails to a specific folder;\n* `Ctrl + Q` – mark all emails as read; mark selected emails as read (as of v9.0);\n\n## Text formatting\n\n* `Ctrl + B` – bold;\n* `Ctrl + I` – italic;\n"
},
{
"path": "docs/user-guide/stream.md",
"content": "# Stream\n\nStream in EspoCRM is a feed where you can see posts and updates of records you follow. You can also post messages to your own Stream and to the Stream of other Users.\n\nBy default, the following entity types have the Stream enabled: Accounts, Contacts, Leads, Opportunities, Cases, Meetings, and Tasks. An administrator can enable or disable the Stream for a certain entity type under Administration > Entity Manager > {Entity Type} > Edit.\n\n## Record Stream\n\nThe *Stream* panel is available on the record detail view in the bottom. Posts and updates related to the record are displayed here. Each entry in the stream is represented by a *Note* entity.\n\nAn administrator can move the Stream panel down so that it will appear under other panels or put the panel into a tab. This can be done at Administration > Entity Manager > {Entity Type} > Layouts > Bottom Panels.\n\nStream posts can be pinned. A user needs to have *edit* access to a record to be able to pin or unpin Stream posts.\n\n### Access\n\nAccess to the Stream is controlled by Roles and can be configured per entity type. For example, it's possible to configure that users have access to the Stream of records related to their team.\n\nWith the [Collaborators](../administration/roles-management.md#collaborators) feature enabled, users who are record collaborators can access the Stream of the record, provided their access level, as defined by Roles, is other than *no*.\n\n## User Stream\n\nUsers can view their own Stream in the *Stream* dashlet as well on the separate Stream page.\n\nUsers can see Stream of another users on the user's detail view if they have access defined by the *User Permission* in Roles. In the user's Stream, you can see posts and updates of records that the user follows. You can also see posts addressed to that user.\n\nIt's possible to view all activity for a specific user. It will display all notes that either created directly by the user or created as a result of that users' actions. Available from the dropdown menu on the Stream panel on the User's detail view. As of v8.2.\n\n## Notifications\n\nA user receives notifications about new stream entries in followed records.\n\n## Posts\n\nYou can create a post related to a certain record. You are also able to attach multiple files and images to a post. Images can be pasted from the clipboard.\n\n### Mentions\n\nIf you want to mention somebody in your post, you need to type `@` symbol and start typing the user's name. The user you have mentioned in your post will be notified.\n\n!!! note\n\n The user who was mentioned in the post needs to have access to the Stream of the record where they were mentioned. Otherwise, the user won't receive a notification about the post.\n\n!!! note\n\n The user needs to have a proper *Mention Permission* (set in Roles) to be able to mention a specific user. If the assignment permission is set to `no`, then the user won't be able to mention anyone. If set to `team`, then they will be able to mention only users of their teams. If set to `all`, then they will be able to mention anyone. Portal users are not able to mention users.\n\n### Attachments\n\nUsers can attach files stream posts.\n\nAn administrator can configure the *Attachments* field at Administration > Entity Manager > Note > Fields > attachments (as of v7.2). The following parameters are available:\n\n* Source list – by adding Documents, it enables the ability to attach Documents to stream posts directly;\n* Max file size;\n* Accept – which file types to accept.\n\n### Quote reply\n\n*As of v9.0.*\n\nBy clicking 'Quote Reply' on a stream post, it will paste quoted contents into the text field. If a part of a post is selected, only the selected part will be quoted.\n\n### Reactions\n\n*As of v9.0.*\n\nUsers can add to reactions to stream posts. A user can add only one reaction to a particular post. The author of a post is notified about a reaction. Users can view who reacted to a particular post.\n\nA user can disable notifications about reactions in preferences. If the preferences parameter *Notifications about reactions for non-followed records* is not enabled, the user won't be notified about reactions to their posts in records they do not follow.\n\nAn administrator can define which reactions are available in the system. By default, only Like is available. They can disable reactions by leaving the parameter empty.\n\n## Posts to users\n\nUsers can create posts to certain Users, to certain Teams, to all Users and to self. Access for this feature is controlled by the *Message Permission* in Roles.\n\nYou can post to Users:\n\n* from the *Stream* dashlet;\n* in the *Stream* panel on the user's detail view.\n\n## Filtering\n\nYou can filter what to show in the Stream: *All*, *Posts* or *Updates*. Filters are available in the dropdown in to top-right corner of the panel.\n\n## Global Stream\n\n*As of v8.2.*\n\nThe Global Stream is available on a separate page where users can see all Stream notes, not only related to records they follow. Users can perform search: by specific fields or by a text filter. Notes that user don't have access to are not listed.\n\nThe Global Stream can be useful when you need to search for a specific post. The full-text search is applied when using the text filter. \n\nAccess to the Global Stream is controlled by Roles.\n\nThe separate navbar Global Stream tab is available. It can be also reached from the Stream page.\n\n!!! note\n\n If a user does not have *all* access level for all entity types, there are possible scenarios leading to an empty or not complete result list being displayed. It's a server load optimization measure when it would take too much of resources to find the first records the user has access to. Consider adding some search filters in such cases.\n\n## See also\n\n* [Stream quick tour](https://app.supademo.com/demo/cmkvg6g2n2z4p12hh6xvxp6nf)\n* [Activity Stream – Keep up with changes](https://www.espocrm.com/tips/activity-stream/)\n* [Following records in EspoCRM](https://www.espocrm.com/tips/follow-records/)\n"
},
{
"path": "docs/user-guide/text-search.md",
"content": "# Text Search\n\nIn this article:\n\n* [List view text search](#list-view-text-search)\n* [Global search](#global-search)\n* [Full-text search](#full-text-search)\n\nSee also:\n\n* [Search types in EspoCRM: What you should know](https://www.espocrm.com/tips/search-types/)\n\n## List view text search\n\nOn the record list view, it's possible to perform text search.\n\nThe field list which is used in filtering can be configured under: Administration > Entity Manager > {Entity Type} > Edit > Text Filter Fields.\n\nIt's possible to use a wildcard `*`.\n\n\n\nThere is an option to force the system to use the 'contains' operator for Varchar fields by default. Parameter is available under Administration > Settings. Note that it can affect performance.\n\nTo disable previous search suggestions, uncheck the checkbox at Preferences > Misc > Disable text filter storing.\n\n## Global search\n\nThe Global Search performs search in multiple entity types simultaneously.\n\nThe list of entity types used in the Global Search can be configured under Administration > Settings > Global Search Entity List.\n\nThe field list which is used in filtering can be configured under Administration > Entity Manager > {Entity Type} > Edit > Text Filter Fields.\n\n\n\n## Full-text search\n\nFull-text search provides the ability to perform much faster and comprehensive text search. The full-text is performed at the database level.\n\nThe full-text search can be enabled for a specific entity type under Administration > Entity Manager > {Entity Type} > Edit > Full-text search.\n\nAfter enabling full-text-search, running rebuild is required. If you have many records, it's recommended to run rebuild from CLI: `php rebuild.php`.\n\nIn Global Search, the full-text search is always applied (for entity types with enabled full-text search).\n\nThe full-text search is also applied when you search in the list view. Though it can be skipped for some search queries. Yet, it's possible to force a full-text usage by prepending `ft:` to your search query.\n\nThe following operators are available:\n\n* `+` – A leading plus sign indicates that this word must be present.\n* `-` – A leading minus sign indicates that this word must not be present.\n* *no operator* – The word is optional, but the rows that contain it are rated higher.\n* `*` – The truncation (or wildcard) operator. Appended to the word to be affected.\n* `\"` – A phrase enclosed within double quotes must be contained literally, as it was typed.\n\n### Minimum word length\n\nThe MySQL option `ft_min_word_len` defines a minimum word length available for full-text search. By default, it's set to `4`. You might want to set it to `3` to be able to search shorter words.\n\nIf you change this parameter in MySQL, you also need to run rebuild in Espo.\n\n### Stopwords\n\n[MySQL](https://dev.mysql.com/doc/refman/8.0/en/fulltext-stopwords.html) and [MariaDB](https://mariadb.com/docs/server/ha-and-performance/optimization-and-tuning/optimization-and-indexes/full-text-indexes/full-text-index-stopwords) have the list of stopwords that are ignored by full-text search.\n\n### Autocomplete\n\nWhen Full-text search is enabled, autocomplete in link fields may not show suggestions until you type a full word. To have suggestions work for word parts, you can enable the parameter that will append the wildcard operator automatically for autocompletion queries. Administration > Settings > Append wildcard in quick search.\n"
},
{
"path": "docs/user-guide/working-time-calendar.md",
"content": "# Working Time Calendar\n\n*As of v7.3.*\n\nThe Working Time feature allows you to define working and non-working days for users, teams, and the entire organization. It provides a weekly schedule with customizable hours per weekday, supports exceptions for special working days (such as weekends or days with adjusted hours), and allows marking holidays or leaves.\n\nFeatures:\n\n* Week schedule (weekdays can have different schedule);\n* Working day exceptions (e.g. working weekends, days with a non-standard schedule);\n* Non-working day exceptions (leaves, holidays, etc.).\n\nAdmin users and regular users who have access to the Working Time Calendar scope can manage Working Time Calendars.\n\nWorking Time Calendars can be accessed under:\n\n* Calendar page > top-right dropdown menu > Working Time Calendars;\n* Administration > Working Time Calendars (in the Data panel).\n\nA working Time Calendar record can be:\n\n* Selected as a system default (Administration > System > Working Time Calendar);\n* Selected for a team – will apply to users who have that team set in the *Default Team*;\n* Selected for a specific user.\n\nA Working Time Calendar record defines:\n\n* Time zone;\n* Workday schedule (working time ranges);\n* Week schedule (what weekdays are working, every weekday can have a different schedule).\n\nA Working Time Exception record applies custom working time for a specific day range for specific users or for a whole calendar. It can define non-working days or working days with a custom time schedule.\n\n!!! note\n\n In Exceptions, the Date End is inclusive.\n\nExamples:\n\n* Holidays for a whole team. Create an Exception record related to the Working Time Calendar with the type *Non-working*.\n* A leave for a specific user (employee). Create an Exception record related to the User (through the *Users* field) with the type *Non-working*.\n* A working Saturday. Create a one-day Exception with the type *Working*.\n* A working day with a shortened time schedule. Create a one-day Exception with the type *Working*, with a custom *Schedule*.\n\nNon-working days have a different background color on the Calendar:\n\n\n\nNon-working timeslots:\n\n\n\nThe Timeline displays non-working ranges with a different background color:\n\n\n\n## Formula functions\n\nThe following formula functions are available.\n\n* `ext\\workingTime\\addWorkingDays(DATE, DAYS)` – adds working days, the result will be a date-time pointing at the beginning of the day (`00:00`) in a corresponding time zone;\n* `ext\\workingTime\\findClosestWorkingTime(DATE)` – finds the beginning of the next closest working time slot;\n* `ext\\workingTime\\getSummedWorkingHours(FROM, TO)` – get a total number of working hours between two dates;\n* `ext\\workingTime\\getWorkingDays(FROM, TO)` – get a number of working days between two dates;\n* `ext\\workingTime\\hasWorkingTime(FROM, TO)` – whether a date range contains any working time;\n* `ext\\workingTime\\isWorkingDay(DATE_OR_DATETIME)` – whether a date falls into a working day.\n\nFunctions can be applied for the default calendar, user calendar, or team calendar. An entity type ( `'User'` or `'Team'`) and an entity ID can be passed to all workingTime functions as the last two arguments. For example, `ext\\workingTime\\isWorkingDay(dateStart', 'User', assignedUserId)`.\n\n## See also\n\n* [Quick tour](https://app.supademo.com/demo/cmj9rq2v70sm3f6zpxmxq1npw)\n"
},
{
"path": "mkdocs.yml",
"content": "site_name: EspoCRM Documentation\n\nrepo_url: https://github.com/espocrm/documentation/\nedit_uri: edit/master/docs/\n\nextra_javascript: [js/extra.js]\n\nextra_css:\n - css/extra.css\n\nmarkdown_extensions:\n - admonition\n - pymdownx.details\n - pymdownx.superfences\n - mdx_truly_sane_lists\n - attr_list\n - codehilite:\n guess_lang: false\n use_pygments: true\n - toc:\n permalink: true\n toc_depth: 3\n\ntheme:\n name: material\n highlightjs: true\n features:\n - content.action.edit\n icon:\n edit: material/pencil\n palette:\n - scheme: default\n media: \"(prefers-color-scheme: light)\"\n primary: white\n accent: white\n toggle:\n icon: material/brightness-7\n name: Switch to dark mode\n - scheme: slate\n media: \"(prefers-color-scheme: dark)\"\n primary: indigo\n accent: indigo\n toggle:\n icon: material/brightness-4\n name: Switch to light mode\n\n\nnav:\n - 'Home': 'index.md'\n - 'Administration':\n - 'Server configuration':\n - 'Configuration': 'administration/server-configuration.md'\n - 'Apache': 'administration/apache-server-configuration.md'\n - 'Nginx': 'administration/nginx-server-configuration.md'\n - 'IIS': 'administration/iis-server-configuration.md'\n - 'System':\n - 'Installation':\n - 'Installation': 'administration/installation.md'\n - 'Installation by script': 'administration/installation-by-script.md'\n - 'Installation with Docker': 'administration/docker/installation.md'\n - 'Installation with Traefik': 'administration/docker/traefik.md'\n - 'Installation with Caddy': 'administration/docker/caddy.md'\n - 'Upgrading': 'administration/upgrading.md'\n - 'Extensions': 'administration/extensions.md' \n - 'Jobs': 'administration/jobs.md'\n - 'Config parameters': 'administration/config-params.md'\n - 'Log': 'administration/log.md'\n - 'Console commands': 'administration/commands.md' \n - 'WebSocket': 'administration/websocket.md' \n - 'Essentials':\n - 'Terms & naming': 'administration/terms-and-naming.md'\n - 'Troubleshooting': 'administration/troubleshooting.md'\n - 'Backup and restore': 'administration/backup-and-restore.md'\n - 'Performance tweaking': 'administration/performance-tweaking.md'\n - 'Moving to another server': 'administration/moving-to-another-server.md'\n - 'Security': 'administration/security.md'\n - 'Customization':\n - 'Entity Manager': 'administration/entity-manager.md'\n - 'Fields': 'administration/fields.md'\n - 'Layouts': 'administration/layout-manager.md'\n - 'Dynamic Logic': 'administration/dynamic-logic.md'\n - 'API Before-Save script': 'administration/api-before-save-script.md'\n - 'Users': 'administration/users-management.md'\n - 'Roles': 'administration/roles-management.md'\n - 'Email administration': 'administration/emails.md'\n - 'Formula':\n - 'Formula script': 'administration/formula.md'\n - 'Functions': 'administration/formula-functions.md'\n - 'Function reference':\n - 'general': 'administration/formula/general.md'\n - 'string': 'administration/formula/string.md'\n - 'datetime': 'administration/formula/datetime.md'\n - 'number': 'administration/formula/number.md'\n - 'entity': 'administration/formula/entity.md'\n - 'record': 'administration/formula/record.md'\n - 'env': 'administration/formula/env.md'\n - 'password': 'administration/formula/password.md'\n - 'array': 'administration/formula/array.md'\n - 'object': 'administration/formula/object.md'\n - 'language': 'administration/formula/language.md'\n - 'json': 'administration/formula/json.md'\n - 'ext': 'administration/formula/ext.md'\n - 'util': 'administration/formula/util.md'\n - 'log': 'administration/formula/log.md'\n - 'exception': 'administration/formula/exception.md'\n - 'Import': 'administration/import.md'\n - 'Portal': 'administration/portal.md'\n - 'Web-to-Lead': 'administration/web-to-lead.md'\n - 'Currency': 'administration/currency.md'\n - 'Dashboards': 'administration/dashboards.md'\n - 'Authentication':\n - '2-factor authentication': 'administration/2fa.md'\n - 'OpenID Connect': 'administration/oidc.md'\n - 'LDAP':\n - 'Authorization': 'administration/ldap-authorization.md'\n - 'Active Directory': 'administration/ldap-authorization-for-ad.md'\n - 'OpenLDAP': 'administration/ldap-authorization-for-openldap.md'\n - 'Miscellaneous':\n - 'Webhooks': 'administration/webhooks.md'\n - 'Passwords': 'administration/passwords.md'\n - 'Phone numbers': 'administration/phone-numbers.md'\n - 'Addresses': 'administration/addresses.md'\n - 'Maps': 'administration/maps.md'\n - 'B2C mode': 'administration/b2c.md'\n - 'Collaborators': 'administration/collaborators.md'\n - 'Multiple assigned users': 'administration/multiple-assigned-users.md'\n - 'File storage': 'administration/file-storage.md'\n - 'SMS sending': 'administration/sms-sending.md'\n - 'App secrets': 'administration/app-secrets.md'\n - 'User Guide':\n - 'Emails':\n - 'General guidelines': 'user-guide/emails.md'\n - 'IMAP & SMTP configuration': 'user-guide/imap-smtp-configuration.md'\n - 'Mass email': 'user-guide/mass-email.md'\n - 'Stream': 'user-guide/stream.md'\n - 'Sales management': 'user-guide/sales-management.md'\n - 'Case management': 'user-guide/case-management.md'\n - 'Activities & calendar': 'user-guide/activities-and-calendar.md'\n - 'Campaigns': 'user-guide/campaigns.md'\n - 'Mail merge': 'user-guide/mail-merge.md'\n - 'Knowledge base': 'user-guide/knowledge-base.md'\n - 'Documents': 'user-guide/documents.md'\n - 'Export': 'user-guide/export.md'\n - 'Text search': 'user-guide/text-search.md'\n - 'Working time calendar': 'user-guide/working-time-calendar.md'\n - 'Printing to PDF': 'user-guide/printing-to-pdf.md'\n - 'Miscellaneous':\n - 'Shortcut keys': 'user-guide/shortcuts.md'\n - 'Markdown syntax': 'user-guide/markdown.md'\n - 'Browser support': 'user-guide/browser-support.md'\n - 'Data privacy': 'user-guide/data-privacy.md'\n - 'Complex expressions': 'user-guide/complex-expressions.md'\n - 'Optimistic concurrency control': 'user-guide/optimistic-concurrency-control.md'\n - 'Extensions':\n - 'Advanced Pack':\n - 'Overview': 'extensions/advanced-pack/overview.md'\n - 'Reports': 'user-guide/reports.md'\n - 'Workflows': 'administration/workflows.md'\n - 'BPM':\n - 'Overview': 'administration/bpm.md'\n - 'Gateways': 'administration/bpm-gateways.md'\n - 'Events': 'administration/bpm-events.md'\n - 'Activities': 'administration/bpm-activities.md'\n - 'Miscellaneous':\n - 'Examples': 'administration/bpm-examples.md'\n - 'Signals': 'administration/bpm-signals.md'\n - 'Compensation': 'administration/bpm-compensation.md'\n - 'Formula functions': 'administration/bpm-formula.md'\n - 'Drip email campaign': 'administration/bpm-drip-email-campaign.md'\n - 'Tracking URLs': 'administration/bpm-tracking-urls.md'\n - 'Tips': 'administration/bpm-tips.md'\n - 'Configuration': 'administration/bpm-configuration.md'\n - 'Sales Pack':\n - 'Overview': 'extensions/sales-pack/overview.md'\n - 'Products': 'user-guide/products.md'\n - 'Prices': 'extensions/sales-pack/prices.md'\n - 'Sales':\n - 'Quotes': 'user-guide/quotes.md'\n - 'Sales orders': 'user-guide/sales-orders.md'\n - 'Invoices': 'user-guide/invoices.md'\n - 'Credit notes': 'extensions/sales-pack/credit-notes.md'\n - 'Delivery orders': 'extensions/sales-pack/delivery-orders.md'\n - 'Return orders': 'extensions/sales-pack/return-orders.md'\n - 'Write-offs': 'extensions/sales-pack/write-offs.md'\n - 'Subscriptions': 'extensions/sales-pack/subscriptions.md'\n - 'Purchases':\n - 'Suppliers': 'extensions/sales-pack/suppliers.md'\n - 'Purchase orders': 'extensions/sales-pack/purchase-orders.md'\n - 'Receipt orders': 'extensions/sales-pack/receipt-orders.md'\n - 'Bills': 'extensions/sales-pack/bills.md'\n - 'Bill credits': 'extensions/sales-pack/bill-credits.md'\n - 'Inventory management': 'extensions/sales-pack/inventory-management.md'\n - 'Payments': 'extensions/sales-pack/payments.md'\n - 'Taxes': 'extensions/sales-pack/taxes.md'\n - 'Tax codes': 'extensions/sales-pack/tax-codes.md'\n - 'Issuance locking': 'extensions/sales-pack/issuance-locking.md'\n - 'Multi-currency': 'extensions/sales-pack/multi-currency.md'\n - 'Reports': 'extensions/sales-pack/reports.md'\n - 'Project Management':\n - 'Projects': 'extensions/project-management/projects.md'\n - 'Meeting Scheduler':\n - 'Meeting Scheduler': 'extensions/meeting-scheduler/index.md'\n - 'Google Integration':\n - 'Setting-up': 'extensions/google-integration/setting-up.md'\n - 'Calendar': 'extensions/google-integration/calendar.md'\n - 'Contacts': 'extensions/google-integration/contacts.md'\n - 'Gmail': 'extensions/google-integration/gmail.md'\n - 'Outlook Integration':\n - 'Setting-up': 'extensions/outlook-integration/setting-up.md'\n - 'Calendar': 'extensions/outlook-integration/calendar.md'\n - 'Contacts': 'extensions/outlook-integration/contacts.md'\n - 'Email': 'extensions/outlook-integration/email.md'\n - 'VoIP Integration':\n - 'Overview': 'extensions/voip-integration/overview.md'\n - '3CX PBX': 'extensions/voip-integration/3cx-integration-setup.md'\n - 'Asterisk server': 'extensions/voip-integration/asterisk-integration-setup.md'\n - 'Twilio service' : 'extensions/voip-integration/twilio-integration-setup.md'\n - 'Starface server': 'extensions/voip-integration/starface-integration-setup.md'\n - 'Binotel service' : 'extensions/voip-integration/binotel-integration-setup.md'\n - 'IexPBX server' : 'extensions/voip-integration/iexpbx-integration-setup.md'\n - 'Docker container': 'extensions/voip-integration/docker-container.md'\n - 'Customization': 'extensions/voip-integration/customization.md'\n - 'Troubleshooting' : 'extensions/voip-integration/troubleshooting.md'\n - 'Zoom Integration':\n - 'Zoom Integration': 'extensions/zoom-integration/index.md'\n - 'Stripe Integration':\n - 'Stripe Integration': 'extensions/stripe-integration/index.md'\n - 'Export Import':\n - 'Overview': 'extensions/export-import/overview.md'\n - 'Export': 'extensions/export-import/export.md'\n - 'Import': 'extensions/export-import/import.md'\n - 'Compare': 'extensions/export-import/compare.md'\n - 'Run by code': 'extensions/export-import/run-by-code.md'\n - 'Customization': 'extensions/export-import/customization.md'\n - 'Developer':\n - 'Index': 'development/index.md'\n - 'Getting started': 'development/how-to-start.md'\n - 'Making extension package': 'development/extension-packages.md'\n - 'Modules': 'development/modules.md'\n - 'Tests': 'development/tests.md'\n - 'Translation': 'development/translation.md'\n - 'Coding rules': 'development/coding-rules.md'\n - 'Backend':\n - 'Dependency injection': 'development/di.md'\n - 'Metadata': 'development/metadata.md'\n - 'Metadata reference':\n - 'scopes': 'development/metadata/scopes.md'\n - 'entityDefs': 'development/metadata/entity-defs.md'\n - 'aclDefs': 'development/metadata/acl-defs.md'\n - 'selectDefs': 'development/metadata/select-defs.md'\n - 'recordDefs': 'development/metadata/record-defs.md'\n - 'clientDefs': 'development/metadata/client-defs.md'\n - 'entityAcl': 'development/metadata/entity-acl.md'\n - 'pdfDefs': 'development/metadata/pdf-defs.md'\n - 'logicDefs': 'development/metadata/logic-defs.md'\n - 'notificationDefs': 'development/metadata/notification-defs.md'\n - 'streamDefs': 'development/metadata/stream-defs.md'\n - 'fields': 'development/metadata/fields.md'\n - 'dashlets': 'development/metadata/dashlets.md'\n - 'authenticationMethods': 'development/metadata/authentication-methods.md'\n - 'integrations': 'development/metadata/integrations.md'\n - 'app':\n - 'acl': 'development/metadata/app-acl.md'\n - 'acl-portal': 'development/metadata/app-acl-portal.md'\n - 'actions': 'development/metadata/app-actions.md'\n - 'address-formats': 'development/metadata/app-address-formats.md'\n - 'admin-panel': 'development/metadata/app-admin-panel.md'\n - 'api': 'development/metadata/app-api.md'\n - 'app-params': 'development/metadata/app-app-params.md'\n - 'authentication': 'development/metadata/app-authentication.md'\n - 'authentication2FAMethods': 'development/metadata/app-authentication-2fa-methods.md'\n - 'cleanup': 'development/metadata/app-cleanup.md'\n - 'client': 'development/metadata/app-client.md'\n - 'clientNavbar': 'development/metadata/app-client-navbar.md'\n - 'clientIcons': 'development/metadata/app-client-icons.md'\n - 'clientRecord': 'development/metadata/app-client-record.md'\n - 'clientRoutes': 'development/metadata/app-client-routes.md'\n - 'complexExpression': 'development/metadata/app-complex-expression.md'\n - 'config': 'development/metadata/app-config.md'\n - 'consoleCommands': 'development/metadata/app-console-commands.md'\n - 'containerServices': 'development/metadata/app-container-services.md'\n - 'currency': 'development/metadata/app-currency.md'\n - 'currencyConversion': 'development/metadata/app-currency-conversion.md'\n - 'databasePlatforms': 'development/metadata/app-database-platforms.md'\n - 'dateTime': 'development/metadata/app-date-time.md'\n - 'defaultDashboardLayouts': 'development/metadata/app-default-dashboard-layouts.md'\n - 'defaultDashboardOptions': 'development/metadata/app-default-dashboard-options.md'\n - 'emailTemplate': 'development/metadata/app-email-template.md'\n - 'entityManager': 'development/metadata/app-entity-manager.md'\n - 'entityManagerParams': 'development/metadata/app-entity-manager-params.md'\n - 'entityTemplateList': 'development/metadata/app-entity-template-list.md'\n - 'entityTemplates': 'development/metadata/app-entity-templates.md'\n - 'export': 'development/metadata/app-export.md'\n - 'fieldProcessing': 'development/metadata/app-field-processing.md'\n - 'file': 'development/metadata/app-file.md'\n - 'fileStorage': 'development/metadata/app-file-storage.md'\n - 'formula': 'development/metadata/app-formula.md'\n - 'hook': 'development/metadata/app-hook.md'\n - 'image': 'development/metadata/app-image.md'\n - 'jsLibs': 'development/metadata/app-js-libs.md'\n - 'language': 'development/metadata/app-language.md'\n - 'layouts': 'development/metadata/app-layouts.md'\n - 'linkManager': 'development/metadata/app-link-manager.md'\n - 'mapProviders': 'development/metadata/app-map-providers.md'\n - 'massActions': 'development/metadata/app-mass-actions.md'\n - 'metadata': 'development/metadata/app-metadata.md'\n - 'orm': 'development/metadata/app-orm.md'\n - 'pdfEngines': 'development/metadata/app-pdf-engines.md'\n - 'popupNotifications': 'development/metadata/app-popup-notifications.md'\n - 'portalContainerServices': 'development/metadata/app-portal-container-services.md'\n - 'reactions': 'development/metadata/app-reactions.md'\n - 'rebuild': 'development/metadata/app-rebuild.md'\n - 'record': 'development/metadata/app-record.md'\n - 'recordId': 'development/metadata/app-record-id.md'\n - 'regExpPatterns': 'development/metadata/app-reg-exp-patterns.md'\n - 'relationships': 'development/metadata/app-relationships.md'\n - 'scheduledJobs': 'development/metadata/app-scheduled-jobs.md'\n - 'select': 'development/metadata/app-select.md'\n - 'smsProviders': 'development/metadata/app-sms-providers.md'\n - 'templateHelpers': 'development/metadata/app-template-helpers.md'\n - 'templates': 'development/metadata/app-templates.md'\n - 'webSocket': 'development/metadata/app-web-socket.md'\n - 'ORM': 'development/orm.md'\n - 'Select Builder': 'development/select-builder.md'\n - 'API actions': 'development/api-action.md'\n - 'Services': 'development/services.md'\n - 'Hooks': 'development/hooks.md'\n - 'ACL': 'development/acl.md'\n - 'Entry points': 'development/entry-points.md'\n - 'Miscellaneous':\n - 'Coding practices': 'development/coding-practices.md'\n - 'Autoload': 'development/autoload.md'\n - 'Entity type': 'development/custom-entity-type.md'\n - 'Container services': 'development/container-services.md'\n - 'Template helpers (PDF)': 'development/template-custom-helper.md'\n - 'Formula functions': 'development/new-function-in-formula.md'\n - 'Scheduled jobs': 'development/scheduled-job.md'\n - 'Duplicate checking': 'development/duplicate-check.md'\n - 'Database indexes': 'development/db-indexes.md'\n - 'App params': 'development/app-params.md'\n - 'Jobs': 'development/jobs.md'\n - 'Email sending': 'development/email-sending.md'\n - 'Calculated fields': 'development/calculated-fields.md'\n - 'Config parameters': 'development/custom-config-parameters.md'\n - 'Value Objects': 'development/orm-value-objects.md'\n - 'Attachments': 'development/attachments.md'\n - 'Frontend':\n - 'View': 'development/view.md'\n - 'Templates': 'development/frontend/templates.md'\n - 'Model': 'development/model.md'\n - 'Collection': 'development/collection.md'\n - 'HTML & CSS': 'development/frontend/html-css.md'\n - 'Ajax requests': 'development/frontend/ajax.md'\n - 'Controller & routing': 'development/frontend/controller.md'\n - 'Dependency injection': 'development/frontend/dependency-injection.md'\n - 'Modal dialogs': 'development/modal.md'\n - 'Confirmation dialogs': 'development/confirm-dialog.md'\n - 'Custom views': 'development/custom-views.md'\n - 'View setup handlers': 'development/frontend/view-setup-handlers.md'\n - 'Save error handlers': 'development/frontend/save-error-handlers.md'\n - 'Dynamic handler': 'development/dynamic-handler.md'\n - 'Fields':\n - 'Custom field type': 'development/custom-field-type.md'\n - 'Customizing existing fields': 'development/customize-standard-fields.md'\n - 'Miscellaneous':\n - 'Buttons & actions on record views': 'development/custom-buttons.md'\n - 'Panels on record view': 'development/frontend/record-panels.md'\n - 'Custom CSS file': 'development/custom-css.md'\n - 'Dashlets': 'development/how-to-create-a-dashlet.md'\n - 'Link-multiple field with primary record': 'development/link-multiple-with-primary.md'\n - 'Monkey patching': 'development/frontend/monkey-patching.md'\n - 'Campaigns':\n - 'Custom unsubscribe page': 'development/campaign-unsubscribe-template.md'\n - 'API':\n - 'API overview': 'development/api.md'\n - 'Endpoints':\n - 'CRUD operations': 'development/api/crud.md'\n - 'Related records': 'development/api/relationships.md'\n - 'Stream': 'development/api/stream.md'\n - 'CurrencyRate': 'development/api/currency-rate.md'\n - 'Attachment': 'development/api/attachment.md'\n - 'I18n': 'development/api/i18n.md'\n - 'Metadata': 'development/api/metadata.md'\n - 'Account': 'development/api/account.md'\n - 'Misc':\n - 'Search parameters': 'development/api-search-params.md'\n - 'Usage tutorial': 'development/api-tutorial.md'\n - 'Clients':\n - 'PHP': 'development/api-client-php.md'\n - 'JavaScript': 'development/api-client-js.md'\n - 'Python': 'development/api-client-python.md'\n - 'Rust': 'development/api-client-rust.md'\n - 'Java': 'development/api-client-java.md'\n - 'Go': 'development/api-client-go.md'\n - 'Zig': 'development/api-client-zig.md'\n"
}
]
| \n |
| \n |
| {{name}} | \n{{assignedUserName}} | \n
{{/ifMultipleOf}}{{name}} \n{{/each}}\n```\n\n!!! important\n\n The scope is changed inside an iteration block. To access parent scope attributes, use `../`.\n\nAccess the parent scope:\n\n```\n{{#each contacts}}\n Root record name: {{../name}}\n Contact name: {{name}}\n{{/each}}\n```\n\n### Lookup\n\nYou can use this helper to access object's and array's items.\n\nIn object (map):\n\n```\n{{lookup map key}}\n```\n\nIn an array:\n\n```\n{{lookup teamsIds index}}\n```\n\nLink-multiple example:\n\n```\n
{{lookup ../teamsNames this}}
\n```\n\n### Expressions\n\n* `{{object.key}}` – lookup in objects;\n* `{{array.[0]}}` – lookup in arrays;\n* `{{~anyTag}}` – remove all previous spacing;\n* `{{anyTag~}}` – remove all next spacing;\n* `{{{helper}}}` – prevent escaping;\n* `{{helper1 (helper2 arg1 arg2) arg2 arg3}}` – sub-expression passed as an argument;\n\n### Logical expressions\n\n*As of 8.4.*\n\nHelpers:\n\n* and\n* or\n* not\n\nTo be used in sub-expressions.\n\nExamples:\n\n```\n{{#if (or (equal status 'Draft') (equal status 'Active'))}}\n ...\n{{/if}}\n```\n\n```\n{{#if (and value1 value2 value3)}}\n ...\n{{/if}}\n```\n\n### Images\n\n```\n{{imageTag imageFieldNameId width=50 height=50}}\n```\n\n* *imageFieldNameId* is a name of image field, concatenated with *Id*\n* *width* and *height* can be omitted\n\nAnother legacy way to print images:\n\n```\n