1: <?php
 2: 
 3: namespace Charcoal\Ui\Dashboard;
 4: 
 5: // Intra-module (`charcoal-ui`) dependencies
 6: use \Charcoal\Ui\UiItemInterface;
 7: use \Charcoal\Ui\Layout\LayoutAwareInterface;
 8: 
 9: /**
10:  * Defines a dashboard.
11:  *
12:  * Dashboards are simply a collection of _widgets_, in a _layout_.
13:  *
14:  * - `layout` is a `LayoutInterface` object that can be created with a `LayoutBuilder`.
15:  * - `widgets` is a collection of any `UiItemInterface` objects.
16:  */
17: interface DashboardInterface extends UiItemInterface, LayoutAwareInterface
18: {
19:     /**
20:      * Set the dashboard's widgets.
21:      *
22:      * @param array $widgets A collection of widgets.
23:      * @return DashboardInterface Chainable
24:      */
25:     public function setWidgets(array $widgets);
26: 
27:     /**
28:      * Add a widget to the dashboard.
29:      *
30:      * @param  string                $widgetIdent The widget identifier.
31:      * @param  UiItemInterface|array $widget      The widget object or structure.
32:      * @return DashboardInterface Chainable
33:      */
34:     public function addWidget($widgetIdent, $widget);
35: 
36:     /**
37:      * Retrieve the dashboard's widgets.
38:      *
39:      * @return UiItemInterface[]|Generator
40:      */
41:     public function widgets();
42: 
43:     /**
44:      * Determine if the dashboard has any widgets.
45:      *
46:      * @return boolean
47:      */
48:     public function hasWidgets();
49: 
50:     /**
51:      * Count the number of widgets attached to the dashboard.
52:      *
53:      * @return integer
54:      */
55:     public function numWidgets();
56: }
57: