From 38b5b793385d1c8e2c47a65c5a2a7eadbecf0cd7 Mon Sep 17 00:00:00 2001 From: cornernote Date: Mon, 6 Jul 2015 19:05:42 +0930 Subject: [PATCH] added panel docs --- docs/layouts.md | 20 +++-- docs/panels.md | 171 +++++++++++++++++++++++++++++++++++++++ src/Layout.php | 36 ++++----- src/Panel.php | 14 ++-- src/panels/TextPanel.php | 26 +++--- 5 files changed, 218 insertions(+), 49 deletions(-) diff --git a/docs/layouts.md b/docs/layouts.md index ebf2f7c..f15b80e 100644 --- a/docs/layouts.md +++ b/docs/layouts.md @@ -1,15 +1,14 @@ # Layouts -A layout defines a set of Regions in which Panels can be placed. In addition it allows the user to enter custom -options into the dashboard form when updating the dashboard. +A layout defines a set of Regions in which Panels can be placed. In addition it allows the user to enter custom options into the dashboard form when updating the dashboard. ## Layout Class The layout class allows you to define regions where panels can be rendered. -It also extends `yii\base\Model`, allowing you to define custom settings which will be available for the user to -configure the layout via a form when creating new dashboards. +It extends `yii\base\Model`, allowing you to define custom settings which will be available for the user to +configure the layout via a form when updating the dashboard. Place the following code into `app/dashboard/layouts/ExampleLayout.php`: @@ -20,7 +19,7 @@ namespace app\dashboard\layouts; class ExampleLayout extends \cornernote\dashboard\Layout { - public $viewPath = '@app/dashboard/views/layouts/example'; + public $viewPath = '@app/views/dashboard/layouts/example'; public $customSetting; @@ -95,7 +94,7 @@ class ExampleLayout extends \cornernote\dashboard\Layout The layout view will render the dashboard and all of it's panels in "view" mode. -Place the following code into `app/dashboard/views/layouts/example/view.php``: +Place the following code into `app/views/dashboard/layouts/example/view.php``: ```php '; ## Layout Update -The layout update will render the dashboard and all of it's panels in "update" mode. This allows the user to -drag-and-drop panels between the regions. +The layout update will render the dashboard and all of it's panels in "update" mode. This allows the user to drag-and-drop panels between the regions. -Place the following code into `app/dashboard/views/layouts/example/view.php`: +Place the following code into `app/views/dashboard/layouts/example/view.php`: ```php '; The layout form will render form elements for the custom options available to your layout. -Place the following code into `app/dashboard/views/layouts/example/form.php`: +Place the following code into `app/views/dashboard/layouts/example/form.php`: ```php [ 'dashboard' => [ 'layouts' => [ - 'example' => 'app\dashboard\layouts\Example', + 'example' => 'app\dashboard\layouts\ExampleLayout', ], ], ], diff --git a/docs/panels.md b/docs/panels.md index 1b84eaa..c9868d5 100644 --- a/docs/panels.md +++ b/docs/panels.md @@ -1,2 +1,173 @@ # Panels +A panel defines a block that will be rendered inside a layout region. In addition it allows the user to enter custom options into the panel form when updating the panel. + + +## Panel Class + +The panel class allows you to define the block code that will be rendered inside a layout region. + +It extends `yii\base\Model`, allowing you to define custom settings which will be available for the user to +configure the panel via a form when updating the panel. + +Place the following code into `app/dashboard/panels/ExamplePanel.php`: + +```php + $this->customSetting, + ]; + } + + public function renderView() + { + return Yii::$app->view->render($this->viewPath . '/view', [ + 'panel' => $this, + ]); + } + + public function renderUpdate() + { + return Yii::$app->view->render($this->viewPath . '/update', [ + 'panel' => $this, + ]); + } + + public function renderForm($form) + { + return Yii::$app->view->render($this->viewPath . '/form', [ + 'panel' => $this, + 'form' => $form, + ]); + } + +} +``` + + +## Panel View + +The layout view will render the panel in "view" mode. + +Place the following code into `app/views/dashboard/panels/example/view.php`: + +```php + + +

+ dashboardPanel->name ?> + ', + ['dashboard-panel/update', 'id' => $panel->dashboardPanel->id], + [ + 'data-toggle' => 'tooltip', + 'title' => 'Update Dashboard Panel', + ] + ) ?> + ', + ['dashboard-panel/delete', 'id' => $panel->dashboardPanel->id], + [ + 'data-confirm' => 'Are you sure to delete this dashboard panel?', + 'data-method' => 'post', + 'data-toggle' => 'tooltip', + 'title' => 'Delete Dashboard Panel', + ] + ) ?> +

+
+ formatter->asNtext($panel->text); ?> +
+``` + + +## Panel Update + +The panel update will render the panel in "update" mode. This provides a simplified panel when the user is moving the panel between regions. + +Place the following code into `app/views/dashboard/panels/example/update.php`: + +```php + + +

+ dashboardPanel->name ?> + ', ['dashboard-panel/update', 'id' => $panel->dashboardPanel->id], [ + 'data-toggle' => 'tooltip', + 'title' => Yii::t('dashboard', 'Update Dashboard Panel'), + ]) ?> + ', ['dashboard-panel/delete', 'id' => $panel->dashboardPanel->id], [ + 'data-confirm' => Yii::t('dashboard', 'Are you sure to delete this dashboard panel?'), + 'data-method' => 'post', + 'data-toggle' => 'tooltip', + 'title' => Yii::t('dashboard', 'Delete Dashboard Panel'), + ]) ?> +

+
+ dashboardPanel->options); ?> +
+``` + + +## Panel Form + +The panel form will render form elements for the custom options available to your panel. + +Place the following code into `app/views/dashboard/panels/example/form.php`: + +```php + + +field($panel, 'customSetting')->textInput() ?> +``` + + +## Configuration + +Finally you will need to add your panel to the module configuration: + +```php +$config = [ + 'modules' => [ + 'dashboard' => [ + 'panels' => [ + 'example' => 'app\dashboard\panels\ExamplePanel', + ], + ], + ], +]; +``` \ No newline at end of file diff --git a/src/Layout.php b/src/Layout.php index 0f03e53..1887cb2 100644 --- a/src/Layout.php +++ b/src/Layout.php @@ -47,51 +47,51 @@ public function afterValidate() /** * @return string */ - public function renderView() + public function getOptions() { - return ''; + return []; } /** - * @return string + * @return array */ - public function renderUpdate() + public function getRegionOpts() { - return ''; + return []; } /** - * @param ActiveForm $form - * @return string + * @param DashboardPanel[] $dashboardPanels + * @return array */ - public function renderForm($form) + public function regionPanels($dashboardPanels) { - return ''; + return []; } /** * @return string */ - public function getOptions() + public function renderView() { - return []; + return ''; } /** - * @return array + * @return string */ - public function getRegionOpts() + public function renderUpdate() { - return []; + return ''; } /** - * @param DashboardPanel[] $dashboardPanels - * @return array + * @param ActiveForm $form + * @return string */ - public function regionPanels($dashboardPanels) + public function renderForm($form) { - return []; + return ''; } } diff --git a/src/Panel.php b/src/Panel.php index 5fb0e53..cf045e6 100644 --- a/src/Panel.php +++ b/src/Panel.php @@ -46,34 +46,34 @@ public function afterValidate() /** * @return string */ - public function renderView() + public function getOptions() { - return ''; + return []; } /** * @return string */ - public function renderUpdate() + public function renderView() { return ''; } /** - * @param ActiveForm $form * @return string */ - public function renderForm($form) + public function renderUpdate() { return ''; } /** + * @param ActiveForm $form * @return string */ - public function getOptions() + public function renderForm($form) { - return []; + return ''; } } diff --git a/src/panels/TextPanel.php b/src/panels/TextPanel.php index d88041f..95f7842 100644 --- a/src/panels/TextPanel.php +++ b/src/panels/TextPanel.php @@ -35,19 +35,19 @@ public function rules() /** * @inheritdoc */ - public function renderView() + public function getOptions() { - return \Yii::$app->view->render($this->viewPath . '/view', [ - 'panel' => $this, - ]); + return [ + 'text' => $this->text, + ]; } /** * @inheritdoc */ - public function renderUpdate() + public function renderView() { - return \Yii::$app->view->render($this->viewPath . '/update', [ + return Yii::$app->view->render($this->viewPath . '/view', [ 'panel' => $this, ]); } @@ -55,22 +55,22 @@ public function renderUpdate() /** * @inheritdoc */ - public function renderForm($form) + public function renderUpdate() { - return \Yii::$app->view->render($this->viewPath . '/form', [ + return Yii::$app->view->render($this->viewPath . '/update', [ 'panel' => $this, - 'form' => $form, ]); } /** * @inheritdoc */ - public function getOptions() + public function renderForm($form) { - return [ - 'text' => $this->text, - ]; + return Yii::$app->view->render($this->viewPath . '/form', [ + 'panel' => $this, + 'form' => $form, + ]); } } \ No newline at end of file