DEV Community: Arnau Besora

Playing with dialogs and ng-templates

Arnau Besora — Thu, 13 Feb 2020 08:38:02 +0000

In this post, I want to explain our experience working with ng-templates inside our modal dialogs, which has been the short path that we have traveled to get here and what conclusions we draw. It really is not a significant change, it does not imply much more code lines, and maybe it helps you to improve your modal dialogs.

In one of our projects (Empresaula), we have some actions that require a modal dialog to improve the usability of our application. For example, the typical alert message: "Are you sure that you want to delete this document?". Until now, for these cases, we used a MatDialog service from Angular Material. We developed a new dialog component for each new requirement. We don't have a considerable number of different dialogs, so it wasn't a priority to improve these components. However, we decided to play with ng-templates, learn a little more about them, and develop a common dialog component to rule them all.

Requirements for our new dialog component:

We want a simple component, no logic, no complexity and easy to maintain.
We want to create different dialogs easily and quickly.
We want a component that helps us to sustain the style for all the modal dialogs.

Label + buttons array

The first approach was a component that accepted a label text for the header, and an array of buttons for the actions. When the dialog was closed, it returned a value corresponding to the clicked button. For each button we needed to define:

label: Button text.
value: The value of the response when the dialog is closed.
cssClass: The class name to know which CSS rules to apply to it (Optional)

Then inside our common component with a ngFor we rendered all the buttons. And here you have the content of our first dialog component:

<div mat-dialog-content>
  <p class="dialog-paragraph">{{ label }}</p>
</div>
<div class="dialog-actions">
  <button mat-button (click)="onCancel()" class="dialog-actions--cancel">
    {{ 'shared.users.dialog.actions.cancel' | translate }}
  </button>
  <button
    *ngFor="let button of buttons"
    mat-button
    class="dialog-actions--success"
    [ngClass]="button.cssClass"
    (click)="onConfirm(button.value)"
  >
    {{ button.label }}
  </button>
</div>

We already had our common dialog component, but it was not a right solution:

It scales poorly: What happens if some modal needs to render an input of type text? Adding a buttonType in each button will solve it, but for every new requirement, we would need to add logic to our component. Add complexity to the component is the main point that we want to avoid.
Requires a lot of code to generate buttons: To render the buttons list, it's needed to set a lot of data (label, value, cssClass, buttonType in a future, etc.). At empresaula, we have some components that can open five types of a modal dialog, each type with different buttons.
It's not useful for every case: In some dialogs, we render an entire form inside the dialog, with different steps. How is it supposed to build a form using our array buttons variable?

Is `ng-templates` the right solution?

Yes! Using ng-templates we have removed all the logic from the dialog component, we can render anything inside the dialog, and building extra common components we can maintain the style of the dialogs. Also, we have some extra advantages. Let's take a look.

Our entire dialog component now looks like this:

import { Component, Inject, TemplateRef } from '@angular/core'
import { MAT_DIALOG_DATA, MatDialogRef } from '@angular/material'

/**
 * A common component rendered as a Material dialog
 */
@Component({
  selector: 'esm-dialog',
  styleUrls: ['dialog.component.scss'],
  template: `
    <div mat-dialog-content>
      <p class="dialog-paragraph">{{ data.headerText }}</p>
      <ng-container [ngTemplateOutlet]="data.template"></ng-container>
    </div>
  `
})
export class DialogComponent<T> {
  /**
   * Initializes the component.
   *
   * @param dialogRef - A reference to the dialog opened.
   */
  constructor(
    public dialogRef: MatDialogRef<DialogComponent<T>>,
    @Inject(MAT_DIALOG_DATA)
    public data: {
      headerText: string
      template: TemplateRef<any>
      context: T
    }
  ) {}
}

An elementary component that renders a header, the content, and stores the context to manage when it's closed.

To help us to build and manage the dialog, we also developed a dialog service and a dialog factory. The factory builds the dialog, and the service manages it.

The Factory

import { Injectable } from '@angular/core'
import { MatDialog, MatDialogConfig } from '@angular/material'
import { first } from 'rxjs/operators'

// Components
import { DialogComponent } from '../components/dialog/dialog.component'

// Models
import { DialogData } from '../models/dialog-data.model'
import { DialogOptions } from '../models/dialog-options.model'

// Services
import { DialogService } from './dialog.service'

@Injectable({
  providedIn: 'root'
})
export class DialogFactoryService<T = undefined> {
  constructor(private dialog: MatDialog) {}

  open(
    dialogData: DialogData<T>,
    options: DialogOptions = { width: 500, disableClose: true }
  ): DialogService<T> {
    const dialogRef = this.dialog.open<DialogComponent<T>, DialogData<T>>(
      DialogComponent,
      {
        ...this.fetchOptions(options),
        data: dialogData
      }
    )

    dialogRef.afterClosed().pipe(first())

    return new DialogService(dialogRef)
  }

  private fetchOptions({
    width,
    disableClose
  }: DialogOptions): Pick<
    MatDialogConfig<DialogData<T>>,
    'width' | 'disableClose'
  > {
    return {
      width: `${width}px`,
      disableClose
    }
  }
}

The Service

import { TemplateRef } from '@angular/core'
import { MatDialogRef } from '@angular/material'
import { first } from 'rxjs/operators'

// Components
import { DialogComponent } from '../components/dialog/dialog.component'

type DialogRef<T> = MatDialogRef<DialogComponent<T>>

export class DialogService<T = undefined> {
  opened$ = this.dialogRef.afterOpened().pipe(first())

  constructor(private dialogRef: DialogRef<T>) {}

  get context() {
    return this.dialogRef.componentInstance.data.context
  }

  close() {
    this.dialogRef.close()
  }

  setHeaderText(headerText: string): void {
    this.dialogRef.componentInstance.data.headerText = headerText
  }

  setTemplate(template: TemplateRef<any>): void {
    this.dialogRef.componentInstance.data.template = template
  }
}

And finally, whenever we need we can create a dialog with a few lines of code.

Step 1: Define the template

<ng-template #userDialogTemplate>
  <esm-user-dialog-template
    [action]="selectedAction"
    (onDispatchAction)="dispatchAction($event)"
  ></esm-user-dialog-template>
</ng-template>

Step 2: Define the template variables, the dialog service and the dialog factory


dialog: DialogService;
@ViewChild("userDialogTemplate")
userDialogTemplate: TemplateRef<any>;

constructor(private dialogFactoryService: DialogFactoryService) {}

Step 3: Open the dialog

this.dialog = this.dialogFactoryService.open({
  headerText: 'Header text',
  template: this.userDialogTemplate
})

Generating the content using ng-templates implies that you can control the dialog component from the component that opens it.

The main difference in this approach is that the onDispatchAction is defined where the common dialog is opened, not inside the common dialog component. It seems a small difference, but it has exciting connotations.

The dialog does not even have an action to close itself, so we don't need to subscribe to the function which opens the dialog.

Additionally, by linking it with the utilities that ng-templates give us, we realized the power that our new component had. We can change the content of the modal at any time during the process. For example, we can dispatch an action from the store, change the template to show a loader while the action is processed, and when we get a response from the store we can choose if we close the dialog or we show some advice content. So we have defined two actions at dialogs service to change the header and the template when it's necessary setHeaderText and setTemplate.

// Change the header of the dialog
this.dialog.setHeaderText('New header')

// Change the content of the dialog
this.dialog.setTemplate(this.userLoadingActions)

// Finally close the dialog
const { activity } = this.dialog.context // Get context before close
this.dialog.close()

Our dialog working and changing the templates in each action.

Demo

You will find a demo project with the full code of our DialogModule

Conclusions

We keep the logic out of our common modal dialog. The control of the modal actions depends on the component that calls it.
We don't need to propagate events outside the modal dialog.
We can create any modal dialog without adding new features to our common component
We can change the content of our dialog at any time.

I hope you found this post useful. If you have any comments, questions or suggestions, tell us on Twitter!

Photo by Kyle Glenn on Unsplash

Phoenix: Integration tests at GitHub Actions

Arnau Besora — Thu, 13 Feb 2020 08:25:40 +0000

In this post, I will try to explain how to do integration tests for your Phoenix project and add them to the checks in your repository

These are the tools that we will use:

Ex_machina to create test data.
Wallaby to test your web applications by simulating realistic user interactions.
GitHub Actions to configure the environment and run the tests at GitHub.

ExMachina

The first step will be to configure your project to easily create test data. As mentioned above, we will use ex_machina. To install it follow the instructions of their repository. Once we have installed the library, let's configure it to our needs.

Factories and Factory Module

We will split factories into separate files and will import them by creating a Factory module.

Here we have the code of our Client factory.

# test/suport/factories/client.ex

defmodule OurProject.ClientFactory do
  defmacro __using__(_opts) do
    quote do
      def client_factory do
        %OurProject.Clients.Client{
          name: "Client Name",
          contact_info: "Client contact_info"
        }
      end
    end
  end
end

And then we import it in our Factory Module.

# test/support/factory.ex

defmodule OurProject.Factory do
  use ExMachina.Ecto, repo: OurProject.Repo
  use OurProject.ClientFactory
end

Once we have created our Factory module and our factories we can use them in any test importing the factory module. You can with ExMachina you can build or insert test data, the main difference is that build returns an object that is not saved at the database. For more information read the Overview section of their repository

Here is an example test that inserts a client when we need it. Calling the client_fixture function.

# test/our_project/client/some_client_test.ex

defmodule OurProject.SomeClientTest do
  use OurProject.DataCase

  import OurProject.Factory

  def client_fixture(attrs \\ %{}) do
    # `insert*` returns an inserted comment. Only works with ExMachina.Ecto
    # Associated records defined on the factory are inserted as well.
    insert(:client, attrs)
  end
    ...
end

Wallaby

We already have our data so we can start with the integration tests. Install wallaby following the instructions on their GitHub page and configure it with Chromedriver.

# config/test.exs

config :wallaby,
  driver: Wallaby.Experimental.Chrome,
  chrome: [
    headless: true
  ]

Now, we will create a FeatureCase module to configure the database, create the session and import the modules and helpers that our tests will need. Here we will import our Factory module.

# test/support/feature_case.ex

defmodule OurProject.FeatureCase do
  use ExUnit.CaseTemplate

  using do
    quote do
      use Wallaby.DSL
      import Wallaby.Query

      alias OurProject.Repo
      import Ecto
      import Ecto.Changeset
      import Ecto.Query

      #Import our Router Helpers
      import OurProject.Router.Helpers

      #Import custom helpers if we need them
      import OurProject.TestHelpers.Navigation

      #Import our ExMachina factories
      import OurProject.Factory
    end
  end

  # Connect to the test database and create the session for each test
  setup tags do
    :ok = Ecto.Adapters.SQL.Sandbox.checkout(OurProject.Repo)

    unless tags[:async] do
      Ecto.Adapters.SQL.Sandbox.mode(OurProject.Repo, {:shared, self()})
    end

    metadata = Phoenix.Ecto.SQL.Sandbox.metadata_for(OurProject.Repo, self())
    {:ok, session} = Wallaby.start_session(metadata: metadata)
    {:ok, session: session}
  end
end

Finally, we are ready to create our first test. We are going to create a test that requires fake data so we can see how to use the factories inside an integration test.

#test/integration/client/delete_client.exs

defmodule OurProject.DeleteClientTest do
  use OurProject.FeatureCase, async: false

  setup %{session: session} do
    client = insert(:client)
    {:ok, session: session, client: client}
  end

  test "remove client", %{session: session, client: client} do
    session
    |> visit("/clients", client.name)
    |> click(link(client.name))
    |> click(link("delete"))
    |> assert_has(css(".toast-message", count: 1, text: "Client successfully deleted"))
  end
end

GitHub Actions

We have our integration tests and we want to check them when we submit a pull request. With a few steps, we can configure our GitHub workflow to run the tests every time we push to the branch.

Chromedriver

We have to add Chromedriver to our CI. To do it we will use an action created by @nanasses. Here you can read the documentation.

# .github/workflows/ci.yml

- uses: nanasess/setup-chromedriver@master

Compile our project

We have to get the dependencies, compile the project and run the migrations.

# .github/workflows/ci.yml

- name: Install Dependencies
  run: mix deps.get
- run: mix compile
- run: mix ecto.migrate

Compile our assets

In order to have our javascript compiled it's needed to compile our assets.

# .github/workflows/ci.yml

- run: npm install
  working-directory: ./assets
- run: npm run deploy --prefix ./assets

Run the tests

And finally, run the tests.

# .github/workflows/ci.yml

- run: mix test --trace

Overview

There is our entire ci.yml file.

name: Continuous Integration
on: [push]

# This workflow will build and test a Phoenix application that uses
# PostgreSQL as a database. Will also cache dependencies and build
# artifacts to speed up the build.
jobs:
  test:
    env:
      MIX_ENV: ci
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
    runs-on: ubuntu-latest

    services:
      db:
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: postgres
        image: postgres:11
        ports: ['5432:5432']
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v1.0.0
      - name: Recover dependency cache
        uses: actions/cache@v1
        id: deps_cache
        with:
          path: deps
          key: ${{ runner.OS }}-deps-${{ hashFiles('**/mix.lock') }}
          restore-keys: |
            ${{ runner.OS }}-deps-${{ env.cache-name }}-
            ${{ runner.OS }}-deps-
            ${{ runner.OS }}-
      - name: Recover build cache
        uses: actions/cache@v1
        with:
          path: _build
          key: ${{ runner.OS }}-build-${{ env.cache-name }}
          restore-keys: |
            ${{ runner.OS }}-build-
            ${{ runner.OS }}-
      - uses: actions/setup-elixir@v1.0.0
        with:
          otp-version: 22.x
          elixir-version: 1.9.x
      - uses: nanasess/setup-chromedriver@master
      - name: Install Dependencies
        run: mix deps.get
      - run: mix compile
      - run: mix ecto.migrate
      - run: npm install
        working-directory: ./assets
      - run: npm run deploy --prefix ./assets
      - run: mix test --trace

That's it

We have our tests created and running on GitHub. If you are interested in GitHub Actions, at Codegram we have a repository with GitHub Actions workflows that can be useful to you.