Sam Dawson

Using require and transclusion in Angular1 components

Tue, 11 Apr 2017 00:00:00 +0000

When creating a ‘select/dropdown’ component we need to pass a list to the component which it then uses to display the available options for the user to select.

The simplest way to do this is to pass a array in the component binding, which it then internally repeats and fires some event when the user chooses a option.

In these examples our select is called dropdown

<dropdown options="['add','edit','delete']" on-option-select="onOptionSelect(selectedOption)"></dropdown>

The limitation on this approach is that we are then limited to use the same template for each use of the component.

Another approach is to use a combination require and transclusion to make our component usage look like the following, which will allow us to use custom templates for the options in each usage of our dropdown component.

<dropdown on-option-select="onOptionSelect(optionName)">
  <dropdown-option ng-repeat="option in options" option-name=""></dropdown-option>
</dropdown>

First we want to setup the parent dropdown component

myApp.component('dropdown', {
  template: `
    <div class="dropdown">
      <div class="dropdown__button" ng-click="$ctrl.toggleDropdown()">Select a option &or;</div>
      <div class="dropdown__box" ng-show="$ctrl.showDropdown">
        <ng-transclude></ng-transclude>
      </div>
    </div>
  `,
  transclude: true,
  bindings: { onOptionSelect: '&' },
  controller: dropdownController,
});

The ng-transclude element will be replaced with multiple dropdown-options components which we will build next. We also want to setup functions on the dropdown controller, which will be used in the template above.

function dropdownController() {
  const viewModel = this;
  
  viewModel.addOption = addOption;
  viewModel.toggleDropdown = toggleDropdown;
  
  function addOption(option) {
    viewModel.options.push(option);
  }
  
  function removeOption(option) {
    viewModel.options.splice(options.indexOf(option), 1);
  }
  
  function toggleDropdown() {
    viewModel.showDropdown = !viewModel.showDropdown;
  }
}

You will notice that there are some functions here that we are not using within our template. The addOption and removeOption functions both modify the internal options data model, these functions we will use in our child dropdown-option component.

Next lets setup our dropdown-option component. Using the require object we can specify that this component must be used within our previously defined parent component dropdown.

myApp.component('dropdownOption', {
  template: `
    <ng-transclude class="dropdown__box__option" ng-click="$ctrl.onOptionClick()"></ng-transclude>
  `,
  transclude: true,
  require: { parent: '^dropdown' },
  bindings: { optionName: '@' },
  controller: dropdownOptionsController,
});

We now have access to the parent dropdown components controller within dropdown-options controller, using the parent property that we specified in our require object above.

The parent.addOption function is now used $onInit() to register the dropdown option, and the parent.removeOption is used $onDestroy() to remove the option from our parent dropdown options data model.

function dropdownOptionsController() {
  const viewModel = this;
  
  viewModel.$onInit = $onInit;
  viewModel.onOptionClick = onOptionClick;
  
  function $onInit() {
    viewModel.parent.addOption(viewModel.optionName);
  }
  
  function onOptionClick() {
    viewModel.parent.onOptionSelect({optionName:viewModel.optionName});
    viewModel.parent.toggleDropdown();
  }
  
  function $onDestroy() {
    viewModel.parent.removeOption(viewModel.optionName);
  }
}

We can also trigger the parent.onOptionSelect() from the dropdown-option component.

Note: We never ended up using the options data model on our dropdown component, but I thought it was useful to add to show how you can communicate between parent/child components using require.

Complete Example

Google login with angularfire2

Sun, 02 Apr 2017 00:00:00 +0000

This is a specfic use case of firebase, it took me a while to setup myself so I thought it might be worth sharing.

Assuming that we already have angular2 setup we want to install angularfire2

npm install firebase angularfire2 --save

Next assuming that we already have a firebase project setup. In the root app module we want to initialize our firebase project

import { AngularFireModule } from 'angularfire2';

const firebaseConfig = {
	apiKey: "...",
	authDomain: "myapp.firebaseapp.com",
	databaseURL: "https://myapp.firebaseio.com",
	storageBucket: "myapp.appspot.com",
	messagingSenderId: "..."
};

@NgModule({
	...
	imports: [
		'...',
		AngularFireModule.initializeApp(firebaseConfig),
	],
})
export class AppModule { }

We are using google as our user authentication as a example here, firebase has other authentication methods email/password, facebook, github etc. We can setup what type of authentication we want to use during our app’s root module initilization. We want to use the angular fire module AuthProviders to specifiy our authentication type, and then specify our method (popup, redirect etc.) using AuthMethods.

import { AngularFireModule, AuthMethods, AuthProviders } from 'angularfire2';

const firebaseAuthConfig = {
  provider: AuthProviders.Google,
  method: AuthMethods.Redirect
};

@NgModule({
	...
	imports: [
		'...',
		AngularFireModule.initializeApp(firebaseConfig, firebaseAuthConfig),
	],
})
export class AppModule { }

Since we have setup authentication in the application bootstrap we can call

af.auth.login();

We are able to call login() without any parameters because we have already setup our authentication provider and method in our root module initilization.

Because we setup redirect as our method, calling the af.auth.login() function will redirect the current page to a google login page, and then redirect to back to our application.

Now that the user has logged in and has been redirected back to our app, we want to be able to retrieve some info about the logged in user. We can subscribe to the login event using

this.af.auth.subscribe(auth: FirebaseAuthState => {
	auth = auth;
});

The FirebaseAuthState object returned has a uid property which we can use as a key to store that users data in firebase.

angular fire provides a database object which allows us to change data within our projects database.

this.shoppingList = this.af.database.list(`/users/${auth.uid}/shoppingList`);

The list function allows us to store a <array>, there is also a object method available.

The database.list() function returns a observable which we can display in our template using the async pipe

<li *ngFor="let listItem of shoppingList | async">
	
</li>

To add items to our ‘shoppingList’ we can use

this.af.database.list(`/users/${auth.uid}/shoppingList`).push('bread');

Angular 2 Icon System

Fri, 24 Mar 2017 00:00:00 +0000

Here is the “Angular Icon System” rebuilt for angular 2. Converting it to angular 2 did provide some syntactic sugar, the component otherwise remains mostly the same.

Link to Plunker example

svg-icon.component.ts

import { Component, OnChanges, Input } from '@angular/core';
import { NgStyle } from '@angular/common/index';

@Component({
  selector: 'svg-icon',
  template: 
    `<svg class="icon" [ngStyle]="svgStyle">
      <use attr.xlink:href="#"></use>
    </svg>`,
  styleUrls: ['./svg-icon.component.css']
})

export class SvgIconComponent implements OnChanges {
  @Input() iconName: string;
  @Input() iconSize: number;
  
  svgSymbolId: string;
  svgStyle: object;
  
  ngOnChanges(changes: SimpleChanges) {
    if (changes.iconName) {
      this.svgSymbolId = changes.iconName.currentValue;
    }
    
    if (changes.iconSize) {
      this.svgStyle = { 'font-size': changes.iconSize.currentValue };
    }
  }
}

svg-icon.component.css

.icon {
  fill: currentColor;
  width: 1em;
  height: 1em;
}

HTML usage

<svg-icon [iconName]="'apartment'" [iconSize]="40"><svg-icon>

Angular Icon System

Tue, 21 Mar 2017 00:00:00 +0000

This is a example of the angular icon system that I use, it’s aim is to keep icon naming consistent and the html needed to generate a icon small.

Displaying a icon using SVG symbols

A prerequisite for the icon system is that every icon has a unique name. The icon system relies on a single SVG with multiple symbols, we then <use> the symbol in one or more places.

This SVG is prepended to the body of our html. We are using a Internally referenced SVG in this example another approach that would work with this icon system is to use externally referenced svg files.

<svg style="position: absolute; width: 0; height: 0; overflow: hidden">
    <defs>
        <symbol viewBox="0 0 20 20" id="apartment">
            <title>apartment</title>
            <path d="..."></path>
            <path d="..."></path>
        </symbol>
        ...
    </defs>
</svg>

I am going to skip over how we got to this point where the SVG’s are already in the document body. It would be tedious to manage our svg symbols by having them statically in the body of our html.

With this icon system in its real world usage I concatenate the SVG’s with a ‘icon build system’ which I will explore in another post, the build system allows me to place all of my icons as single SVG’s into a directory, the build system then collects all of those icons and injects them into the body.

Once we have the SVG symbols injected into our html we can <use> our SVG’s.

<svg class="icon">
    <use xlink:href="#apartment"></use>
</svg>

(explain xlink href)

We are referencing the ‘apartment’ SVG that is in our SVG symbols. The above example produces our ‘apartment’ icon

Building a icon component

Now that we have got the basic version of this icon system working we can begin to build on top with angular. We are going to create a angular component which uses a variation of the above html as its template. Instead of the hard coded ‘#apartment’ we use the injected string iconName from the our svgIcon component.

.component('svgIcon', {
    template: '<svg class="icon">
                  <use xlink:href="{{$ctrl.iconName}}"></use>
              </svg>',
});

Lets define iconName as a binding, iconName references the symbol ID directly from our svg defs.

.component('svgIcon', {
    template: '<svg class="icon">
                  <use xlink:href="{{$ctrl.iconName}}"></use>
              </svg>',
    bindings: {
        iconName: '<',
    },
    controller: function (){}
});

To produce our ‘apartment’ icon we then only need the following html. Assuming we have our angular modules wired up correctly.

<svg-icon icon-name="'apartment'"><svg-icon>

Here is a working example of all of the concepts we have covered so far. There are some extras in the example that I have left out so far for simplicity. Assumed knowledge here is the $onChanges life cycle hook and ng-style used to set our icon size.

See the Pen Angular Icon System (Icon) by Sam Dawson (@Samic8) on CodePen.

Aliases

Aliases are the most powerful part of this icon system, it helps keep icons consistent across our application. Aliases provide a way for an icons unique name to be independent of their usage name, allowing the same icon to be used for multiple use cases with different naming.

Another benefit is being able to replace icons with without having to do a find and replace. Now lets get into how we go about getting aliases working for our icon system.

We want to add a extra binding to our svgIcon component called aliasName. Here we will use one-way binding (<), which allows us to watch for changes and update icons on the fly.

.component('svgIcon', {
    template: '<svg class="icon">
                  <use xlink:href="{{$ctrl.iconName}}"></use>
              </svg>',
    bindings: {
        iconName: '<',
        iconAlias: '<',
    },
    controller: function (){}
});

For our apartment icon, lets set up a alias name of ‘building’. So that we can use the component like so

<svg-icon icon-alias="'building'"><svg-icon>

We need to write some extra javascript in our controller to get this working, so far our controller has been empty. First we want to create a aliases object, the holds our alias/icon name associations.

function svgIconController() {
	const ctrl = this;
	
	const aliases = {
		building: 'apartment',
		...
	};
}

Now that we have a string that does not directly associate with a symbol in our svg, we want to make sure that we translate aliasName input to a string that is actually associated with a symbol.

Lets change the template so it is not directly using our ‘iconName’ binding

.component('svgIcon', {
    template: '<svg class="icon">
                  <use xlink:href="{{$ctrl.svgSymbolId}}"></use>
              </svg>',
    bindings: {...},
    controller: ...
});

Now we want to get the symbol id from the associated ‘aliasName’ aliases[aliasName] and set the result to the svgSymbolId. Our component is now multipurpose as it accepts both ‘iconName’ and ‘aliasName’, we are assuming the developer will use either/or and not both (our component could be extended to error etc.)

function svgIconController() {
	const ctrl = this;
	
	const aliases = {...};
	
	this.$onChanges = $onChanges;
	
	function $onChanges({iconName, aliasName, iconSize}) {
		ctrl.svgSymbolId = `#${iconName.currentValue ? iconName.currentValue : aliases[aliasName.currentValue]}`;
	}
	
}

_{Destructuring assignment is used as our function arguments}

Usage of <svg-icon icon-alias="'building'"><svg-icon> will produce

See the Pen Angular Icon System (Aliases) by Sam Dawson (@Samic8) on CodePen.

Bonus

ng-repeat

With our icon system wired up to accept one way bindings we can use ng-repeat to produce dynamic lists of icons. In our root controller we can set up a array of iconName (we could also use iconAlias)

function rootCtrl($scope) {
    $scope.iconsToRepeat = [
        'cash-dollar',
        'bubbles',
        'calculator',
        'apartment'
    ];
}

<div ng-repeat="iconName in iconsToRepeat">
    <svg-icon icon-name="iconName"></svg-icon>
</div>

Which produces our icons

Colors

This icon system can be used with the color system outlined in my previous post.

We can use currentColor as the fill property on the svg inside our svgIcon component and then on the components element use a color class, the svg will inherit our color.

.icon {
    fill: currentColor;
}

_{Note: That the icons we are using in these examples are fill only icons. This sort of color inheritance will prove difficult if we needed to use icons with multiple colors, this is a limitation.}

Icon sizing

In this icon system we are using icons that have equal width and height. Therefore being able to simultaneously change the width and height with a single value, we can set our icons width and height properties to 1em. The icons will now equal the current font-size, meaning if we set a font-size of 20px on the parent element or directly the svg will use the current font size as both its width and height.

.icon {
    ...
    width: 1em;
    height: 1em;
}

To use this with our icon system we could use inline styling

<svg-icon icon-name="apartment" style="font-size: 20px"><svg-icon>

If we want to do this a little cleaner we could add a iconSize binding to our component and then apply the font-size in a inline style within the component

<svg-icon icon-name="apartment" icon-size="20"><svg-icon>

Complete example

See the Pen Angular Icon System (Repeat) by Sam Dawson (@Samic8) on CodePen.

Link to post on this icon system being rebuilt for angular 2

Color Organization

Tue, 14 Mar 2017 00:00:00 +0000

Keeping colors consistent across an application is difficult, here are some patterns that I use that help with consistency. The syntax in the code examples is in Sass.

Variables

When I need a new color, I begin with assigning it as a global sass variable. Another option would be to use a sass map for colors, making looping possible (I am considering changing to this approach).

The basic building block for the color system is the global variable. They consist of a post-fix “color”, a [shade] and a unique identifier [name], ‘color-[shade]-[name]’.

$color-grey-elephant: #F1F1F1;
$color-red-kickflip: #e74c18;
$color-green-leaf: #17ae00;

_{Note: The syntax in the code examples is in scss.}

The post-fix “color” identifies the variable as being associated a hex code value, next the shade “$color-[green etc.]” gives some indication to what shade of color its is, then lastly the name is just a any string (get creative), providing some memorability by having a unique name.

I have been called out multiple times on how ridiculous my naming can get on occasion, but at least it is memorable. These color names can then also be shared with others, so that everyone has the same name to reference for the color. I am still experimenting with ways to share these colors to people that do not code, one attempt I have experimented with is to regex all the hex codes in a file and then use those hex codes to build a static html file, this builds a “color styleguide”.

_{Link to styleguide}

Aliases

The second building block to the color system is aliases. Instead of repetitively informing others that “$color-green-leaf” is used on all “Edit” buttons, we can give the colors secondary names that describe exactly what it is used for.

$color-alias-edit-button: $color-green-leaf;
$color-alias-delete-icons: $color-red-kickflip;
$color-alias-external-hyperlinks: $color-green-leaf;

Similar to our standard color variable naming pattern, the aliases begins with a static identifier [color-alias]. Its clear what each color is used for, and others can reference the code for the color alias. It also helps prevent others from creating similar colors for the same purpose, e.g. creating similar shades of green for the same edit button used in different locations.

Classes

Having the colors available in sass is a inherit benefit, making them available for direct use in the html would be convenient for speeding up development and preventing having to write new classes every time we want to use a color. To have easy access to each color and color alias I then create a class of the same name for each.

.color-grey-elephant { color: $color-grey-elephant; }
.color-alias-edit-button { color: $color-alias-edit-button; }

_{This can become less tedious by looping to producing these classes, one approach could be to store the colors in a sass map.}

When I want to use the color in the html, I can then use it directly as a class.

<a class="button color-alias-edit-button">Edit</a>

Its most likely that we want the color of the buttons background to be green, but the class that we have applied will only change the text color by default. This is where the use of the property value “currentColor” becomes very useful. To get the button to appear with a green background we could add this to our button class.

.button {
	display: inline-block;
	padding: 10px 5px;
	border-radius: 2px;

	background: currentColor;
}

Now we have a green background. A pre caution for using currentColor in this context, is that the buttons text is now green as well. To fix this we can use another element within our button and make sure it does not inherit its color from its parent.

<a class="button color-alias-edit-button">
	<span class="color-grey-elephant">Edit</span>
</a>

Aliases in Javascript

I have found it useful to keep a list of color aliases in the javascript, in my case for use in graphs. That way the sass still owns the colors, but the js has a reference to the class name which it can then apply when needed to elements. This saves use from duplication, and when the colors change in the sass it will be reflected in the JS applied versions as well. In the following example the key is the type of data being graphed.

const classColorAliases = {
	people: 'color-alias-graph-people',
	dogs: 'color-alias-graph-dogs',
	cats: 'color-alias-graph-cats'
};