You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

177 lines
5.8 KiB

3 years ago
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @copyright 2017, Morris Jobke <hey@morrisjobke.de>
  5. *
  6. * @author Brad Rubenstein <brad@wbr.tech>
  7. * @author Joas Schilling <coding@schilljs.com>
  8. * @author Lukas Reschke <lukas@statuscode.ch>
  9. * @author Morris Jobke <hey@morrisjobke.de>
  10. * @author Roeland Jago Douma <roeland@famdouma.nl>
  11. *
  12. * @license GNU AGPL version 3 or any later version
  13. *
  14. * This program is free software: you can redistribute it and/or modify
  15. * it under the terms of the GNU Affero General Public License as
  16. * published by the Free Software Foundation, either version 3 of the
  17. * License, or (at your option) any later version.
  18. *
  19. * This program is distributed in the hope that it will be useful,
  20. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  22. * GNU Affero General Public License for more details.
  23. *
  24. * You should have received a copy of the GNU Affero General Public License
  25. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  26. *
  27. */
  28. namespace OCP\Mail;
  29. /**
  30. * Interface IEMailTemplate
  31. *
  32. * Interface to a class that allows to build HTML emails
  33. *
  34. * Example:
  35. *
  36. * <?php
  37. *
  38. * $emailTemplate = new EMailTemplate($this->defaults, $this->urlGenerator, $this->l10n);
  39. *
  40. * $emailTemplate->addHeader();
  41. * $emailTemplate->addHeading('Welcome aboard');
  42. * $emailTemplate->addBodyText('Welcome to your Nextcloud account, you can add, protect, and share your data.');
  43. *
  44. * $emailTemplate->addBodyButtonGroup(
  45. * 'Set your password', 'https://example.org/resetPassword/q1234567890qwertz',
  46. * 'Install Client', 'https://nextcloud.com/install/#install-clients'
  47. * );
  48. *
  49. * $emailTemplate->addFooter('Optional footer text');
  50. *
  51. * $htmlContent = $emailTemplate->renderHtml();
  52. * $plainContent = $emailTemplate->renderText();
  53. *
  54. * @since 12.0.0
  55. */
  56. interface IEMailTemplate {
  57. /**
  58. * Sets the subject of the email
  59. *
  60. * @param string $subject
  61. *
  62. * @since 13.0.0
  63. */
  64. public function setSubject(string $subject);
  65. /**
  66. * Adds a header to the email
  67. *
  68. * @since 12.0.0
  69. */
  70. public function addHeader();
  71. /**
  72. * Adds a heading to the email
  73. *
  74. * @param string $title
  75. * @param string|bool $plainTitle Title that is used in the plain text email
  76. * if empty the $title is used, if false none will be used
  77. *
  78. * @since 12.0.0
  79. */
  80. public function addHeading(string $title, $plainTitle = '');
  81. /**
  82. * Adds a paragraph to the body of the email
  83. *
  84. * @param string $text; Note: When $plainText falls back to this, HTML is automatically escaped in the HTML email
  85. * @param string|bool $plainText Text that is used in the plain text email
  86. * if empty the $text is used, if false none will be used
  87. *
  88. * @since 12.0.0
  89. */
  90. public function addBodyText(string $text, $plainText = '');
  91. /**
  92. * Adds a list item to the body of the email
  93. *
  94. * @param string $text; Note: When $plainText falls back to this, HTML is automatically escaped in the HTML email
  95. * @param string $metaInfo; Note: When $plainMetaInfo falls back to this, HTML is automatically escaped in the HTML email
  96. * @param string $icon Absolute path, must be 16*16 pixels
  97. * @param string|bool $plainText Text that is used in the plain text email
  98. * if empty the $text is used, if false none will be used
  99. * @param string|bool $plainMetaInfo Meta info that is used in the plain text email
  100. * if empty the $metaInfo is used, if false none will be used
  101. * @param integer plainIndent If > 0, Indent plainText by this amount.
  102. * @since 12.0.0
  103. */
  104. public function addBodyListItem(string $text, string $metaInfo = '', string $icon = '', $plainText = '', $plainMetaInfo = '', $plainIndent = 0);
  105. /**
  106. * Adds a button group of two buttons to the body of the email
  107. *
  108. * @param string $textLeft Text of left button; Note: When $plainTextLeft falls back to this, HTML is automatically escaped in the HTML email
  109. * @param string $urlLeft URL of left button
  110. * @param string $textRight Text of right button; Note: When $plainTextRight falls back to this, HTML is automatically escaped in the HTML email
  111. * @param string $urlRight URL of right button
  112. * @param string $plainTextLeft Text of left button that is used in the plain text version - if empty the $textLeft is used
  113. * @param string $plainTextRight Text of right button that is used in the plain text version - if empty the $textRight is used
  114. *
  115. * @since 12.0.0
  116. */
  117. public function addBodyButtonGroup(string $textLeft, string $urlLeft, string $textRight, string $urlRight, string $plainTextLeft = '', string $plainTextRight = '');
  118. /**
  119. * Adds a button to the body of the email
  120. *
  121. * @param string $text Text of button; Note: When $plainText falls back to this, HTML is automatically escaped in the HTML email
  122. * @param string $url URL of button
  123. * @param string $plainText Text of button in plain text version
  124. * if empty the $text is used, if false none will be used
  125. *
  126. * @since 12.0.0
  127. */
  128. public function addBodyButton(string $text, string $url, $plainText = '');
  129. /**
  130. * Adds a logo and a text to the footer. <br> in the text will be replaced by new lines in the plain text email
  131. *
  132. * @param string $text If the text is empty the default "Name - Slogan<br>This is an automatically sent email" will be used
  133. * @param string $lang Optional language to set the default footer in
  134. *
  135. * @since 12.0.0
  136. */
  137. public function addFooter(string $text = '', ?string $lang = null);
  138. /**
  139. * Returns the rendered email subject as string
  140. *
  141. * @return string
  142. *
  143. * @since 13.0.0
  144. */
  145. public function renderSubject(): string;
  146. /**
  147. * Returns the rendered HTML email as string
  148. *
  149. * @return string
  150. *
  151. * @since 12.0.0
  152. */
  153. public function renderHtml(): string;
  154. /**
  155. * Returns the rendered plain text email as string
  156. *
  157. * @return string
  158. *
  159. * @since 12.0.0
  160. */
  161. public function renderText(): string;
  162. }