Manuel Guilbault's Blog

Adding deep linking support to an Azure Functions-based Aurelia app

manuel.guilbault@gmail.com (Manuel Guilbault) — Thu, 07 Dec 2017 00:00:00 +0000

In this serie:

Hosting an Aurelia app on Azure
Deploying an Aurelia app on Azure using VSTS
Adding deep linking support to an Azure Functions-based Aurelia app (this post)
Adding Let’s Encrypt to an Azure Functions-based Aurelia app (coming soon)

In the previous posts of this serie, we saw a very unexpensive solution to host an Aurelia app on Azure. We also saw how to automate the deployment process of an Aurelia app on Azure using Visual Studio Team Services.

However, the current state of the solution doesn’t support deep linking if the app uses the router in push state mode. In this post, we’ll see how to fix this.

You can get the sample Aurelia app I used for this post here.

Understanding how deep linking works in push state mode

Imagine an Aurelia app that uses the router in push state mode. Imagine this app is deployed on http://www.my-awesome-app.com/. Imagine that a user accesses the app and, through the navigation menu, navigates to http://www.my-awesome-app.com/some-feature and bookmarks this URL. What normally happens when he comes back to this bookmarked URL later?

The web server receives a GET request for /some-feature.
It searches its file system (or its storage mechanism, whatever it is) for a file matching this path, but can’t find any matching file.
It returns a 200 OK response with the content of /index.html instead of a 404 Not Found.
Since the user’s browser received /index.html, the Aurelia app starts.
Since the path of the current URL is /some-feature in the user’s browser, the Aurelia router loads the component linked to this path. Everything works as expected.

At the moment, our solution doesn’t perform step 4 properly. If the proxy app receives a GET request for a path not matching a file in the Storage container, it just returns a 404 Not Found response. How can we fix that?

Replacing the proxy functions

At the moment of writing, the Azure Functions proxies don’t support this type of fallback mechanism. The only solution is to remove the proxies.json file and to create a full-fledged Azure Function that will act as a proxy and that will implement the fallback mechanism.

First, delete the azure/functions-app/proxies.json file.

Then, in your Aurelia app root directory, adjust the file structure to match the following:

azure
└── functions-app
    ├── proxy
    │   ├── function.json
    │   └── index.js
    └── host.json

Next, put the following snippet in azure/functions-app/proxy/function.json:

{
  "bindings": [
    {
      "name": "request",
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "anonymous",
      "methods": [ "get" ],
      "route": "{*path}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    }
  ]
}

This file states that the function will be triggered when the Functions app receives a GET request to any path. The function will receive the HTTP request as its request parameter, and will have the request path available as the path context variable.

In azure/functions-app/proxy/index.js, put the following code:

const http = require('http');
const path = require('path');
const { parse: parseUrl, format: formatUrl } = require('url');

module.exports = function(context, request) {
  const pathname = context.bindingData.path || '';
  const backendUrl = getBackendUrl(pathname);

  sendGetRequest(backendUrl, (error, response) => {
    if (error) {
      context.log.error(`Request to ${backendUrl} failed: ${error}`);
      context.done(null, { status: 500, body: '500 Internal Server Error' });

    } else if (response.status === 404) {
      const indexUrl = getBackendUrl('index.html');
  
      sendGetRequest(indexUrl, (error, response) => {
        if (error) {
          context.log.error(`Request to ${indexUrl} failed: ${error}`);
          context.done(null, { status: 500, body: '500 Internal Server Error' });
        } else {
          context.log.info(`Request to ${indexUrl} returned ${response.statusCode}`);
          context.done(null, response);
        }
      });

    } else {
      context.done(null, response);
    }
  });
};

function getBackendUrl(pathname) {
  const storageHostAndPath = process.env['Storage.HostAndContainer'];
  const sasToken = process.env['Storage.SasToken'];

  if (pathname === '') {
    pathname = 'index.html';
  }

  const hostAndPath = path.posix.join(storageHostAndPath, pathname);
  const rawUrl = `http://${hostAndPath}${sasToken}`;
  return parseUrl(rawUrl);
}

function sendGetRequest(uri, callback) {
  const options = {
    protocol: uri.protocol,
    hostname: uri.hostname,
    port: uri.port,
    path: uri.path,
  };
  const request = http.get(options, (response) => { toAzureFunctionsResponse(response, callback); });
  request.on('error', (e) => { callback(e, null); });
  request.end();
}

function toAzureFunctionsResponse(response, callback) {
  const azureFunctionsResponse = {
    status: response.statusCode,
    headers: response.headers,
    body: ''
  };
  response.on('error', (error) => { callback(error, null); });
  response.on('data', (chunk) => {
    azureFunctionsResponse.body += chunk;
  });
  response.on('end', () => {
    callback(null, azureFunctionsResponse);
  });
}

This file exports a function which will be executed by the Azure Functions runtime based on the triggers it is bound to in the function.json file. It first retrieves the request path from its execution context, and computes the URL to the Storage container for this path using the Storage.HostAndContainer and Storage.SasToken app settings. It then forwards the request to this URL. If the path is found on the Storage container, the response is piped back to the client. If the Storage container returns a 404 Not Found, the function then falls back to /index.html instead.

Lastly, we need to change the azure/functions-app/host.json file. By default, Azure Functions HTTP triggers will match only routes with the /api prefix. We just need to remove this default prefix:

{
  "http": {
    "routePrefix": ""
  }
}

You can now redeploy this app (this should be easy if you followed my previous post). If you give it a try, deep linking should now work properly.

Conclusion

Solving the deep linking problem was not that complicated. However, it would be pretty neat if the Azure Functions proxies supported this kind of feature (there’s already a feature request for this). In the meantime, this work around is an okay enough solution.

What’s next?

In my next post, we’ll see how to add a custom domain to our app. We’ll also see how to integrate the Let’s Encrypt Azure site extension with our Azure Functions app, so we can enable HTTPS by generating an SSL certificate for free using Let’s Encrypt.

Deploying an Aurelia app on Azure using VSTS

manuel.guilbault@gmail.com (Manuel Guilbault) — Mon, 04 Dec 2017 00:00:00 +0000

In this serie:

Hosting an Aurelia app on Azure
Deploying an Aurelia app on Azure using VSTS (this post)
Adding deep linking support to an Azure Functions-based Aurelia app
Adding Let’s Encrypt to an Azure Functions-based Aurelia app (coming soon)

In my previous post, I explained how to host an Aurelia application on Azure for very cheap.

In this post, I’ll explain how to use Visual Studio Team Services (VSTS) to easily deploy a static website or SPA application to Azure.

We’ll start by automating the creation of our Azure infrastructure using an Azure Resource Manager template, then we’ll script our Azure Functions proxy app. Lastly, we’ll create a build definition and a release definition in VSTS to automate the whole deployment process.

You’ll need a VSTS account to follow the third part of this post.

You can get the sample Aurelia app I used for this post here. Additionally, this repository contains some files used for deployment on Azure in the azure directory. More on this later.

The Azure Resource Manager template

We can imagine that this application is part of a larger system. In such a context, we probably would want to deploy this system on additional environments such as development, staging, integration, and so on. However, in the previous post, I created the Azure infrastructure manually using the Azure portal. It makes our infrastructure unreplicable, and makes creating those other environments tedious and error-prone.

Azure offers a piece of technology called Azure Resource Manager (ARM) templates. An ARM template is a JSON file that describes a set of Azure resources to deploy, along with how they depend on each other, so they can be deployed in the right order. Additionally, if a given Azure resource already exists, the ARM API is intelligent enough to simply update it so it matches the new definition. Thanks to this, a stateful resource such as a Blob storage or a SQL database won’t lose its state.

We’ll start by creating an ARM template to define the whole Azure infrastructure we manually created in the previous post.

First, we’ll create an azure directory in our Aurelia application, in which we’ll create the following azuredeploy.json file:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
  },
  "variables": {
  },
  "resources": [
  ],
  "outputs": {
  }
}

This is the standard ARM template skeleton. A template can have input parameters, and can define variables. Of course, it is pretty useless if it doesn’t define some resources. Finally, it can export some outputs.

In addition to this structure, a template can use a rich expression syntax to access resources’ properties, compute values from others, or access variables or parameters. You can get more familiar with ARM templates by checking the official documentation.

The parameters

Let’s add the following parameters:

appName: the name of the Azure Function app service. It must be globally unique, as it will be used in the web app’s domain name. This parameter will be optional, as its default value will be generated by the template.
storageAccountName: the name of the Storage account that will store the application’s files. It must be globally unique. This parameter will be optional, as its default value will be generated by the template.
storageAccountType: the replication type of Blob Storage account. This parameter will be optional, as its default value will be Standard_LRS (see locally redundant storage).
blobContainerName: the name of the Blob Storage container in which our Aurelia application files will be stored. This parameter will be optional, as its default value will be web-app-content.

To add those parameters, simply replace the parameters object with the following:

{
  "appName": {
    "type": "string",
    "defaultValue": "[uniquestring('manuelguilbault.com', 'aurelia-azure', resourceGroup().id, 'webapp')]",
    "metadata": {
      "description": "The name of your proxy webapp."
    }
  },
  "storageAccountName": {
    "type": "string",
    "defaultValue": "[uniquestring('manuelguilbault.com', 'aurelia-azure', resourceGroup().id, 'storage')]",
    "metadata": {
      "description": "The name of the Storage account."
    }
  },
  "storageAccountType": {
    "type": "string",
    "defaultValue": "Standard_LRS",
    "allowedValues": [
      "Standard_LRS",
      "Standard_GRS",
      "Standard_RAGRS"
    ],
    "metadata": {
      "description": "The type of Storage account"
    }
  },
  "blobContainerName": {
    "type": "string",
    "defaultValue": "web-app-content",
    "metadata": {
      "description": "The name of the blob container where the web app is stored."
    }
  }
}

It is important to note that the uniquestring function used to generate the default value of the appName and the storageAccountName parameters computes a deterministic value based on its arguments. Since App Service and Storage account names must be globally unique on Azure, you’ll most certainly need to change the set of arguments passed to those uniquestring calls if you want to deploy this template.

The variables

Next, let’s use those parameters and define some variables that we’ll use in the description of the resources we wish to deploy:

{
  "functionAppName": "[parameters('appName')]",
  "hostingPlanName": "[parameters('appName')]",
  "storageAccountName": "[parameters('storageAccountName')]",
  "storageAccountType": "[parameters('storageAccountType')]",
  "blobContainerName": "[parameters('blobContainerName')]"
}

Simply replace the variables object with the previous snippet in the template.

As a rule of thumb, I always assign each parameter to a variable, so the resources declarations never directly depend on parameters but only on variables. This makes the template easier to change, as you can easily add or remove parameters and change how a variable’s value is computed without having to change multiple resource declarations.

The resources

Our template will declare 3 different resources: a Storage account, a hosting plan, and a functions app. Let’s see how this looks like:

[
  {
    "type": "Microsoft.Storage/storageAccounts",
    "name": "[variables('storageAccountName')]",
    "apiVersion": "2017-06-01",
    "location": "[resourceGroup().location]",
    "kind": "Storage",
    "sku": {
      "name": "[variables('storageAccountType')]"
    }
  },
  {
    "type": "Microsoft.Web/serverfarms",
    "apiVersion": "2015-04-01",
    "name": "[variables('hostingPlanName')]",
    "location": "[resourceGroup().location]",
    "properties": {
      "name": "[variables('hostingPlanName')]",
      "computeMode": "Dynamic",
      "sku": "Dynamic"
    }
  },
  {
    "type": "Microsoft.Web/sites",
    "apiVersion": "2015-08-01",
    "name": "[variables('functionAppName')]",
    "location": "[resourceGroup().location]",
    "kind": "functionapp",
    "dependsOn": [
      "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
      "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
    ],
    "properties": {
      "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
      "siteConfig": {
        "appSettings": [
          {
            "name": "AzureWebJobsDashboard",
            "value": "[concat('DefaultEndpointsProtocol=https;AccountName=', variables('storageAccountName'), ';AccountKey=',listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), providers('Microsoft.Storage', 'storageAccounts').apiVersions[0]).keys[0].value)]"
          },
          {
            "name": "AzureWebJobsStorage",
            "value": "[concat('DefaultEndpointsProtocol=https;AccountName=', variables('storageAccountName'), ';AccountKey=', listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), providers('Microsoft.Storage', 'storageAccounts').apiVersions[0]).keys[0].value)]"
          },
          {
            "name": "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING",
            "value": "[concat('DefaultEndpointsProtocol=https;AccountName=', variables('storageAccountName'), ';AccountKey=', listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), providers('Microsoft.Storage', 'storageAccounts').apiVersions[0]).keys[0].value)]"
          },
          {
            "name": "WEBSITE_CONTENTSHARE",
            "value": "[toLower(variables('functionAppName'))]"
          },
          {
            "name": "FUNCTIONS_EXTENSION_VERSION",
            "value": "~1"
          },
          {
            "metadata": {
              "comment": "This will enable proxy functions. See https://github.com/Azure/Azure-Functions/issues/356"
            },
            "name": "ROUTING_EXTENSION_VERSION",
            "value": "~0.2"
          },
          {
            "name": "WEBSITE_NODE_DEFAULT_VERSION",
            "value": "6.5.0"
          },
          {
            "name": "Storage.HostAndContainer",
            "value": "[concat(variables('storageAccountName'), '.blob.core.windows.net/', variables('blobContainerName'))]"
          }
        ]
      }
    }
  }
]

The first object in the array describes the Storage account, and the second the hosting plan. Here, the hosting plan uses the Dynamic SKU, so the pricing is calculated based on the consumption.

The third object describes the Functions app acting as a proxy in front of the Storage container. It contains a couple of interesting details:

The dependsOn array contains the ID of the first and second resources. This is to make sure that the web app is provisioned only once the Storage account and the hosting plan have been deployed.
The appSettings array contains all the application settings that are either static values or that are known in the scope of the ARM template.

You can simply replace the value of the resources property in the template with the previous snippet.

The outputs

Depending on which parameters are specified when the template is executed, some resource names may be generated by the template. However, some of those names may be required by the release pipeline. As such, we’ll output those names, so the release pipeline can gather them up after the template is deployed and use them in further release steps:

{
  "AppService.Name": {
    "type": "string",
    "value": "[variables('functionAppName')]"
  },
  "Storage.Account.Name": {
    "type": "string",
    "value": "[variables('storageAccountName')]"
  },
  "Storage.Container.Name": {
    "type": "string",
    "value": "[variables('blobContainerName')]"
  }
}

Just replace the value of the outputs property in the template with the previous snippet.

The Azure Functions app

In the previous post, we created the Azure Functions proxy app manually through the Azure portal. In order to make our deployment automatic and replicable, we need to script it.

In your Aurelia app root directory, create the following file structure:

azure
└── functions-app
    ├── host.json
    └── proxies.json

In functions-app/host.json, just put an empty JSON object:

{}

In functions-app/proxies.json, put the following:

{
  "$schema": "http://json.schemastore.org/proxies",
  "proxies": {
      "default": {
          "matchCondition": {
              "route": "/{*path}"
          },
          "backendUri": "https://%Storage.HostAndContainer%/{path}%Storage.SasToken%"
      },
      "root": {
          "matchCondition": {
              "route": "/"
          },
          "backendUri": "https://%Storage.HostAndContainer%/index.html%Storage.SasToken%"
      }
  }
}

This will have the exact same result as what we did using the Azure portal in the previous post.

Visual Studio Team Services

Now that our ARM template and our Functions app are ready, we can start creating our build and release pipelines in VSTS.

If you’re not familiar with VSTS, let’s just say that it supports two different types of pipelines: builds and releases. A build pipeline’s job is to process some source code and to create one or more build artifacts out of it. A release pipeline’s job is to take one or more build artifacts and to deploy them to a hosting environment. In our case, this hosting environment will be Azure.

Build and release pipelines are made of tasks. A task has a set of settings, based on its type, and variables can be used in those settings. A variable is accessed using the $(variable_name) notation. You’ll see examples of this later.

For the following part, you’ll need to host your Aurelia app along with the azure directory containing the ARM template and the Functions proxy app on a Git repository. VSTS supports a couple of different providers, such as GitHub or Bitbucket. However, unless you already created a Git repository somewhere else, the simplest solution is to create a Git repository on VSTS and to push your code there.

If you never did it before, you’ll need to authorize VSTS to deploy on your Azure subscription. You can follow this blog post.

The build pipeline

A build pipeline is a sequence of tasks, which should publish one or more build artifacts.

Creating the build definition

In VSTS, go to Build and Release, then Builds, then New. You’ll be asked to choose a template. Just select Empty process.

VSTS will show the following screen, where the Process tab is selected in the left panel:

First, give a name to your build pipeline and select the Hosted agent queue. Then, click on the Get sources tab in the left panel. You’ll see the following screen:

Here, select the repository from which your code will be fetched. Selecting This project will allow you to pick a Git repository from your VSTS project (that’s what I did).

Adding the tasks

Next, we’ll add tasks to our build pipeline. Clicking the + button sitting beside the Phase 1 tab in the left panel will display the task selection screen. You can browse the available tasks, or use the search bar. After you find the task you want to add, you just have to click its Add button, and the task will appear in the left panel. You can then select the task in the left panel and its configuration form will show up in the right panel.

Here’s the list of tasks, along with their respective properties, to add to the build pipeline. The order must be respected. Any property not listed here should be left with its default value.

Task type	Property	Value
npm	Command	custom
	Command and arguments	install -g aurelia-cli
npm	Command	install
Command Line	Tool	au
	Arguments	build --env prod
Copy Files	Source Folder	$(System.DefaultWorkingDirectory)
	Contents	scripts/*/ favicon.ico index.html
	Target Folder	$(Build.ArtifactStagingDirectory)
Publish Build Artifacts	Path to publish	$(Build.ArtifactStagingDirectory)
	Artifact name	drop
Delete Files	Source Folder	$(Build.ArtifactStagingDirectory)
	Contents	**
Copy Files	Source Folder	$(System.DefaultWorkingDirectory)
	Contents	azure/*/
	Target Folder	$(Build.ArtifactStagingDirectory)
Publish Build Artifacts	Path to publish	$(Build.ArtifactStagingDirectory)
	Artifact name	azure

Once you are done adding the list of tasks, click the Save button.

To summarize, this pipeline will first install the Aurelia CLI, then will restore the application’s dependencies and transpile and bundle the app. Next, it will create two artifacts: a first one named drop, which will contain the application’s files, and a second named deploy, which will contain the ARM template, the Azure Functions app, and other scripts that our release pipeline will use.

The release pipeline

The release pipeline is linked to a source, which in our case will be build artifacts, and is made of one or more environments, which can be connected together in sequence or in parallel. Each environment is a sequence of tasks, just like a build pipeline.

Installing VSTS extensions

To make our release pipeline as simple as possible, we’ll install two extensions from the VSTS marketplace: ARM Outputs and Azure App Service: Set App settings. The first extension will add a release task that retrieves the output of an ARM template deployment and exposes them as VSTS variables, making them available to the next tasks in the sequence. The second extension will add a release task allowing to update the App settings of an App Service in Azure. Those two extensions are free and open source.

To install the extensions, just follow the two links and, for each, click Install and follow the process.

Creating the release definition

Once this is done, go to Build and Release, then Releases, click on Create release definition and select Empty process. VSTS will ask you to create a first environment:

For the sake of this post, let’s just create a single production environment, so go ahead and change the name to production.

Linking the build artifact

Next, let’s link our release pipeline to our build pipeline. Click on Add artifact and fill the fields as follows:

Here, you should select the proper VSTS project in the Project field, and your new build definition in the Source field. You can leave the other fields to their default values.

Next, let’s enable continuous deployment by clicking on the lightning icon on the top right corner of the new linked artifact and by enabling continuous deployment:

Thanks to this, every time a new build is completed successfully, the release pipeline will be triggered automatically.

Adding variables

Next, let’s create some variables to make our release pipeline easier to maintain. Select the Variables tab, then Process variables, and Add the following rows:

Name	Value
AppService.Name	The unique name for your application. This will be the subdomaine of `azurewebsites.net` used to access to your app. For example, I put `manuelguilbault-blog-post-aurelia-azure` here, so the URL to my app is `http://manuelguilbault-blog-post-aurelia-azure.azurewebsites.net`
ResourceGroup.Name	The name of the resource group on which the application’s resources will be deployed. I used `blog-post-aurelia-azure-production` here.
BuildArtifact.Name	The value of the Source alias field when you linked the build artifact. By default, this is the name of the build pipeline to which our release pipeline is linked. Here I used `post-azure-aurelia`.

Then, click Save.

Creating an environment

Lastly, let’s create the task sequence for our production environment. Go back to Pipeline and click on the 1 phase, 0 task link in the production environment box. VSTS will show a screen that is very similar to the one we used to add tasks to our build pipeline. It works the same way. Here’s the sequence of tasks, along with their properties, to add to the release pipeline:

Task type	Property	Value
Azure Resource Group Deployment	Azure subscription	Select your Azure subscription.
	Resource group	$(ResourceGroup.Name)
	Location	Select the location where you want to deploy your app. Here I used `West Europe`.
	Template	$(System.DefaultWorkingDirectory)/$(BuildArtifact.Name)/deploy/azure/azuredeploy.json
	Override template parameters	-appName $(AppService.Name)
ARM Outputs	Azure Connection Type	Azure Resource Manager
	AzureRM Subscription	Select your Azure subscription.
	Resource Group	$(ResourceGroup.Name)
	Outputs to process	Storage.Account.Name, Storage.Container.Name
Azure File Copy	Source	$(System.DefaultWorkingDirectory)/$(BuildArtifact.Name)/drop/
	Azure Connection Type	Azure Resource Manager
	Azure Subscription	Select your Azure subscription.
	Destination Type	Azure Blob
	RM Storage Account	$(Storage.Account.Name)
	Container Name	$(Storage.Container.Name)
	Additional Arguments	/SetContentType
Azure PowerShell	Azure Connection Type	Azure Resource Manager
	Azure Subscription	Select your Azure subscription.
	Script Type	Script File Path
	Script Path	$(System.DefaultWorkingDirectory)/$(BuildArtifact.Name)/deploy/azure/tools/generate-sas-token.ps1
	Script Arguments	-ResourceGroup $(ResourceGroup.Name) -StorageAccount $(Storage.Account.Name) -StorageContainer $(Storage.Container.Name) -Permission r -ExportTo Storage.SasToken
Azure App Service Deploy	Azure Subscription	Select your Azure subscription.
	App Service Name	$(AppService.Name)
	Package or folder	$(System.DefaultWorkingDirectory)/$(BuildArtifact.Name)/deploy/azure/functions-app/
	Publish using Web Deploy	Check it.
	Remove additional files at destination	Check it.
Azure App Service: Set App settings	AzureRM Subscription	Select your Azure subscription.
	Azure App Service	$(AppService.Name)
	Resource Group	$(ResourceGroup.Name)
	App Settings	Storage.SasToken=’$(Storage.SasToken)’

Once you are done adding the list of tasks, click the Save button.

To summarize, this pipeline will first provision the Azure resources using our ARM template. It will then retrieve the template’s outputs and add them as VSTS variables, so they are available to the next tasks. After this, it copies the content of the drop artifact to the Blob Storage container, then generates a long-lived SAS token so the proxy app has permission to read the Blob Storage container’s content. This generated SAS token is assigned to yet another VSTS variable. Lastly, the proxy app is deployed on the Azure Functions App Service and its app settings are updated with the Storage container SAS token. At this point, the application is fully deployed and ready to be used.

You may have noticed that the ARM template deployment task overrides the appName parameter. This is so the app’s domain name is predetermined. However in some scenarios, such as if we add a custom domain to the app, we could leave this parameter out and let the ARM template generate the app name.

Generating a Storage SAS token

You may have noticed that the fourth task expects a PowerShell script at azure/tools/generate-sas-token.ps1. This script is called with the resource group, the Storage account name, and the Storage container name as parameters. It is expected to generate a SAS token with read permissions on the Storage container and to assign this token to the Storage.SasToken VSTS variable.

The content of this script is pretty straightforward if you’re familiar with Azure Powershell:

Param(
  [string] $ResourceGroup,
  [string] $StorageAccount,
  [string] $StorageContainer,
  [string] $Permission,
  [string] $ExportTo
)

$key = Get-AzureRmStorageAccountKey -ResourceGroupName $ResourceGroup -Name $StorageAccount
$context = New-AzureStorageContext -StorageAccountName $StorageAccount -StorageAccountKey $key[0].Value
$sasToken = New-AzureStorageContainerSASToken -Name $StorageContainer -Permission $Permission -Context $context -ExpiryTime (Get-Date).AddYears(100)
Write-Host "##vso[task.setvariable variable=$ExportTo]$sasToken"

The script starts by fetching the access keys for the Storage account, then it creates a context object for the Storage account using the primary access key and creates a new SAS token, setting the expiration 100 years in the future. Lastly, it writes a VSTS command to the standard output so the SAS token is assigned to a VSTS variable whose name was passed as the ExportTo parameter.

Don’t forget to push this file to your Git repository.

Building & releasing

Once your code is pushed, and the build and release pipelines are created, you can go back to Build and Release, then Builds. If you move your mouse over the row of the build definition we created earlier, you’ll see a ... button appear. Click on it, then click on Queue new build in the contextual menu, and confirm the dialog that will show up by clicking on Queue.

Once the build is completed, you can go to Releases. A new release should start automatically if you properly enabled continuous deployment earlier. Once the release completes, you can then go to your Azure portal to make sure everything was deployed properly.

You can also fire up your favorite browser and navigate to http://your_app_name.azurewebsites.net/ to test your app running on Azure.

Conclusion

VSTS, Azure and ARM templates are amazing pieces of technology. When used together, not only is hosting an Aurelia application on Azure pretty cheap, but building and deploying it is fairly easy. Additionally, the build and release pipelines we created here can be enhanced to do much more. For example, you can add a NPM task to run unit tests in your build pipeline. Or you can add a custom domain to the proxy app during release. If your app relies on the aurelia-configuration plugin, you can update your config.json file using VSTS variables just like we do with the App Service’s app settings. There are lots of extensions to perform various tasks and, when you really can’t find what you need, the Azure PowerShell API is pretty well documented.

What’s next?

If your Aurelia application uses the router in push state mode, you may have noticed that the current solution doesn’t support deep linking. In my next post, I address this problem.

In a further post, we’ll see how to add a custom domain to our app. We’ll also see how to integrate the Let’s Encrypt Azure site extension with our Azure Functions app, so we can enable HTTPS by generating an SSL certificate for free using Let’s Encrypt.

Hosting an Aurelia app on Azure

manuel.guilbault@gmail.com (Manuel Guilbault) — Tue, 22 Aug 2017 00:00:00 +0000

In this serie:

Hosting an Aurelia app on Azure (this post)
Deploying an Aurelia app on Azure using VSTS
Adding deep linking support to an Azure Functions-based Aurelia app
Adding Let’s Encrypt to an Azure Functions-based Aurelia app (coming soon)

When it comes to hosting a static website on Azure, there are multiple possibilities, each with their own advantages and limitations.

One of those possibilities is to host the static files as a Web Application. However, this can be a pretty expensive solution, as the cheapest pricing tier supporting custom domains is a little more than 8 euros per month. Even more, if you want to support SSL, it bumps up to nearly 50 euros.

In this blog post, I’m going to show how to host an Aurelia application (or any static site, actually) on Azure for *almost* nothing. We’ll host the application’s files on a Blob storage container, then use an Azure Proxy Function, which will act as an entry point and work around some limitations of Blob storage.

For sites than have less than a million visits per month, this setup will likely cost less than a couple of euros per month. This is because Blob storage is really cheap, and Azure Functions, when using the consumption plan, come with a million of free executions per month.

You can use this sample Aurelia application if you want to follow along.

To follow this post, you’ll need an Azure subscription.

Storing files on a Blob storage container

We’ll start by creating a Blob storage container and upload a simple Aurelia application to it.

Creating the storage account

Start by navigating to your Azure portal.

Go to New > Storage > Storage account. A storage account creation form will show. Fill the following properties:

Name: the name of your Blob storage account (I used manuelguilbault here). Must be globaly unique, as it will be used in the Blob storage’s domain name.
Subscription: select your Azure subscription.
Resource group: every Azure artefact must belong to a given resource group. Either select an existing resource group or create one.
All other properties can keep their default values.

You can next click on Create.

Azure is going to work for a little while. Once your Blob storage account has been created, navigate to it (you can either search for it in the top search bar, or simply click on the success notification). You’ll see the following:

Under Services, click on Blobs, then on the button to add a Container:

Give the container the name you want (I named mine blog-post-aurelia-azure) and select Blob as the access type, so the data stored in the container is publicly visible on the web, then click OK. Your new Blob container will be created.

Uploading the app

For the next steps, you’ll need the Azure Storage Explorer installed.

Scroll left so you see your storage account, and click on the Open in Explorer button. This will launch the Azure Storage Explorer. Follow the instructions and sign in, so you see your subscription(s) in the explorer’s left panel.

In this left panel, expand your subscription, then your storage account and its Blob Containers and select your new container. Then, in the container’s tab in the center panel, use the Upload button to upload the files and folders of your Aurelia application.

If you upload the sample app provided at the beginning of this post, first make sure you au build it before hand (see its README.md file), then upload the scripts folder, and the favicon.ico and index.html files.

Accessing the files

Once the app is uploaded to Azure, let’s try to access the files from a browser. Go back to your storage account on the Azure portal and copy it’s Primary blob service endpoint, which is a URL following this pattern: https://<your_storage_account_name>.blob.core.windows.net/. In my case, the URL is https://manuelguilbault.blob.core.windows.net/.

To this URL, append the name of the Blob container, followed by /index.html (or the name of your application’s index file). In my case, the final URL looks like this: https://manuelguilbault.blob.core.windows.net/blog-post-aurelia-azure/index.html.

If you access this URL in a browser, the index.html page should load (check your browser’s developer tools to make sure). Now, if you used the sample Aurelia application provided at the beginning of this post, or if your own Aurelia app uses the router with push state, your app shouldn’t work when you navigate to this URL. This is because Aurelia expects that the application is loaded using a default document (without the index.html part), so the router can correctly match the / path to its home route.

Using Azure Proxy Functions

Accessing an Aurelia application directly from the Blob storage URL has some severe limitations:

Blob storage doesn’t support default documents. This means that accessing a directory path (in my case, https://manuelguilbault.blob.core.windows.net/blog-post-aurelia-azure/) doesn’t serve the index.html file in the directory, but will return a 404 Not Found response.
If your Aurelia application uses the router in push state mode, your app won’t work because the router expects the app to load using the default document (/).

To solve these issues, we’ll create an Azure Function app on top of the Blob storage container, that will act as a proxy for our application.

Creating an Azure Function Application

In the Azure dashboard, click on New, search for function, click on Function App, then on Create. Next, fill the form:

App name: enter the name of your Function app (I named mine manuelguilbault-blog-post-aurelia-azure). Must be globaly unique, as it will be used in the app’s domain name.
Subscription: select your Azure subscription.
Resource Group: every Azure artefact must belong to a given resource group. Either select an existing resource group or create one.
Hosting Plan: select Consumption Plan to get 1 million free executions per month (at the moment of writing).
All other properties can keep their default values.

You can next click on Create.

Enabling Proxy Functions

At the moment of writing, the Azure Proxy Functions feature is in preview. As such, it must be enabled before it can be used.

To do so, navigate to your new Function App in the Azure portal. In the Overview tab, under Configured features, click on Function app settings. This will open a new tab titled Function app settings, under which you can enable Proxies by toggling the feature to On.

Creating an Azure Proxy Function

Navigate to your Function App in the Azure portal, and click on the plus button beside the Proxies list item. This will display a creation form, which you can fill:

Name: the name of the proxy function. I named mine default.
Route template: the template of the URL path that must be matched for this proxy function to be triggered. Here, enter /{*path}. This pattern will match any path and make it available as a path variable to the backend URL.
Backend URL: the URL to which matching requests will be dispatched. Here, enter the URL of your Blob storage container, followed by the {path} variable output. For me, this was https://manuelguilbault.blob.core.windows.net/blog-post-aurelia-azure/{path}.
All other properties can keep their default values.

You can next click on Create.

This function will dispatch all requests sent to https://manuelguilbault-blog-post-aurelia-azure.azurewebsites.net/ to my Blob storage container. However, in order to support default documents, so the index.html file is loaded when accessing the / path, we need to create a second proxy function with the following properties:

Name: the name of the proxy function. I named this one root.
Route template: this proxy function should match only requests sent to the root, so enter /.
Backend URL: requests sent to the root should return the index.html file, so enter URL of your Blob storage container, followed by index.html. For me, this was https://manuelguilbault.blob.core.windows.net/blog-post-aurelia-azure/index.html.

Now click on Create.

Testing the application

We now have two proxy functions. The first one, named root, will be used to load the index.html when accessing the root of our function app’s domain, and a second one named default which will simply forward any other requests to the Blob storage container. The first one will be used to load our Aurelia application itself, and the second one will kick in when the index.html file will load our application’s bundles, CSS files or images.

To test the application, simply launch a browser tab and navigate to your function app’s URL (in my case, https://manuelguilbault-blog-post-aurelia-azure.azurewebsites.net/). The Aurelia app (or your static site) should load properly now.

Making the Blob storage container private

Since the Blob storage container is no more accessed directly, but only through a Proxy Function, you can make it private to make sure no one can access it directly from the web.

To do this, go back to your Blob storage container in your Azure portal, then click on Access policy. You should see this form come up:

Here, simply change the Public access level to Private and click Save.

Wrapping things up

With two very simple proxy functions and a Blob storage container, we now have an Aurelia app (or a static site) hosted on Azure, for a very cheap price. Additionally, since our application is accessed through a function app, we can easily add a custom domain and an SSL certificate to our app.

In my next post, I show how to use Visual Studio Team Services to automate the build and deployment of an Aurelia application to a Blob storage container. Stay tuned!

Thanks to @NatMarchand for the idea!

Multiple Aurelia apps in a single ASP.NET Core application

manuel.guilbault@gmail.com (Manuel Guilbault) — Thu, 29 Jun 2017 00:00:00 +0000

I’ve been recently working on an ASP.NET Core MVC application for a tour operator company. The application follows the standard MVC navigation principles:

You search for flights between two cities, for a specific time period;
You see a grid with the flights matching the criteria, displaying all sorts of yielding information (sold seats, capacity, pricing parameters, etc.);
You click on a single flight to go to its edition page;
You edit the flight’s capacity and pricing parameters, save, and go back to the result grid.

The customers asked if we could redesign this workflow so they could edit the pricing parameters directly in the grid. To support this demand, the grid being a simple table element rendered using a Razor template, we decided to transform it into a small Aurelia application which would render the grid and handle inline edition.

As the customer also mentionned they would like to have some other workflows redesigned as such in the future, we figured we would end up with multiple Aurelia apps in our .NET project. As such, we wanted modified the default setup of an ASP .NET Core Aurelia app to support multiple client apps.

We needed to fiddle a bit here and there, but we ended up being able to do it pretty easily. Here’s a recap of how we did it.

Setting up the project & the environment

To follow this example, you’ll need to create a .NET Core Aurelia web app:

Install the .NET Core CLI
Install the ASP.NET Spa Templates: dotnet new --install "Microsoft.AspNetCore.SpaTemplates::*"
Create a new folder for your project: mkdir dotnet-core-multiple-aurelia-apps
Move into it: cd dotnet-core-multiple-aurelia-apps
Create your ASP.NET Core Aurelia project: dotnet new aurelia

Of course, since Aurelia is involved, you’ll also need to have NodeJS installed.

Transforming a single Aurelia app project into a multiple one

Once you got your ASP.NET Core project ready, you can start transforming it into a multiple Aurelia apps project. Quickly:

rename the ClientApp directory to ClientApps;
create ClientApps/app1, where app1 is the name of your first Aurelia app;
move everything from ClientApps inside ClientApps/app1.

Next, in webpack.config.js:

replace every occurences of ClientApp with ClientApps;
change the file so it returns one configuration object per Aurelia app instead of a single one;
for each app’s configuration object:
- change the entry point’s name from 'app' to the app’s name;
- change how it resolves its modules, not from ClientApps anymore, but from the app directory inside ClientApps.

The updated webpack.config.js should look like this:

const path = require('path');
const webpack = require('webpack');
const { AureliaPlugin } = require('aurelia-webpack-plugin');
const bundleOutputDir = './wwwroot/dist';

module.exports = (env) => {
    const isDevBuild = !(env && env.prod);
    return [
        'app1',
        // Add any other Aurelia app here
    ].map(appName => ({
        stats: { modules: false },
        entry: { [appName]: 'aurelia-bootstrapper' },
        resolve: {
            extensions: ['.ts', '.js'],
            modules: [`ClientApps/${appName}`, 'node_modules'],
        },
        output: {
            path: path.resolve(bundleOutputDir),
            publicPath: '/dist/',
            filename: '[name].js'
        },
        module: {
            rules: [
                { test: /\.ts$/i, include: /ClientApps/, use: 'ts-loader?silent=true' },
                { test: /\.html$/i, use: 'html-loader' },
                { test: /\.css$/i, use: isDevBuild ? 'css-loader' : 'css-loader?minimize' },
                { test: /\.(png|jpg|jpeg|gif|svg)$/, use: 'url-loader?limit=25000' }
            ]
        },
        plugins: [
            new webpack.DefinePlugin({ IS_DEV_BUILD: JSON.stringify(isDevBuild) }),
            new webpack.DllReferencePlugin({
                context: __dirname,
                manifest: require('./wwwroot/dist/vendor-manifest.json')
            }),
            new AureliaPlugin({ aureliaApp: 'boot' })
        ].concat(isDevBuild ? [
            new webpack.SourceMapDevToolPlugin({
                filename: '[file].map', // Remove this line if you prefer inline source maps
                moduleFilenameTemplate: path.relative(bundleOutputDir, '[resourcePath]')  // Point sourcemap entries to the original file locations on disk
            })
        ] : [
            new webpack.optimize.UglifyJsPlugin()
        ])
    }));
}

This configuration will now generate one bundle for each application. For exemple, the app1 application will be bundled in the wwwroot/dist/app1.js file.

Lastly, load the proper bundles and bootstrap your Aurelia app in the proper Razor view:

<div aurelia-app="boot">Loading...</div>

@section scripts {
  <script type="text/javascript" src="~/dist/vendor.js" asp-append-version="true"></script>
  <script type="text/javascript" src="~/dist/app1.js" asp-append-version="true"></script>
}

Before you run the application, make sure to generate the vendor bundle by running webpack --config webpack.config.vendor.js.

Check this GitHub repository for a code sample.

Aurelia - feedback from the trenches

manuel.guilbault@gmail.com (Manuel Guilbault) — Thu, 08 Jun 2017 00:00:00 +0000

I’ve been using Aurelia to write multiple applications of various size for more than a year now, and I thought it might be interesting for some people to get some real-life feedback.

All in all, the framework is awesome. Aurelia’s developer experience is much better than that of other frameworks I’ve worked with (*cough* Angular *cough*). It’s flexible, extensible, and very little intrusive. You don’t have to fight it to do things the right way, whatever that right way might be.

However, entropy is constantly at work, and things can quickly become messy if you don’t pay attention. Here are a few things I’ve learnt along the way.

Type everything

If you don’t use TypeScript yet, you really should. Its type system adds tremedous value when compared to plain JS.

Why?

First, it serves as API documentation for the developers working on your code base. Let’s imagine the following JS code snippet:

export class User {
  constructor(firstName, lastName) {
    this.firstName = firstName;
    this.lastName = lastName;
  }
}

function getFullName(user) {
  return `${user.firstName} ${user.lastName}`;
}

Check the getFullName function. What is the expected type of this user parameter? Is it an object or something else? What are its properties and methods? Here, we can probably guess that it is a User instance. However, if the class and the function live in distinct files or directories, good luck with that.

Exploring such a JS code base can be a nightmare, as you would need to search for calls to getFullName to try to figure out what parameters are passed to it. The type system makes understanding existing code much easier:

function getFullName(user: User) {
  return `${user.firstName} ${user.lastName}`;
}

It is now pretty clear that the user argument is an instance of the User class. Additionally, most modern IDEs will let you to navigate to the definition of User in a single click.

The type system also prevents a whole class of bugs, where some part of the code uses something - a variable, method, function, or parameter - the wrong way - call an undefined method, or assign a value to an unexisting property, for example. In plain JS, such bugs must be covered by unit tests. In TypeScript, the transpiler will complain about such a misuse if things are properly typed. The type system can completely replace a whole category of unit tests.

Let’s imagine the following code:

export class User {
  constructor(public firstName: string, public lastName: string) {}
}

function getFullName(user: User) {
  return `${user.firstname} ${user.lastname}`;
}

This code has a bug. The getFullName function contains typos: it uses the firstname and lastname properties, while the User class defines those properties using a capital N: firstName and lastName.

Here, the error is easy to spot, as the class definition and the function sit side by side. However, if they live in distinct files, such a bug can be hard to spot without either a unit test or the TypeScript transpiler. Relying on the type system for such things is much simpler and quicker than writing unit tests.

Everything, really?

Yes. Everything. For example:

Create an interface for the route parameters passed to the activate method of route components,
Specify the type of the @bindable properties of custom elements or attributes,
Use typed events when working with the EventAggregator,
Use classes or interfaces for objects sent or retrieved using the fetch client,
Didn’t I say everything?

By typing everything, you eliminate a whole category of bugs. Additionally, you add documentation for other developers and your future self. Lastly, you give more informations to your tools (auto-completers, linters, bundlers, etc.) so they can do a better job assisting you.

Those advantages largely outweight the additional cost of properly typing things, trust me. Or don’t, and try it for yourself. You’ll see.

Small apps over big apps

Whenever possible, it’s better to write multiple small applications over writing one huge application. A small code base is more manageable than a large one, and it’s easier to have multiple small teams maintaining multiple small applications than one huge team working on a single huge code base. Small applications can be released independently and at different paces, while releasing huge apps require much more planification and coordination between team members, and such a process is most of the time rigid and not agile at all.

I didn’t invent anything here; microservices have been around long enough now, and they are based on the same principles.

Bundle intelligently

If you can’t keep your application small as suggested before, at least use bundles intelligently so your application loads faster.

For example, if your application’s users are segregated in roles, you can group features in role-based bundles. This way, a given user would load only the bundle(s) he needs to do his job based on its role(s).

If you won’t reap the benefits of small code bases - faster and independent release cycles, smaller teams, reduced code complexity - at least you won’t hurt too much your users’ experience by forcing them to load a 10 MB bundle when all they need really is 10% of it.

Organize by features

Aurelia features are extremely useful to organize your code.

For example, I often have a validation feature in my Aurelia applications. This feature handles some simple tasks related to form validation:

It loads the aurelia-validation plugin,
It registers at least one ValidationRenderer in the DI container,
It registers any custom validation rules needed across the application.

Features can also be used to group components, models, and services related to specific domains.

A chapter of my book is dedicated to this subject.

Decompose

A route component fetching data from an HTTP endpoint and rendering a complex view all by itself will likely be hard to maintain, as it has too many responsibilities. It also makes it hard - or even impossible - to reuse parts of its behavior or UI elements.

Components should be loosely coupled and highly cohesive. They should be small and solve a well-defined problem. Larger components should be composed of smaller ones, and their task should be to configure and coordinate interactions between their constituents.

A lot of Aurelia’s features can be of great help in decomposing components and making them flexible enough to be used in larger components: one-way and two-way data-binding, event aggregation, content projection, and template injection, are the cornerstones of well-taylored and highly configurable components. Make sure you master each of those techniques well enough, so you can make enlightened design decisions and use Aurelia to its full potential.

Separate UI & domain concerns

Similarly, keeping UI and domain artifacts separated in your code base will make it easier to maintain.

By UI artifact, I mean:

Components,
Custom elements & attributes,
Value converters,
Binding behaviors,
Templates.

By Domain artifact, I mean:

Domain models,
Domain services,
Back-end clients.

For example, a route component should be built by composing UI and domain artifacts together. If it fetches its own data from an HTTP endpoint, defines its own view model for this data and has a complex template to present it to the user, it will likely be hard to maintain and its constituents impossible to reuse. Additionally, domain intelligence will be lost in UI concerns.

However, if you design distinct domain models and services, isolated from UI components, then aggregate them all in a route component, this route component will be smaller because it will simply coordinate interactions between its domain and UI constituents. Plus, your code will likely be saner and easier to understand.

Again, it didn’t invent anything here. This idea comes from both Domain-Driven Design and Hexagonal architecture, and has been around for years. Even though people apply this to back-end design most of the time, front-end application design can also greatly benefit from those principles.

Have fun!

I had a lot of fun in the last year working with Aurelia. I hope you do too!

Don’t hesitate to let me know about your own experience with Aurelia. Just leave a comment! ☺

What is Aurelia's .two-way command for?

manuel.guilbault@gmail.com (Manuel Guilbault) — Sat, 11 Feb 2017 00:00:00 +0000

One of my book’s reader sent me an email earlier this week. He was confused by a statement from the book and thought it might contain a typo or some kind of error. This statement said that the .two-way binding command didn’t adapt to its context, while .bind did.

I answered that it was no error, that .bind uses two-way binding when the target property supports it and falls back to one-way binding when it doesn’t, while .two-way forces two-way binding. Although it may not be as clear as I intended, that’s what I meant when I wrote that it didn’t adapt to its context.

That question made me realize that at first glance, .two-way seems pretty useless. Why would someone want to force two-way binding on a property that doesn’t support it? It makes no sense.

I gave it some thought, and found a use case where it does actually make sense.

The .bind command uses the target property’s default binding mode. Aurelia considers that the default binding mode for all native HTML elements’ attributes and properties is one-way, except for properties affected by user inputs on form-related elements, such as an input’s or a select’s value, whose default binding mode is two-way.

However, when creating custom elements and attributes, you have complete control over the default binding mode of your component’s properties. One could easily imagine a custom attribute - or a custom element’s property - whose default binding mode is one-way, but which supports two-way binding by being somehow related to user input. In such a case, using the .two-way command would be the only way to force two-way binding for this property, since the .bind command would use one-way binding by default.

Such a scenario doesn’t seem very likely to me, but Aurelia nevertheless supports it.

Thanks to Christian for his question.

Building an image files picker with Aurelia

manuel.guilbault@gmail.com (Manuel Guilbault) — Wed, 01 Feb 2017 00:00:00 +0000

This post was initially published on Aurelia’s official blog.

In my book Learning Aurelia, you can see, among other things, how to build an image file picker component, supporting drag and drop and showing a preview of the selected image.

In this post, we’ll use the techniques described in the book to build a multi-select image file picker, also supporting drag and drop, with a gallery-style preview feature.

Picking files

Let’s start by creating a custom file-picker element, which will encapsulate an <input type="file"> element:

resources/elements/file-picker.ts:

import {customElement, useView, bindable, bindingMode} from 'aurelia-framework';

@customElement('file-picker')
@useView('./file-picker.html')
export class FilePicker {

  @bindable accept = '';
  @bindable multiple = false;
  @bindable({ defaultBindingMode: bindingMode.twoWay }) files: FileList;

  input: HTMLInputElement;

  filesChanged() {
    if (!this.files) {
      this.clearSelection();
    }
  }

  private clearSelection() {
      this.input.type = '';
      this.input.type = 'file';
  }
}

This view-model declares three bindable properties:

accept: will be bound to the input’s accept attribute, which is used to limit the type of files the browser’s dialog will show to the user.
multiple: will be bound to the input’s multiple attribute, which tells the browser’s dialog if it should support selection of multiple files or not.
files: will be bound to the input’s files attribute. This property is bound two way by default, so the file(s) selected by the user are assigned back to the bound property.

The view-model also declares an input property, to which the template will assign a reference on the <input type="file"> element.

Lastly, since the input’s files property is read-only and the DOM API doesn’t expose a method to clear the input’s file selection (other than calling the reset method on the whole surrounding form), the view-model uses a hack to clear the selected files when an empty value is assigned to the file-picker’s files property: it sets the input’s type to an empty string then resets it back to file.

resources/elements/file-picker.html:

<template>
  <input type="file" accept.bind="accept" multiple.bind="multiple" 
         files.bind="files" ref="input"
         style="visibility: hidden; width: 0; height: 0;">
  <button class="btn btn-primary" click.delegate="input.click()">
    <slot>Select</slot>
  </button>
</template>

The file-picker’s template defines an <input type="file"> element, styled so it is invisible and so it occupies no space in the DOM. Its accept, multiple, and files attributes are also properly bound to their corresponding property on the view-model. Lastly, it assigns a reference on the input to the view-model’s input property.

The template also declares a button element, styled using Bootstrap’s classes. Inside it, a default content projection slot, with the Select text as its default content. Additionally, the button’s click event calls the input’s click method. Thanks to this, the browser’s file dialog will show up when the user clicks the button, even though the input element is not visible.

This component basically just replaces the ugly native file picker with a sexier button.

Adding a file drop target

Next, let’s create a custom attribute allowing to transform any element into a file drag and drop target:

resources/attributes/file-drop-target.ts:

import {customAttribute, bindingMode, autoinject} from 'aurelia-framework';

@customAttribute('file-drop-target', bindingMode.twoWay)
@autoinject
export class FileDropTarget {

  value: FileList | (({files: FileList}) => void);
  
  constructor(private element: Element) {}

  attached() {
    this.element.addEventListener('dragover', this.onDragOver);
    this.element.addEventListener('drop', this.onDrop);
    this.element.addEventListener('dragend', this.onDragEnd);
  }

  private onDragOver = (e) => {
    e.stopPropagation();
    e.preventDefault();

    e.dataTransfer.dropEffect = 'copy';
  };

  private onDrop = (e) => {
    e.stopPropagation();
    e.preventDefault();

    if (typeof this.value === 'function') {
      this.value({ files: e.dataTransfer.files });
    } else {
      this.value = e.dataTransfer.files;
    }
  };

  private onDragEnd = (e) => {
    e.stopPropagation();
    e.preventDefault();
    
    e.dataTransfer.clearData();
  };

  detached() {
    this.element.removeEventListener('dragend', this.onDragEnd);
    this.element.removeEventListener('drop', this.onDrop);
    this.element.removeEventListener('dragover', this.onDragOver);
  }
}

The attribute’s target element will be injected in the view-model’s constructor. When the attribute is attached to the DOM, it starts listening for the dragover, drop, and dragend events on the target element. When the attribute is detached from the DOM, the event listeners are removed.

The attribute is bound two way by default, so the file(s) assigned to its value when a user drops them on the target element are assigned back to the bounded property, if any. However, upon files being dropped on the target element, the view-model checks if the value is a function or not. This means that the attribute can be used either with the .bind command, so the dropped files are assigned to the bound expression, or with the .call command, so the bound expression is called and passed the dropped files whenever a drop event occurs.

Chunking an array

In order to display the selected images as a gallery, we’ll use Bootstrap’s grid system. This means we’ll need to break the files array down in chunks, so we can iterate on chunks to render rows, then on each chunk’s files to render columns.

The best way to do this in Aurelia is with a value converter:

resources/value-converters/chunk.ts:

import {valueConverter} from 'aurelia-framework';

@valueConverter('chunk')
export class Chunk {
  toView(array: any[], size: number): any[][] {
    let result = [];
    let nbChunks = Math.ceil(array.length / size);
    for (let i = 0; i < nbChunks; ++i) {
      const offset = i * size;
      result.push(array.slice(offset, offset + size));
    }
    return result;
  }
}

The chunk value converter expects an array and the chunks’ size as its parameter and returns an array of array.

Displaying a Blob object as an image

The last part we’ll need is some way to display a File instance inside an img element. To do this, we’ll leverage the browser’s URL.createObjectURL function, which takes a Blob object as a parameter and returns a special URL leading to this resource. Our custom attribute, which will be used essentially on img elements, will be bound to a Blob object, will generate an object URL from it, and will assign this URL to the img element’s src attribute.

Some of you might think that a value converter would be a better fit for this type of feature, and I would absolutely agree. A value converter could take as an input a Blob object and return the object URL. It could then be used on a binding between an img element’s src attribute and a property containing a Blob object.

However, in this particular case, each object URL must be released after usage in order to prevent memory leaks, and value converters offer no mechanism to be notified when a value is no longer used. On the contrary, HTML behaviors offer a much richer workflow and a wider set of extension points. That’s why we will create a custom attribute instead:

resources/attributes/blob-src.ts:

import {customAttribute, inject} from 'aurelia-framework';

@customAttribute('blob-src')
@inject(Element)
export class BlobSrc {

  private objectUrl: string;

  constructor(private element: HTMLImageElement) {}

  private disposeObjectUrl() {
    if (this.objectUrl) {
      this.element.src = '';
      URL.revokeObjectURL(this.objectUrl);
      this.objectUrl = null;
    }
  }

  valueChanged(value) {
    this.disposeObjectUrl();

    if (value instanceof Blob) {
      this.objectUrl = URL.createObjectURL(value);
      this.element.src = this.objectUrl;
    }
  }

  unbind() {
    this.disposeObjectUrl();
  }
}

Bringing it all together

Each of the parts we saw up to this point is shown in the book, even though some have been modified to fit the current context.

The last missing piece is the one that brings everything together: an image-files-picker custom element.

resources/elements/image-files-picker.html:

<template>
  <div class="jumbotron jumbotron-fluid" file-drop-target.call="add(files)">
    <div class="container">
      <div class="text-center">
        <p>You can drop image files anywhere inside this area</p>
      </div>
      <div class="row" repeat.for="row of files | chunk:3">
        <div class="col-md-4" repeat.for="file of row">
          <div class="card card-inverse">
            <img class="card-img img-fluid"
                alt="Preview for ${file.name & oneTime}"
                blob-src.one-time="file">
            <div class="card-img-overlay">
              <button type="button" class="close" aria-label="Remove" 
                      click.delegate="remove($parent.$index * 3 + $index)">
                <span aria-hidden="true">&times;</span>
              </button>
              <p class="card-text">
                <small class="text-muted">${file.name & oneTime}</small>
              </p>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
  <file-picker accept.bind="accept" multiple.one-time="true" 
               files.bind="selectedFiles" 
               change.delegate="addSelectedFiles()">
    Add
  </file-picker>
</template>

The template starts with a jumbotron container, which acts as a file-drop-target. When files are dragged and dropped on this element, the view-model’s add method will be called and passed the dropped files.

Inside this container, the files array is rendered on three columns using the chunk value converter, each file displayed inside a Bootstrap card component. Each card displays the file in an img element using the blob-src attribute, a button whose click event calls the view-model’s remove method, and the file’s name.

Lastly, underneath the image gallery, a file-picker element allows the user to select image files. The selected files are bound to the view-model’s selectedFiles property, then the change event dispatched by the underlying <input type="file"> element and bubbling up the DOM triggers a call to the addSelectedFiles method. The file-picker’s default projection slot is also overwritten with the text Add.

resources/elements/image-files-picker.ts:

import {customElement, useView, bindable, bindingMode} from 'aurelia-framework';

@customElement('image-files-picker')
@useView('./image-files-picker.html')
export class ImageFilesPicker {

  @bindable({ defaultBindingMode: bindingMode.twoWay }) files: File[] = [];

  selectedFiles: FileList;

  add(files: FileList) {
    for (let i = 0; i < files.length; ++i) {
      const file = files.item(i);
      this.files.push(file);
    }
  }

  remove(index) {
    this.files.splice(index, 1);
  }

  addSelectedFiles() {
    this.add(this.selectedFiles);
    this.selectedFiles = null;
  }
}

The view-model declares a files bindable property, which is bound two way by default. This property is expected to initially contain an empty array.

When files are dropped on the drop target element, the add method is called and the dropped files are appended to the files property. When the user selects files using the file-picker, the selected files are assigned back to the selectedFiles property, then the change event handler calls the addSelectedFiles, which appends the selectedFiles to the files property, and finally assigns null to the selectedFiles.

This last step makes sure that the underlying <input type="file"> element has its selection cleared. Without it, if a user tries to add the same file twice in a row, the change event would not be triggered the second time, because the input’s value would not change, so the second file selection would fail from the user’s perspective.

Using the image files picker

Using the image-files-picker element is then pretty simple. We first need to declare a property hosting the array of files on the App view-model:

app.ts:

export class App {
  files: File[] = [];
}

Next, we simply need to add the custom element in the template of our App component:

app.html:

<template>
  <require from="bootstrap/css/bootstrap.min.css"></require>
  
  <section class="container">
    <image-files-picker files.bind="files"></image-files-picker>
  </section>
</template>

Of course, the various parts need to be loaded, either using the require statement in the app.html template, or in the resources/index.ts feature’s configure function.

Filtering out non-image files

At this point, a user can select or drop any type of files using our component. Some logic allowing only image files should be somehow added.

A basic filtering logic, using the same syntax as the <input type="file"> element’s accept attribute, is implemented in the complete code sample, which you can find here. A more complete solution, showing error messages to the user, can easily be implemented. I’ll leave this as an exercise to the reader.

Exploiting the selected images

Typically, such a component would be used to first select a bunch of image files, then to upload those files to some remote endpoint. This is pretty easy to do with Aurelia’s Fetch client and the FormData class from the Fetch API.

Here’s an example of a client service used to upload an array of File instances to some remote endpoint:

import {autoinject} from 'aurelia-framework';
import {HttpClient} from 'aurelia-fetch-client';

@autoinject
export class SomeAPI {
  constructor(private http: HttpClient) {}

  uploadFiles(files: File[]): Promise<void> {
    const body = new FormData();
    for (let i = 0; i < files.length; ++i) {
      body.append(`files[${i}]`, files[i]);
    }
    return this.http.fetch('some/url', { method: 'POST', body });
  }
}

The Mozilla Developer Network has some great doc about the FormData class.

Summary

Once again, Aurelia makes things easy. Its various constructs, such as custom attributes, elements, and value converters, help us decompose a problem and solve each of its parts with a generic, reusable solution, and then recombine them together to address our initial, specific problem. Shameless plug alert: this aspect is one of the many topics addressed in Learning Aurelia. You should definitely give it a look!

Update 2018-03-02

Reader @sokratismanolis pointed out in this comment that the code doesn’t work on IE 11 and Edge. I didn’t have time to find out the core of the issue yet, but it seems to be caused by a delegated event listener being fired before a data binding instruction is refreshed. I worked around the issue by removing the delegated event listener and by using the @observable attribute on selectedFiles, as you can see on this branch.

Building Aurelia's focus attribute

manuel.guilbault@gmail.com (Manuel Guilbault) — Fri, 05 Jun 2015 00:00:00 +0000

Aurelia is a next generation SPA framework, initiated by Rob Eisenberg, creator of Durandal. I’m really proud to be featured on the blog this week. Check it out!

Hard-coded IDs suck, and enums won't help

manuel.guilbault@gmail.com (Manuel Guilbault) — Tue, 07 Oct 2014 00:00:00 +0000

Sometimes an application requires that some features are enabled (or rules applied), or not, based on some context. What is the best way to solve such a problem?

Hard-coded IDs… Hard-coded IDs everywhere…

A C# app I was working on for a worldwide company was used in many countries. Of course, each country had specific features that were enabled and rules that were applied only for them. The previous programmers had used a very naive approach to solve this problem: they tested the user’s country ID:

if (user.Country.ID == 1)
{
    // Show a button available only for country #1
    // By the way, country #1 is France for the sake of this example
}

The app ended up being full of those ugly checks. Plus, if you don’t know the countries and their IDs and don’t have the database table under hand, good luck trying to figure out what users of which country should see this button.

Enums to the rescue - or not

I was absolutely not convinced by the first idea that came to my mind, but I decided to give it a try. I created an enum listing the countries:

public enum CountryEnum
{
    France = 1,
    Canada = 2,
    // and so on
}

Then I added a method to the Country entity:

public class Country
{
    // snip...

    public CountryEnum ToEnum()
    {
        return (CountryEnum)ID;
    }

    // snip...
}

And the checks turned into:

if (user.Country.ToEnum() == CountryEnum.France)
{
    // Show a button available only for France
}

Well… it was a little better. It was much easier to see what features and rules applied to which country. But it still sucked. Mainly because it was hard to change. Imagine having a rule for France that would require to show or enable multiple buttons, links, table columns or whatever on multiple views. And imagine that Canada wants that same feature in the next release. It was still a huge “oh God no” for me to go and update all those checks to include those pesky Canadians. Add to that the fact that the pages and user controls (yes, it was a web forms app) were bloated with those checks, sometimes many of them entangled together, and you’ve got a huge mess on your hands. Time to sit back and think.

Feature toggles

I remembered reading a while ago about feature toggles on Martin Fowler’s bliki, and I realized that this solution, although brought up in a static context (the way Fowler describes them, feature toggles are enabled or disabled generally in configuration - in our example, each country would have its own live version of the app, configured for its own needs), could be applied in a dynamic context like mine.

So I rolled all my changes back, and started from scratch:

public class CountryFeatures
{
    public bool CanDoThis { get; private set; }
    public bool CanSeeThat { get; private set; }
    public bool MustConfirmBeforeThatAction { get; private set; }
    // and so on for every country-specific feature or rule
}

You get the idea for the next step, I guess:

public class Country
{
    // snip...

    public CountryFeatures Features { get; private set; }

    // snip...
}

How I initialized the Features property for each country is not relevant to this article: you could store the feature switches for each country in a database table, in a configuration file, or even hard-code them for all I care. What’s important is that the feature checks were now much clearer:

if (user.Country.Features.CanDoThis)
{
    // Show the button used to do this
}

Now that is a much better solution. The single responsibility principle is respected: the view only needs to know if a given feature is enabled or not to decide if it must render the button. It doesn’t need to know for which country the feature is enabled anymore.

Additionally, even if this check was found in multiple places, there was no need to change all those occurrences anymore to enable the feature for Canada. I only needed to toggle the feature on for the countries that needed it.

Summary

Feature toggle is a powerful tool that can be leveraged not only statically, through configuration, to enable or disable features on a per-deployment basis, but it can also be used dynamically, using some context information in a single deployment setup.