1
0

WidgetTemplate.php 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * Nextcloud - Dashboard App
  5. *
  6. * This file is licensed under the Affero General Public License version 3 or
  7. * later. See the COPYING file.
  8. *
  9. * @author Maxence Lange <maxence@artificial-owl.com>
  10. * @copyright 2018, Maxence Lange <maxence@artificial-owl.com>
  11. * @license GNU AGPL version 3 or any later version
  12. *
  13. * This program is free software: you can redistribute it and/or modify
  14. * it under the terms of the GNU Affero General Public License as
  15. * published by the Free Software Foundation, either version 3 of the
  16. * License, or (at your option) any later version.
  17. *
  18. * This program is distributed in the hope that it will be useful,
  19. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  21. * GNU Affero General Public License for more details.
  22. *
  23. * You should have received a copy of the GNU Affero General Public License
  24. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  25. *
  26. */
  27. namespace OCP\Dashboard\Model;
  28. use JsonSerializable;
  29. /**
  30. * Interface WidgetTemplate
  31. *
  32. * A widget must create an WidgetTemplate object and returns it in the
  33. * IDashboardWidget::getWidgetTemplate method.
  34. *
  35. * @see IDashboardWidget::getWidgetTemplate
  36. *
  37. * @since 15.0.0
  38. *
  39. * @package OCP\Dashboard\Model
  40. */
  41. final class WidgetTemplate implements JsonSerializable {
  42. /** @var string */
  43. private $icon = '';
  44. /** @var array */
  45. private $css = [];
  46. /** @var array */
  47. private $js = [];
  48. /** @var string */
  49. private $content = '';
  50. /** @var string */
  51. private $function = '';
  52. /** @var WidgetSetting[] */
  53. private $settings = [];
  54. /**
  55. * Get the icon class of the widget.
  56. *
  57. * @since 15.0.0
  58. *
  59. * @return string
  60. */
  61. public function getIcon(): string {
  62. return $this->icon;
  63. }
  64. /**
  65. * Set the icon class of the widget.
  66. * This class must be defined in one of the CSS file used by the widget.
  67. *
  68. * @see addCss
  69. *
  70. * @since 15.0.0
  71. *
  72. * @param string $icon
  73. *
  74. * @return WidgetTemplate
  75. */
  76. public function setIcon(string $icon): WidgetTemplate {
  77. $this->icon = $icon;
  78. return $this;
  79. }
  80. /**
  81. * Get CSS files to be included when displaying a widget
  82. *
  83. * @since 15.0.0
  84. *
  85. * @return array
  86. */
  87. public function getCss(): array {
  88. return $this->css;
  89. }
  90. /**
  91. * path and name of CSS files
  92. *
  93. * @since 15.0.0
  94. *
  95. * @param array $css
  96. *
  97. * @return WidgetTemplate
  98. */
  99. public function setCss(array $css): WidgetTemplate {
  100. $this->css = $css;
  101. return $this;
  102. }
  103. /**
  104. * Add a CSS file to be included when displaying a widget.
  105. *
  106. * @since 15.0.0
  107. *
  108. * @param string $css
  109. *
  110. * @return WidgetTemplate
  111. */
  112. public function addCss(string $css): WidgetTemplate {
  113. $this->css[] = $css;
  114. return $this;
  115. }
  116. /**
  117. * Get JS files to be included when loading a widget
  118. *
  119. * @since 15.0.0
  120. *
  121. * @return array
  122. */
  123. public function getJs(): array {
  124. return $this->js;
  125. }
  126. /**
  127. * Set an array of JS files to be included when loading a widget.
  128. *
  129. * @since 15.0.0
  130. *
  131. * @param array $js
  132. *
  133. * @return WidgetTemplate
  134. */
  135. public function setJs(array $js): WidgetTemplate {
  136. $this->js = $js;
  137. return $this;
  138. }
  139. /**
  140. * Add a JS file to be included when loading a widget.
  141. *
  142. * @since 15.0.0
  143. *
  144. * @param string $js
  145. *
  146. * @return WidgetTemplate
  147. */
  148. public function addJs(string $js): WidgetTemplate {
  149. $this->js[] = $js;
  150. return $this;
  151. }
  152. /**
  153. * Get the HTML file that contains the content of the widget.
  154. *
  155. * @since 15.0.0
  156. *
  157. * @return string
  158. */
  159. public function getContent(): string {
  160. return $this->content;
  161. }
  162. /**
  163. * Set the HTML file that contains the content of the widget.
  164. *
  165. * @since 15.0.0
  166. *
  167. * @param string $content
  168. *
  169. * @return WidgetTemplate
  170. */
  171. public function setContent(string $content): WidgetTemplate {
  172. $this->content = $content;
  173. return $this;
  174. }
  175. /**
  176. * Get the JS function to be called when loading the widget.
  177. *
  178. * @since 15.0.0
  179. *
  180. * @return string
  181. */
  182. public function getInitFunction(): string {
  183. return $this->function;
  184. }
  185. /**
  186. * JavaScript function to be called when loading the widget on the
  187. * dashboard
  188. *
  189. * @since 15.0.0
  190. *
  191. * @param string $function
  192. *
  193. * @return WidgetTemplate
  194. */
  195. public function setInitFunction(string $function): WidgetTemplate {
  196. $this->function = $function;
  197. return $this;
  198. }
  199. /**
  200. * Get all WidgetSetting defined for the widget.
  201. *
  202. * @see WidgetSetting
  203. *
  204. * @since 15.0.0
  205. *
  206. * @return WidgetSetting[]
  207. */
  208. public function getSettings(): array {
  209. return $this->settings;
  210. }
  211. /**
  212. * Define all WidgetSetting for the widget.
  213. *
  214. * @since 15.0.0
  215. *
  216. * @see WidgetSetting
  217. *
  218. * @param WidgetSetting[] $settings
  219. *
  220. * @return WidgetTemplate
  221. */
  222. public function setSettings(array $settings): WidgetTemplate {
  223. $this->settings = $settings;
  224. return $this;
  225. }
  226. /**
  227. * Add a WidgetSetting.
  228. *
  229. * @see WidgetSetting
  230. *
  231. * @since 15.0.0
  232. *
  233. * @param WidgetSetting $setting
  234. *
  235. * @return WidgetTemplate
  236. */
  237. public function addSetting(WidgetSetting $setting): WidgetTemplate {
  238. $this->settings[] = $setting;
  239. return $this;
  240. }
  241. /**
  242. * Get a WidgetSetting by its name
  243. *
  244. * @see WidgetSetting::setName
  245. *
  246. * @since 15.0.0
  247. *
  248. * @param string $key
  249. *
  250. * @return WidgetSetting
  251. */
  252. public function getSetting(string $key): WidgetSetting {
  253. if (!array_key_exists($key, $this->settings)) {
  254. return null;
  255. }
  256. return $this->settings[$key];
  257. }
  258. /**
  259. * @since 15.0.0
  260. *
  261. * @return array
  262. */
  263. public function jsonSerialize() {
  264. return [
  265. 'icon' => $this->getIcon(),
  266. 'css' => $this->getCss(),
  267. 'js' => $this->getJs(),
  268. 'content' => $this->getContent(),
  269. 'function' => $this->getInitFunction(),
  270. 'settings' => $this->getSettings()
  271. ];
  272. }
  273. }