{"id":21430165,"url":"https://github.com/cuba-platform/emailtemplate-addon","last_synced_at":"2025-03-16T21:44:55.296Z","repository":{"id":150932132,"uuid":"166801043","full_name":"cuba-platform/emailtemplate-addon","owner":"cuba-platform","description":"This component provides the ability to create outbound email based on generating by YARG reporting templates. Using the component, you can create, edit and delete templates, set groups for templates, and send emails.","archived":false,"fork":false,"pushed_at":"2025-02-18T12:57:25.000Z","size":1713,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-18T13:41:39.194Z","etag":null,"topics":["apache2","cuba-component","cuba-platform","email-template"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuba-platform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-21T11:15:08.000Z","updated_at":"2025-02-18T12:57:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"fc3181ae-0744-48b2-82bd-b239848ad293","html_url":"https://github.com/cuba-platform/emailtemplate-addon","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Femailtemplate-addon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Femailtemplate-addon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Femailtemplate-addon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Femailtemplate-addon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuba-platform","download_url":"https://codeload.github.com/cuba-platform/emailtemplate-addon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243940063,"owners_count":20372044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache2","cuba-component","cuba-platform","email-template"],"created_at":"2024-11-22T22:21:08.793Z","updated_at":"2025-03-16T21:44:55.264Z","avatar_url":"https://github.com/cuba-platform.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp\u003e\n    \u003ca href=\"http://www.apache.org/licenses/LICENSE-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat\" alt=\"license\" title=\"\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://travis-ci.org/cuba-platform/emailtemplate-addon\"\u003e\u003cimg src=\"https://travis-ci.org/cuba-platform/emailtemplate-addon.svg?branch=master\" alt=\"Build Status\" title=\"\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# Email Templates\n\n- [1. Overview](#Overview)\n- [2. Installation](#installation)  \n  - [2.1. From the Marketplace](#from-the-marketplace)  \n  - [2.2. By Coordinates](#by-coordinates)  \n- [3. Usage](#usage)  \n  - [3.1. Creating Email Templates](#creating-email-templates)  \n    - [3.1.1. Creating Email Template From Report](#creating-from-report)  \n    - [3.1.2. Creating Email Template From Designer](#creating-from-designer)  \n    - [3.1.3. Setting attachments](#setting-attachments)\n  - [3.2. Setting Groups](#setting-groups)\n  - [3.3. Custom Blocks](#custom-blocks)  \n  - [3.4. Sending Emails](#sending-emails)  \n- [4. Email Templates API](#api)  \n  - [4.1 Email Templates Builder](#builder)\n- [5. Predefined Roles](#roles)\n- [Release notes](https://github.com/cuba-platform/emailtemplate-addon/releases)\n\n# 1. Overview \u003ca name=\"Overview\"\u003e\u003c/a\u003e\n\nThe add-on enables creating and configuring outbound email templates containing a constant body and variable parameters. A template is created in the visual HTML designer or by using reports. The add-on provides a visual HTML editor with the extensive set of HTML elements.\n\nSending emails from templates can be set as a reaction to different events in your application. You can preset recipients, configure parameters and upload attachment files to be sent with emails.\n\nKey features:\n- Visual HTML templates builder based on [GrapesJS](https://grapesjs.com/) JavaScript library.\n- HTML [reports](https://www.cuba-platform.com/marketplace/reporting/) as a base for outbound emails body.\n- Downloading/uploading HTML code of a template.\n- User interface for configuring and managing templates.\n\n\nSee [sample application](https://github.com/cuba-platform/emailtemplate-addon-demo) using this add-on.\nSee [webinar](https://www.youtube.com/watch?v=JqRexrg4mAs) on the CUBA Platform channel.\n\n# 2. Installation \u003ca name=\"installation\"\u003e\u003c/a\u003e\n\nThe add-on can be added to your project in one of the ways described below. Installation from the Marketplace is the simplest way. The last version of the add-on compatible with the used version of the platform will be installed.\nAlso, you can install the add-on by coordinates choosing the required version of the add-on from the table.\n\nIn case you want to install the add-on by manual editing or by building from sources see the complete add-ons installation guide in [CUBA Platform documentation](https://doc.cuba-platform.com/manual-latest/manual.html#app_components_usage).\n\n## 2.1. From the Marketplace \u003ca name=\"from-the-marketplace\"\u003e\u003c/a\u003e\n\n1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the [CUBA Platform site](https://www.cuba-platform.com/download/previous-studio/).\n2. Go to *CUBA -\u003e Marketplace* in the main menu.\n\n ![marketplace](img/marketplace.png)\n\n3. Find the *Email Templates* add-on there.\n\n ![addons](img/addons.png)\n\n4. Click *Install* and apply the changes. The addon corresponding to the used platform version will be installed.\n\n## 2.2. By Сoordinates \u003ca name=\"by-coordinates\"\u003e\u003c/a\u003e\n\n1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the [CUBA Platform site](https://www.cuba-platform.com/download/previous-studio/).\n\n2. Go to *CUBA -\u003e Marketplace* in the main menu.\n\n3. Click the icon in the upper-right corner.\n\n ![by-coordinates](img/by-coordinates.png)\n\n4. Paste the add-on coordinates in the corresponding field as follows:\n\n `com.haulmont.addon.emailtemplates:yet-global:\u003cadd-on version\u003e`\n\n where `\u003cadd-on version\u003e` is compatible with the used version of the CUBA platform.\n\n | Platform Version  | Component Version |\n|-------------------|-------------------|\n| 7.2.x             | 1.4.2             |\n| 7.1.X             | 1.3.1             |\n| 7.0.X             | 1.1.3             |\n| 6.10.X            | 1.0.3             |\n\n5. Click *Install* and apply the changes. The add-on will be installed to your project.\n\n# 3. Usage \u003ca name=\"usage\"\u003e\u003c/a\u003e\n\nYou can use the following component features.\n\n## 3.1. Creating email templates \u003ca name=\"creating-email-templates\"\u003e\u003c/a\u003e\n\nThe component enables you to create, edit and remove email templates.\n\nTo open *Email template browser* press *Email templates* in the *Administration* menu.\n\n![email-template-menu](img/email-template-menu.png)\n\nThere are two ways to create email template: from report and from designer.\n\n![email-template-editor-modes](img/email-template-editor-modes.png)\n\n### 3.1.1. Creating Email Template From Report \u003ca name=\"creating-from-report\"\u003e\u003c/a\u003e\n\nThe following parameters are available for editing:\n\n- the *Name* field;\n- the *Code* field;\n- the *Group* drop-down;\n- the *Use subject from report* checkbox;\n- the *Subject* field (if *Use subject from report* unchecked);\n- the *From* field;\n- the *To* field;\n- the *Cc* field;\n- the *Bcc* field;\n- the *Report template to generate body* lookup field.\n\n![email-template-editor](img/email-template-editor.png)\n\nIf the report type is a report with an entity you can set entity for a template. In addition, you can set report parameters.\n\n![email-template-editor-entity](img/email-template-editor-entity.png)\n\nIf the report type is a report with entities you can set entities for a template. In addition, you can set report parameters.\n\n![email-template-editor-entities](img/email-template-editor-entities.png)\n\n### 3.1.2. Creating Email Template From Designer \u003ca name=\"creating-from-designer\"\u003e\u003c/a\u003e\n\nThe following parameters are available for editing:\n\n- the *Name* field;\n- the *Code* field;\n- the *Group* drop-down;\n- the *Subject* field;\n- the *From* field;\n- the *To* field;\n- the *Cc* field;\n- the *Bcc* field.\n\nThe screen contains the following elements:\n\n- the *Import HTML* button;\n- the *HTML code* button;\n- the *View HTML* button;\n- the *Export Report* button;\n- the *HTML Editor*.\n\nThis type of creating template provides the ability to use HTML editor. You can design a template with different elements and set every element,  using *Setting* panel.\n\nSee more information about using the editor in `README` [for GrapesJs HTML editor](https://github.com/cuba-platform/grapesjs-addon/blob/master/README.md).\n\n![email-template-editor-designer](img/email-template-editor-designer.png)\n\nTo add parameters and value formats go to the *Parameters and Formats* tab.\n\n![email-template-editor-designer-parameters-formats](img/email-template-editor-designer-parameters-formats.png)\n\nTo create parameters automatically from template use *Create from template* button in the *Parameters* section.\n\nSee the complete parameter guide in [CUBA Platform. Report Generator | External Report Parameters](https://doc.cuba-platform.com/reporting-latest/parameters.html).\n\nSee the complete value format guide in [CUBA Platform. Report Generator | Field Value Formats](https://doc.cuba-platform.com/reporting-latest/formatters.html).\n\n### 3.1.3. Setting attachments \u003ca name=\"setting-attachments\"\u003e\u003c/a\u003e\nYou can add or remove attachments on the *Attachments* tab for both types of templates: from report and from designer. You can attach a report or a file.\n\n![email-template-editor-attachment](img/email-template-editor-attachment.png)\n\nYou can set the following parameters for a report attachment:\n\n- *File name* - a report attachment name for an addressee;\n- an entity or entities for a report;\n- parameters from a report.\n\n![email-template-editor-attachment-report-parameters](img/email-template-editor-attachment-report-parameters.png)\n\n## 3.2. Setting Groups \u003ca name=\"setting-groups\"\u003e\u003c/a\u003e\n\nTo open group browser click *Groups* in the *Email templates* browser. The screen enables you to create, edit or remove email template groups.\n\n![email-template-group-browser](img/email-template-group-browser.png)\n\nTo create or edit the group enter the name of the group.\n\n![email-template-group-editor](img/email-template-group-editor.png)\n\nAfter setting groups, you can specify a group for a template.\n\n## 3.3. Custom Blocks \u003ca name=\"custom-blocks\"\u003e\u003c/a\u003e\n\nThe add-on enables creating custom blocks. Go *Administration -\u003e Email templates* and click the *Blocks* button.\n\nTo create a new block click the *Create* button and in the *Template Block editor* screen you can move predefined HTML elements and change them on the canvas. Or you can see and set HTML code on the *HTML* tab.\n\n![custom-blocks-editor](img/custom-blocks-editor.png)\n\nYou can put the created custom block to the predefined groups or create your own. Go *Administration -\u003e Email templates* and click the *Blocks* button and then *Groups* button.\n\nYour created custom HTML elements will appear in the *Email template* editing screen while creating an email template from designer.\n\n![from-designer-blocks](img/from-designer-blocks.png)\n\n## 3.4. Sending Emails \u003ca name=\"sending-emails\"\u003e\u003c/a\u003e\n\nTo send an email select a template in the list and click *Send*.\n\n![email-template-list](img/email-template-list.png)\n\nThe following parameters are available for editing:\n\n- the *Subject* field;\n- the *From* field;\n- the *To* field;\n- the *Cc* field;\n- the *Bcc* field.\n\nThe *To* field is required. You can select entity or entities for the report and set report parameter.\n\n![email-template-sending](img/email-template-sending.png)\n\n# 4. Email Templates API \u003ca name=\"api\"\u003e\u003c/a\u003e\n\nA developer can use the following methods from EmailTemplatesAPI:\n\n1. To create EmailInfo from a template that may contain the same reports with different parameter values:\n```java\n    EmailInfo generateEmail(EmailTemplate emailTemplate, List\u003cReportWithParams\u003e params)\n```\n2. To create EmailInfo by parameters map for all included reports:\n```java\n    EmailInfo generateEmail(EmailTemplate emailTemplate, Map\u003cString, Object\u003e params)\n```\n3. To check that the report input parameter did not change its parameter type:\n```java\n    void checkParameterTypeChanged(ReportInputParameter inputParameter, ParameterValue parameterValue)\n```\n\nThe `EmailTemplate` entity contains subject, body, and attachments. It also contains from, to, cc, bcc addresses.\n\nThe `ReportWithParams` is a wrapper class that represents a report and a map of parameters for that report.\n\nThe `ParameterValue` is a class that provides a string representation of the parameter with alias and type.\n\nThe `ReportInputParameter` is a class of Reporting component.\n\nThe `EmailInfo` is a class of CUBA `EmailService`.\n\n## 4.1. Email Templates Builder \u003ca name=\"builder\"\u003e\u003c/a\u003e\n\nEmail templates API contains builder that can create and fill `EmailTemplate` entity.\n\n`EmailTemplateBuilderImpl` is an implementation of `EmailTemplateBuilder` that provides intermediate methods for\nsetting and adding email template properties. It also contains terminal methods that can build `EmailTemplate`,\ngenerate or send `EmailInfo`.\n\nA copy of the specified `EmailTemplate` is created in the constructor. Every intermediate method fills the created copy.\n```java\n    public EmailTemplateBuilderImpl(EmailTemplate emailTemplate) {\n        this.emailTemplate = cloneTemplate(emailTemplate);\n    }\n```\nThe `build()` method creates the copy from the copy inside builder. It is necessary to save a state of the existed entity or builder.\n\nExample of using the builder:\n```java\n    EmailTemplate newTemplate = emailTemplatesAPI.buildFromTemplate(emailTemplate)\n            .setSubject(\"Test subject\")\n            .setTo(\"address@haulmont.com\")\n            .setBodyParameter(\"entity\", someEntity)\n            .setAttachmentParameters(reportsWithParams)\n            .build();\n```\n\n# 5. Predefined Roles \u003ca name=\"roles\"\u003e\u003c/a\u003e\n- **email-templates-admin** - grants access to all Email templates screens and entities.\n- **email-templates-can-send-templates** - allows user to send created email templates as emails.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Femailtemplate-addon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuba-platform%2Femailtemplate-addon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Femailtemplate-addon/lists"}