Skip to content

Commit

Permalink
guide
Browse files Browse the repository at this point in the history
  • Loading branch information
nadar committed Jul 29, 2021
1 parent f29e213 commit 78cc3ba
Show file tree
Hide file tree
Showing 5 changed files with 38 additions and 36 deletions.
2 changes: 1 addition & 1 deletion docs/guide/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@
+ [Forms in Blocks](lesson-blockform.md)
+ [Image slider Block](lesson-imagesliderblock.md)
+ [Admin and Frontend module](lesson-module.md)
+ [Create an ActiveWindow](lesson-activewindow.md)
+ [Create an Active Window](lesson-activewindow.md)
+ [Custom Angular Controller and Admin View](lesson-admin-custom-angular-view.md)
+ Developers
+ [Create Package (ext/module)](luya-package-dev.md)
Expand Down
36 changes: 18 additions & 18 deletions docs/guide/lesson-activewindow.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
# How to create a LUYA ActiveWindow
# How to create a LUYA Active Window

In this lesson we are going to add a special email function to the [address book](https://github.com/luyadev/luya-module-addressbook) which we have created in the [previous lesson](https://github.com/luyadev/luya/blob/master/docs/guide/lesson-module.md). We will extend the original CRUD view for the contact group list in the CMS with another button. This button will open a window overlay which will give us the possibility to freely add custom actions and views. In our case, we want to add the feature to send all contacts in the group list an email.

We will learn how to add and integrate an [ActiveWindow](https://luya.io/guide/ngrest-activewindow) to an existing LUYA module.
We will learn how to add and integrate an [Active Window](https://luya.io/guide/ngrest-activewindow) to an existing LUYA module.

## Creating the ActiveWindow
## Creating the Active Window

As in the previous examples we will use a LUYA code wizard to create a generic base for our ActiveWindow:
As in the previous examples we will use a LUYA code wizard to create a generic base for our Active Window:

```sh
./vendor/bin/luya admin/active-window/create
```
See the GIF below:

![Creating an ActiveWindow](https://raw.githubusercontent.com/luyadev/luya/master/docs/guide/img/aws-create.gif "Creating an ActiveWindow with LUYA code wizard")
![Creating an Active Window](https://raw.githubusercontent.com/luyadev/luya/master/docs/guide/img/aws-create.gif "Creating an Active Window with LUYA code wizard")

## Adding the ActiveWindow to our group model
## Adding the Active Window to our group model

As stated in the [ActiveWindow Documentation]() we will have to add the button for opening the ActiveWindow view in the associated model file. As we want to send the emails for every group, we have to modify the `addressbook/model/Group.php` and add the function `ngRestConfig` as the declaration is missing in our case:
As stated in the [Active Window Documentation]() we will have to add the button for opening the Active Window view in the associated model file. As we want to send the emails for every group, we have to modify the `addressbook/model/Group.php` and add the function `ngRestConfig` as the declaration is missing in our case:

```php
public function ngRestActiveWindows()
Expand All @@ -29,7 +29,7 @@ public function ngRestActiveWindows()
```

If the function is already defined, just add the `GroupEmailActiveWindow' entry as shown above.
This includes linking to the correct class definition of the ActiveWindow, adding a text and a meaningful icon for the button.
This includes linking to the correct class definition of the Active Window, adding a text and a meaningful icon for the button.

## Configuring the mail LUYA component

Expand All @@ -53,17 +53,17 @@ The next step is to actual declare our functions which are needed to send the em

## Adding the email function

Next, we will define a callback function `CallbackSendMail` in our generated ActiveWindow class in `modules/addressbook/admin/aws/GroupEmailActiveWindow` which will be called by the view later. We will define `$subject` and `$text` as input parameters which will contain the email subject and text body. Additionally we will extend the call to the *index view* by adding the contact list as a parameter to the view call. Of course, this function have to be defined before in the `modules/addressbook/models/Group` model by adding:
Next, we will define a callback function `CallbackSendMail` in our generated Active Window class in `modules/addressbook/admin/aws/GroupEmailActiveWindow` which will be called by the view later. We will define `$subject` and `$text` as input parameters which will contain the email subject and text body. Additionally we will extend the call to the *index view* by adding the contact list as a parameter to the view call. Of course, this function have to be defined before in the `modules/addressbook/models/Group` model by adding:

```php
public function getContacts()
{
return $this->hasMany(Contact::class, ["group_id" => "id"]);
}
```
Now we are able to use `$this->model->contacts` in our ActiveWindow class. It is important to note, that we can use `$this->model`, because we hooked the ActiveWindow in the *ngRestConfig* function. To fetch data it is highly advised to define additional function in the model class, like it has shown above and does not fall back to something like `Model::find()->select([...])->all()`.
Now we are able to use `$this->model->contacts` in our Active Window class. It is important to note, that we can use `$this->model`, because we hooked the Active Window in the *ngRestConfig* function. To fetch data it is highly advised to define additional function in the model class, like it has shown above and does not fall back to something like `Model::find()->select([...])->all()`.

With this said, here is the complete code snippet for the ActiveWindow class:
With this said, here is the complete code snippet for the Active Window class:

```php
<?php
Expand Down Expand Up @@ -102,15 +102,15 @@ class GroupEmailActiveWindow extends ActiveWindow
}
```

By using `sendSuccess` and `sendError` we are able to use the CMS message system and trigger the closing of the ActiveWindow. See in the next chapter how we will use a special form option for this.
By using `sendSuccess` and `sendError` we are able to use the CMS message system and trigger the closing of the Active Window. See in the next chapter how we will use a special form option for this.

Do not forget to include the used namespaces in the header.
And please note, that we have stripped the comments from the generated file to minimize the code snippet.

## Creating the ActiveWindow view
## Creating the Active Window view

The last step includes the creation of our needed `index.php` view file in `modules/addressbook/admin/views/aws/groupemail`.
One of the main purpose of the concept of an ActiveWindow is to be able to define your own views and functionality outside the CRUD view.
One of the main purpose of the concept of an Active Window is to be able to define your own views and functionality outside the CRUD view.
In our view we will include an overview of all contacts in the group, similar to the CRUD view and add an embedded email form with the email subject input field and a textarea for the actual email text:

```php
Expand Down Expand Up @@ -148,12 +148,12 @@ use luya\admin\ngrest\aw\ActiveWindowFormWidget;
<?php $form::end(); ?>
```

As you can see, we have used the {{luya\admin\ngrest\aw\ActiveWindowFormWidget}}. Besides the {{luya\admin\ngrest\aw\CallbackButtonWidget}} it is mostly what you will need to create a simple ActiveWindow form with additional functionality.
As you can see, we have used the {{luya\admin\ngrest\aw\ActiveWindowFormWidget}}. Besides the {{luya\admin\ngrest\aw\CallbackButtonWidget}} it is mostly what you will need to create a simple Active Window form with additional functionality.

We configured the widget to use our defined callback function in the ActiveWindow class and show a button label. We have also used the option to close the ActiveWindow when receiving a success message from the callback.
We configured the widget to use our defined callback function in the Active Window class and show a button label. We have also used the option to close the Active Window when receiving a success message from the callback.

## Result

After saving the view file, we have successfully added an ActiveWindow to the *addressbook* module. As you can see, it is fully integrated in our CRUD view, utilizes the already defined [bootstrap table styles](https://getbootstrap.com/docs/4.0/content/tables/) and uses the LUYA CMS notification service:
After saving the view file, we have successfully added an Active Window to the *addressbook* module. As you can see, it is fully integrated in our CRUD view, utilizes the already defined [bootstrap table styles](https://getbootstrap.com/docs/4.0/content/tables/) and uses the LUYA CMS notification service:

![Showing the ActiveWindow](https://raw.githubusercontent.com/luyadev/luya/master/docs/guide/img/aws-result.gif "Showing the ActiveWindow")
![Showing the Active Window](https://raw.githubusercontent.com/luyadev/luya/master/docs/guide/img/aws-result.gif "Showing the Active Window")
2 changes: 1 addition & 1 deletion docs/guide/luya-console.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Admin UI commands:
|`admin/storage/cleanup`|Cleanup not existing files compare file system and database.
|`admin/storage/cleanup-image-table`|Find if duplications are available in the image table (same filter and file id). If confirmed it will remove all duplications except of one, the first one created.
|`admin/storage/process-thumbnails`|Create all thumbnails for filemanager preview. Otherwise they are created on request load.
|`admin/active-window/create`|Generate a [new ActiveWindow](ngrest-activewindow.md) class file based on your configuration.
|`admin/active-window/create`|Generate a [new Active Window](ngrest-activewindow.md) class file based on your configuration.
|`admin/crud/create`|Create new [NgRest CRUD](ngrest-concept.md) with a wizzard.
|`admin/crud/model`|Generates only the [NgRestModel](ngrest-model.md). Usage `./vendor/bin/luya admin/crud/model "app\models\Customer"`

Expand Down
4 changes: 3 additions & 1 deletion docs/guide/luya-guideline.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@ This represents a guideline how words and proper nouns should be written in the

+ LUYA – always capitalized
+ ActiveRecord
+ ActiveWindow
+ Active Window
+ Active Button
+ Active Selection
+ admin UI – instead of Admin, admin module or Admin UI
+ AJAX
+ AngularJS
Expand Down
30 changes: 15 additions & 15 deletions docs/guide/ngrest-activewindow.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# NgRest ActiveWindow
# NgRest Active Window

An *NgRest ActiveWindow* is a concept to attach a modal window into a [NgRest CRUD list](ngrest-concept.md). The ActiveWindow is always bound to an **ID** of an item and is represented as a button with an icon and/or an alias, e.g. a button in the CRUD list:
An *NgRest ActiveWindow* is a concept to attach a modal window into a [NgRest CRUD list](ngrest-concept.md). The Active Window is always bound to an **ID** of an item and is represented as a button with an icon and/or an alias, e.g. a button in the CRUD list:

![button](https://raw.githubusercontent.com/luyadev/luya/master/docs/guide/img/aw_button.png "ActiveWindow button")
![button](https://raw.githubusercontent.com/luyadev/luya/master/docs/guide/img/aw_button.png "Active Window button")

An example of an ActiveWindow (Change Password) when clicked:
An example of an Active Window (Change Password) when clicked:

![overlay-window](https://raw.githubusercontent.com/luyadev/luya/master/docs/guide/img/aw_window.png "ActiveWindow overlay")
![overlay-window](https://raw.githubusercontent.com/luyadev/luya/master/docs/guide/img/aw_window.png "Active Window overlay")

## Create an ActiveWindow
## Create an Active Window

> Use the [`admin/active-window` console command](luya-console.md) to generate a new ActiveWindow.
> Use the [`admin/active-window` console command](luya-console.md) to generate a new Active Window.
A very basic example class with the name *TestActiveWindow* just renders an index and contains a callback:

Expand All @@ -33,7 +33,7 @@ class TestActiveWindow extends \luya\admin\ngrest\base\ActiveWindow
}
```

Some general information about ActiveWindows:
Some general information about Active Windows:

+ The property `$module` is required and is used to determine the path for the views files.
+ The `index()` method is required and will always be the default method which is rendered by clicking on the button in the CRUD grid list.
Expand All @@ -46,11 +46,11 @@ Working with callbacks

Calling the callbacks

+ When a ActiveWindow callback is called the lower camelcase prefix method e.g. `callbackHelloWorld` must be called as `hello-world`.
+ When a Active Window callback is called the lower camelcase prefix method e.g. `callbackHelloWorld` must be called as `hello-world`.

## Attaching the class

In order to add an ActiveWindow into your NgRest config it has to be added in the {{luya\admin\ngrest\base\NgRestModel::ngRestActive Windows()}} method. As the ActiveWindow contains the {{yii\base\BaseObject}} as extend class you can configure all public properties while the class is loading. Below, an example of how to load an ActiveWindow class and define `label` and `icon` public properties. The alias and icon properties are present in every ActiveWindow and can always be overridden.
In order to add an Active Window into your NgRest config it has to be added in the {{luya\admin\ngrest\base\NgRestModel::ngRestActive Windows()}} method. As the Active Window contains the {{yii\base\BaseObject}} as extend class you can configure all public properties while the class is loading. Below, an example of how to load an Active Window class and define `label` and `icon` public properties. The alias and icon properties are present in every Active Window and can always be overridden.

```php
public function ngRestActiveWindows()
Expand Down Expand Up @@ -78,7 +78,7 @@ This `My Windows Alias` button will only be shown for if the row `firstname` equ

### View files

To render view files you can run the method `$this->render()` inside your ActiveWindow class. The render method will lookup for PHP view file based on the base path of your `$module` property. Lets assume we run `$this->render('index')` and have defined `admin` as your `$module` property and your ActiveWindow name is `TestActiveWindow` this will try to find the view file under the path `@admin/views/aws/test/index.php`.
To render view files you can run the method `$this->render()` inside your Active Window class. The render method will lookup for PHP view file based on the base path of your `$module` property. Lets assume we run `$this->render('index')` and have defined `admin` as your `$module` property and your Active Window name is `TestActiveWindow` this will try to find the view file under the path `@admin/views/aws/test/index.php`.

## How to make a Button

Expand Down Expand Up @@ -137,7 +137,7 @@ public function callbackPostData($firstname, $lastname)

## AngularJS in view files

As the admin UI is written in AngularJS which let´s you easily create inline AngularJS controllers to interact with your ActiveWindow class.
As the admin UI is written in AngularJS which let´s you easily create inline AngularJS controllers to interact with your Active Window class.

The below view file shows an AngularJS controller which collects data from the the controller assigned into the view but uses `ng-repeat to display and render the data.

Expand All @@ -161,7 +161,7 @@ zaa.bootstrap.register('InlineController', ['$scope', function($scope) {
</div>
```
After the ActiveWindow response from the function `addToList` has received the ActiveWindow will be reloaded. This is just a very quick integration example and it does not give the user a true AngularJS experience but shows you how to deliver solutions in a very short time.
After the Active Window response from the function `addToList` has received the Active Window will be reloaded. This is just a very quick integration example and it does not give the user a true AngularJS experience but shows you how to deliver solutions in a very short time.
When working with angular you might want to trigger some of the functions of the CRUD, here a list of what functions are callable and what they do:
Expand Down Expand Up @@ -206,9 +206,9 @@ To disable permission checks, you have to set the `permissionLevel` to am empty
...
```
## Existing reusable ActiveWindows
## Existing reusable Active Windows
The admin UI of LUYA provides some basic reusable ActiveWindows which you can reuse and use out of the box. Just attach them to your NgRest config with the given configuration. Take a look at the API reference for more details in how to attach the specific ActiveWindow.
The admin UI of LUYA provides some basic reusable Active Windows which you can reuse and use out of the box. Just attach them to your NgRest config with the given configuration. Take a look at the API reference for more details in how to attach the specific Active Window.
|Class|Description
|--|--|
Expand Down

0 comments on commit 78cc3ba

Please sign in to comment.