Skip to content

Commit 38b5b79

Browse files
cornernotecornernote
committed
added panel docs
1 parent 219ca99 commit 38b5b79

File tree

5 files changed

+218
-49
lines changed

5 files changed

+218
-49
lines changed

‎docs/layouts.md

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,14 @@
11
# Layouts
22

3-
A layout defines a set of Regions in which Panels can be placed. In addition it allows the user to enter custom
4-
options into the dashboard form when updating the dashboard.
3+
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.
54

65

76
## Layout Class
87

98
The layout class allows you to define regions where panels can be rendered.
109

11-
It also extends `yii\base\Model`, allowing you to define custom settings which will be available for the user to
12-
configure the layout via a form when creating new dashboards.
10+
It extends `yii\base\Model`, allowing you to define custom settings which will be available for the user to
11+
configure the layout via a form when updating the dashboard.
1312

1413
Place the following code into `app/dashboard/layouts/ExampleLayout.php`:
1514

@@ -20,7 +19,7 @@ namespace app\dashboard\layouts;
2019
class ExampleLayout extends \cornernote\dashboard\Layout
2120
{
2221

23-
public $viewPath = '@app/dashboard/views/layouts/example';
22+
public $viewPath = '@app/views/dashboard/layouts/example';
2423

2524
public $customSetting;
2625

@@ -95,7 +94,7 @@ class ExampleLayout extends \cornernote\dashboard\Layout
9594

9695
The layout view will render the dashboard and all of it's panels in "view" mode.
9796

98-
Place the following code into `app/dashboard/views/layouts/example/view.php``:
97+
Place the following code into `app/views/dashboard/layouts/example/view.php``:
9998

10099
```php
101100
<?php
@@ -121,10 +120,9 @@ echo '</div>';
121120

122121
## Layout Update
123122

124-
The layout update will render the dashboard and all of it's panels in "update" mode. This allows the user to
125-
drag-and-drop panels between the regions.
123+
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.
126124

127-
Place the following code into `app/dashboard/views/layouts/example/view.php`:
125+
Place the following code into `app/views/dashboard/layouts/example/view.php`:
128126

129127
```php
130128
<?php
@@ -181,7 +179,7 @@ echo '</div>';
181179

182180
The layout form will render form elements for the custom options available to your layout.
183181

184-
Place the following code into `app/dashboard/views/layouts/example/form.php`:
182+
Place the following code into `app/views/dashboard/layouts/example/form.php`:
185183

186184
```php
187185
<?php
@@ -205,7 +203,7 @@ $config = [
205203
'modules' => [
206204
'dashboard' => [
207205
'layouts' => [
208-
'example' => 'app\dashboard\layouts\Example',
206+
'example' => 'app\dashboard\layouts\ExampleLayout',
209207
],
210208
],
211209
],

‎docs/panels.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,173 @@
11
# Panels
22

3+
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.
4+
5+
6+
## Panel Class
7+
8+
The panel class allows you to define the block code that will be rendered inside a layout region.
9+
10+
It extends `yii\base\Model`, allowing you to define custom settings which will be available for the user to
11+
configure the panel via a form when updating the panel.
12+
13+
Place the following code into `app/dashboard/panels/ExamplePanel.php`:
14+
15+
```php
16+
<?php
17+
namespace app\dashboard\panels;
18+
19+
class ExamplePanel extends \cornernote\dashboard\Panel
20+
{
21+
22+
public $customSetting;
23+
24+
public $viewPath = '@app/views/dashboard/panels/example';
25+
26+
public function rules()
27+
{
28+
return [
29+
[['customSetting'], 'required'],
30+
];
31+
}
32+
33+
public function getOptions()
34+
{
35+
return [
36+
'customSetting' => $this->customSetting,
37+
];
38+
}
39+
40+
public function renderView()
41+
{
42+
return Yii::$app->view->render($this->viewPath . '/view', [
43+
'panel' => $this,
44+
]);
45+
}
46+
47+
public function renderUpdate()
48+
{
49+
return Yii::$app->view->render($this->viewPath . '/update', [
50+
'panel' => $this,
51+
]);
52+
}
53+
54+
public function renderForm($form)
55+
{
56+
return Yii::$app->view->render($this->viewPath . '/form', [
57+
'panel' => $this,
58+
'form' => $form,
59+
]);
60+
}
61+
62+
}
63+
```
64+
65+
66+
## Panel View
67+
68+
The layout view will render the panel in "view" mode.
69+
70+
Place the following code into `app/views/dashboard/panels/example/view.php`:
71+
72+
```php
73+
<?php
74+
/**
75+
* @var $panel \app\dashboard\panels\ExamplePanel
76+
* @var $this \yii\web\View
77+
*/
78+
?>
79+
80+
<h3>
81+
<?= $panel->dashboardPanel->name ?>
82+
<?= \yii\helpers\Html::a(
83+
'<span class="glyphicon glyphicon-pencil small"></span>',
84+
['dashboard-panel/update', 'id' => $panel->dashboardPanel->id],
85+
[
86+
'data-toggle' => 'tooltip',
87+
'title' => 'Update Dashboard Panel',
88+
]
89+
) ?>
90+
<?= \yii\helpers\Html::a(
91+
'<span class="glyphicon glyphicon-trash small"></span>',
92+
['dashboard-panel/delete', 'id' => $panel->dashboardPanel->id],
93+
[
94+
'data-confirm' => 'Are you sure to delete this dashboard panel?',
95+
'data-method' => 'post',
96+
'data-toggle' => 'tooltip',
97+
'title' => 'Delete Dashboard Panel',
98+
]
99+
) ?>
100+
</h3>
101+
<div class="well">
102+
<?= \Yii::$app->formatter->asNtext($panel->text); ?>
103+
</div>
104+
```
105+
106+
107+
## Panel Update
108+
109+
The panel update will render the panel in "update" mode. This provides a simplified panel when the user is moving the panel between regions.
110+
111+
Place the following code into `app/views/dashboard/panels/example/update.php`:
112+
113+
```php
114+
<?php
115+
/**
116+
* @var $panel \app\dashboard\panels\ExamplePanel
117+
* @var $this \yii\web\View
118+
*/
119+
?>
120+
121+
<h3>
122+
<?= $panel->dashboardPanel->name ?>
123+
<?= \yii\helpers\Html::a('<span class="glyphicon glyphicon-pencil small"></span>', ['dashboard-panel/update', 'id' => $panel->dashboardPanel->id], [
124+
'data-toggle' => 'tooltip',
125+
'title' => Yii::t('dashboard', 'Update Dashboard Panel'),
126+
]) ?>
127+
<?= \yii\helpers\Html::a('<span class="glyphicon glyphicon-trash small"></span>', ['dashboard-panel/delete', 'id' => $panel->dashboardPanel->id], [
128+
'data-confirm' => Yii::t('dashboard', 'Are you sure to delete this dashboard panel?'),
129+
'data-method' => 'post',
130+
'data-toggle' => 'tooltip',
131+
'title' => Yii::t('dashboard', 'Delete Dashboard Panel'),
132+
]) ?>
133+
</h3>
134+
<div class="well">
135+
<?php \yii\helpers\VarDumper::dump($panel->dashboardPanel->options); ?>
136+
</div>
137+
```
138+
139+
140+
## Panel Form
141+
142+
The panel form will render form elements for the custom options available to your panel.
143+
144+
Place the following code into `app/views/dashboard/panels/example/form.php`:
145+
146+
```php
147+
<?php
148+
/**
149+
* @var $panel \app\dashboard\panels\ExamplePanel
150+
* @var $this \yii\web\View
151+
* @var $form \yii\bootstrap\ActiveForm
152+
*/
153+
?>
154+
155+
<?= $form->field($panel, 'customSetting')->textInput() ?>
156+
```
157+
158+
159+
## Configuration
160+
161+
Finally you will need to add your panel to the module configuration:
162+
163+
```php
164+
$config = [
165+
'modules' => [
166+
'dashboard' => [
167+
'panels' => [
168+
'example' => 'app\dashboard\panels\ExamplePanel',
169+
],
170+
],
171+
],
172+
];
173+
```

‎src/Layout.php

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -47,51 +47,51 @@ public function afterValidate()
4747
/**
4848
* @return string
4949
*/
50-
public function renderView()
50+
public function getOptions()
5151
{
52-
return '';
52+
return [];
5353
}
5454

5555
/**
56-
* @return string
56+
* @return array
5757
*/
58-
public function renderUpdate()
58+
public function getRegionOpts()
5959
{
60-
return '';
60+
return [];
6161
}
6262

6363
/**
64-
* @param ActiveForm $form
65-
* @return string
64+
* @param DashboardPanel[] $dashboardPanels
65+
* @return array
6666
*/
67-
public function renderForm($form)
67+
public function regionPanels($dashboardPanels)
6868
{
69-
return '';
69+
return [];
7070
}
7171

7272
/**
7373
* @return string
7474
*/
75-
public function getOptions()
75+
public function renderView()
7676
{
77-
return [];
77+
return '';
7878
}
7979

8080
/**
81-
* @return array
81+
* @return string
8282
*/
83-
public function getRegionOpts()
83+
public function renderUpdate()
8484
{
85-
return [];
85+
return '';
8686
}
8787

8888
/**
89-
* @param DashboardPanel[] $dashboardPanels
90-
* @return array
89+
* @param ActiveForm $form
90+
* @return string
9191
*/
92-
public function regionPanels($dashboardPanels)
92+
public function renderForm($form)
9393
{
94-
return [];
94+
return '';
9595
}
9696

9797
}

‎src/Panel.php

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,34 +46,34 @@ public function afterValidate()
4646
/**
4747
* @return string
4848
*/
49-
public function renderView()
49+
public function getOptions()
5050
{
51-
return '';
51+
return [];
5252
}
5353

5454
/**
5555
* @return string
5656
*/
57-
public function renderUpdate()
57+
public function renderView()
5858
{
5959
return '';
6060
}
6161

6262
/**
63-
* @param ActiveForm $form
6463
* @return string
6564
*/
66-
public function renderForm($form)
65+
public function renderUpdate()
6766
{
6867
return '';
6968
}
7069

7170
/**
71+
* @param ActiveForm $form
7272
* @return string
7373
*/
74-
public function getOptions()
74+
public function renderForm($form)
7575
{
76-
return [];
76+
return '';
7777
}
7878

7979
}

0 commit comments

Comments
 (0)