Friday, December 30, 2016

Version 0.2.0 of vadacl Released

I just released a new version of my vadacl validation library for Angular 2. The new release includes the following updates:

  • To match a recent change to the pattern Validator in Angular 2, vadacl's pattern validation method was updated to accept both string and RegExp pattern arguments.

  • A requiredTrue validation method was added to parallel the recently-added Angular requiredTrue Validator (used primarily for validating that a checkbox has been checked/set to true).

  • The applyCollectionRule() method was added to the Vadacl class. The new method is designed to be used instead of the applyRules() method when applying a single validation method to a FormGroup or FormArray.

  • Added three new validation methods specifically for FormGroup and FormArray validation:

    • totals: validates that the sum of the numeric values of the FormGroup or FormArray controls equals a certain amount.

    • equalValues: validates that all of the values of the FormControls within a FormGroup or FormArray are exactly equal. Useful for performing password confirmation.

    • withinTrueCount: validates that the number of FormControls within a FormGroup or FormArray with a value of Boolean true falls within a given range. Designed primarily to validate how many checkboxes are checked.

  • Added and updated demos to demonstrate the new validation methods.

  • Updated the demo codebase to Angular 2.4.1

Tuesday, November 29, 2016

Locale-Based Message Support Added to vadacl

The latest release of my vadacl validation library for Angular 2 introduces a new feature:  locale-based error message configuration.

Prior to this release, vadacl would allow you to configure the error message for a particular validation error condition for a particular object property in either the object-based validation settings or in the component responsible for the form controls.  And if you did not declare an error message in either of those places, the validation method would return a method-specific default error message from the Messages object.  So in the following (slightly-contrived) scenario:


// app/vadacl/locale/messages-en.ts
let Messages = {
  /* DEFAULT LOCALE VALIDATOR ERROR MESSAGES */
  required: 'A value is required',
  ...
}


// app/domain/user-profile.ts
...
export class UserProfile implements Validatable {
  firstName: string = null;
  lastName: string = null;
  username: string = null;
  age: number = null;
  gender: string = null;

  validations: { [ index: string ] : PropertyValidations } = {
    firstName: {
       required: { message: 'Your first name is required.' }
    },
    lastName: {
       required: {}
    },
    username: {
       required: { message: 'Username is required.' }
    },
    age: {
       required: {}
    },
    gender: {
       required: {}
    }
  };
  ...
}

// app/forms/user-profile-form.component.ts
...
export class UserProfileForm extends Vadacl implements OnInit {
  profileForm: FormGroup;
  userProfile: UserProfile;
  ...

  ngOnInit() {
    this.userProfile = new UserProfile();

    this.profileForm = new FormGroup({
      'firstName': new FormControl(
         this.userProfile.firstName,
         this.applyRules( this.userProfile, 'firstName' )
      ),

      'lastName': new FormControl(
         this.userProfile.lastName,
         this.applyRules( this.userProfile, 'lastName', { required: { message: 'Your last name is required.' } )
      ),

      'username': new FormControl(
         this.userProfile.username,
         this.applyRules( this.userProfile, 'username', { required: { message: 'Please enter a username.' } )
      ),

      'age': new FormControl(
         this.userProfile.age,
         this.applyRules( this.userProfile, 'age' )
      ),

      'gender': new FormControl(
         this.userProfile.gender,
         this.applyRules( this.userProfile, 'gender' )
      )
    });
  }
  ...
}
...the validation error message for each UserProfile property in the UserProfileForm template that fails the required validation would be:
  • firstName: "Your first name is required."
  • lastName: "Your last name is required." (the message is provided during the FormControl instantiation)
  • username: "Please enter a username." (the component-level message overrides the object-level message)
  • age: "A value is required"
  • gender: "A value is required"

Now vadacl provides the option to configure error messages for object properties in the Messages object rather than in the validation settings in the object. Refactoring the example above to use the new feature, the code would look like:


// app/vadacl/locale/messages-en.ts
let Messages = {
  /* DEFAULT LOCALE VALIDATOR ERROR MESSAGES */
  required: 'A value is required',
  ...

  /* LOCALE-BASED DOMAIN CLASS MESSAGES */
  UserProfile: {
    firstName: {
      required: 'First name is required.'
    },
    lastName: {
      required: 'Last name is required.'
    },
    username: {
      required: 'Username is required.'
    }
  }
  ...
}

// app/domain/user-profile.ts
...
export class UserProfile implements Validatable { 
  ...
  validations: { [ index: string ] : PropertyValidations } = {
    firstName: { required: {} },
    lastName: { required: {} },
    username: { required: {} },
    age: { required: {} },
    gender: { required: {} }
  };
  ...
}

// app/forms/user-profile-form.component.ts
...
  'lastName': new FormControl(
    this.userProfile.lastName,
    this.applyRules( this.userProfile, 'lastName' )
  ),

  'username': new FormControl(
    this.userProfile.username,
    this.applyRules( this.userProfile, 'username', { required: { message: 'Please enter a username.' } )
  ),
...
...and the error messages would now be:
  • firstName: "First name is required."
  • lastName: "Last name is required."
  • username: "Please enter a username."
  • age: "A value is required"
  • gender: "A value is required"

The validation message defaults to the message in the Messages object that matches the object / property / validation method combination. If a different message is defined for that property in the object validation settings (which ordinarily you wouldn't do if you wanted to use the locale-based messages in the Messages object) or in the component when configuring the FormControl, that other message would become the message value returned when validation fails.

Configuring the validation messages in the Messages object allows you to keep all of the object-level messages in one place.  In theory, this should also give developers who need to perform internationalization the option of creating Messages objects for different languages and then altering which Messages file is imported into validation-methods.ts file as a build step prior to compiling the app.

Friday, November 11, 2016

vadacl: A Library For Streamlining Form Validation in Angular 2

The initial version of my TypeScript-based vadacl library for performing form validation in Angular 2 is now available on GitHub.

vadacl provides the following enhancements to the typical implementation of form validation via the reactive form classes (FormControl, FormGroup, FormArray, and FormBuilder):

  • Instead of configuring all of the validation in the component hosting the form, you can configure certain validations within the data object itself (validation rules that should remain consistent wherever the data object is used in your application), then add to or modify those validation rules in the component to create the final set of validations needed for a given form.

  • The vadacl validation methods add a "message" property to the metadata object returned when the form data fails validation.  This "message" property value is the message meant to be presented to the user, and can be configured and/or overridden at multiple levels:

    • The method level, via a set of default message values
    • The data object
    • The component level
  • The Vadacl class, whether used as a superclass for your component or as a service, provides methods for providing an array of validator methods to the FormControls in your form and for displaying the validation error "message" values in your template, removing the need to add multiple DOM elements with "ngIf" directives to display each kind of validation error or to add code to your component to gather and translate validation failures into error messages.

vadacl is (currently) a small library contained in a single folder you can just drop into your Angular application. The GitHub repo contains that folder as part of a small Angular 2.1.1 application containing several working demos of vadacl in action.

Enjoy!

Tuesday, November 8, 2016

Learning Angular 2: Implementing My vadacl Validation Library

Version 0.0.7 of my sandbox GuildRunner Angular 2 application is a refactor of the sandbox Chapter form I created in the previous version.  I refactored the form, which uses Angular's reactive form classes (FormControl, FormGroup, FormArray, and FormBuilder) to use a small validation library I created called vadacl.

The two main features of vadacl are:

  • It allows developers to set validation rules for the properties of a domain class at both the domain class level and the component level (because some validations are there to ensure the data can be persisted back to the server, and those validations should be set on the domain class so they are consistent throughout the application).

  • It gives developers the ability to set a "message" value that will be part of the metadata object returned from a validator when the data is invalid (which you can see in action in the refactored sandbox Chapter form).

You can read more about vadacl in my blog post about the library and in the README file in the vadacl GitHub repo.

Wednesday, October 5, 2016

Learning Angular 2: Exploring Reactive Form Classes and Validators

Version 0.0.6 of my sandbox GuildRunner Angular 2 application adds an example of using the reactive form and Validator classes provided by Angular 2.  The example was added to the sandbox collection of components rather than the main application, as I plan on taking what I learned from the exercise and expanding on it when I write the "real" forms.

In my blog post regarding GuildRunner release 0.0.4, which was my take on handling validation for Angular template-driven forms, I incorrectly stated that the other approach to forms supported by Angular 2 was referred to as "dynamic forms."  That's not the case:  the documentation page I was referring to was about how to dynamically generate form inputs for a collection of model data, which is a scenario where using the reactive form classes makes a lot of sense.  The documentation page that gave me the correct name to the alternative to template-driven forms - reactive forms - was the page on form validation.

In the reactive form style, you do not bind your form controls to your model data.  Instead, you bind them to the reactive form classes, which are:

The most basic reactive form - a form with a single input - would be constructed with a single FormGroup containing a single FormControl for the form input.  So a reactive form containing a single text input (say a "name" field with an initial value of "Bob") would be coded in the component like so:


/*
Import the reactive form classes (your Angular module will also have to import the Angular ReactiveFormsModule)
*/
import {FormControl, FormGroup } from '@angular/forms';
...
export class MyReactiveFormComponent implements OnInit {
  myForm: FormGroup;
  
  ngOnInit() {
    this.myForm = new FormGroup( {
      'name': new FormControl( 'Bob' )
    } )
  }

...And the HTML template for the form would be written like so:


<form [formGroup]="myForm">
  <input type="text" formControlName="name">
</form>

Note how the HTML form is connected to the FormGroup via the formGroup attribute, and how the text input is bound to the FormControl via the formControlName attribute: ngModel is not in play here.

Form input validation is applied by adding validator functions to the FormControl: a FormControl takes either a single validator function or an array of validator functions as its second constructor argument. Making the name input in our example required with a minimum length of 2 characters is a simple matter of adding the necessary validator functions shipped with Angular 2 within the Validators class:


  ngOnInit() {
    this.myForm = new FormGroup( {
      'name': new FormControl( 'Bob', [ Validators.required, Validators.minLength(2) ] )
    } )
  }

A validation check will occur anytime the value of the FormControl changes, whether that change is made via the UI or programmatically (which is an improvement over how the template-driven forms work).

A FormGroup can contain any number of FormControl objects.  It can also contain additional FormGroups (sub-groups within the main FormGroup) and FormArrays which hold a collection of unnamed, iterable FormControls.  A single validator function can be attached to each FormGroup and FormArray, usually a custom validator function that performs a validation based on multiple form values.

To try out these features, I created a form for updating certain properties of a Chapter domain class:

  • A text input for updating the chapter name.
  • A select box for selecting the guild the chapter belongs to.
  • A radio button for setting whether or not the chapter was the head chapter for the guild.
  • A series of checkboxes representing the defense measures used at the chapter location, represented in the Chapter domain class an array of defense measure ID values.
In the component, I created a single method (called in ngOnInit) for instantiating the reactive form classes and for subscribing to the change event emitter:

//sandbox/chapter-reactive-form/chapter-reactive-form.component.ts
import { Chapter } from "../../domain/chapter";
import { guilds } from "../../db/guilds";
import { defenseMeasures } from "../../db/defense-measures";

import {FormControl, FormGroup, FormArray, Validators, FormBuilder} from '@angular/forms';
...
export class ChapterReactiveFormComponent implements OnInit {

  chapter: Chapter;
  defenseArray: any = []; //Populated by ngOnInit with an array of defenses
  guildArray: any = []; //Populated by ngOnInit with an array of guilds
  defenseBoxArray: FormArray;
  form: FormGroup;
  ...
  constructor( private formBuilder: FormBuilder ) { }
  ...
  buildForm() {

    //Create a custom Validator function for the defenses array
    function hasDefenses( formArray: FormArray) {
      let valid = false;
      for( let c in formArray.controls ) {
        if( formArray.controls[c].value == true ) { valid = true }
      }
      return valid == true ? null : { noDefenses: true }
    }

    //Construct and populate the defenses FormArray outside of the FormBuilder so we can populate it dynamically
    this.defenseBoxArray = new FormArray( [], hasDefenses );
    for( let d in this.defenseArray ) {
      this.defenseBoxArray.push( new FormControl(( this.chapter.defenses.indexOf( this.defenseArray[d].id ) > -1 )))
    }

    this.form = this.formBuilder.group( {
      'name': [ this.chapter.name, [
        Validators.required,
        Validators.minLength(4),
        Validators.pattern('[a-zA-Z]+')
      ] ],
      'guild': [ this.chapter.guildId, Validators.required ],
      'headChapter': [ this.chapter.headChapter, Validators.required ],
      'defenses': this.defenseBoxArray
    } );

    this.form.valueChanges
      .subscribe( data => this.checkFormValidity( data ) );
  }

The hasDefenses() function definition is an example of how to create a custom validator function, which should either return null if validation passed or return an object literal that provides some context for why the validation failed. The function is then passed as the 2nd argument in the FormArray constructor.

The rest of the FormGroup representing the form is created using the FormBuilder, which provides a less verbose way to instantiating the other reactive form classes. The final statement in the method subscribes to the valueChanges event emitted by the form anytime a form value is updated and ties that event to the execution of the checkFormValidity method which I'll touch on shortly.

The HTML form controls that bind to these reactive form elements looks like this:


<-- sandbox/chapter-reactive-form/chapter-reactive-form.component.html -->
<form class="form-horizontal well well-sm" *ngIf="chapter" [formGroup]="form">
  ...
  <input id="name" type="text" class="form-control" formControlName="name">
  ...
  <select id="guild" class="form-control" formControlName="guild">
    <option [selected]="form.controls.guild.value == null" value="">-- Select --</option>
    <option *ngFor="let g of guildArray" [selected]="g.id == guild" [value]="g.id">{{g.name}}</option>
  </select>
  ...
  <input type="radio" formControlName="headChapter" name="headChapter" value="true" [checked]="form.controls.headChapter.value === true"> Yes   
  <input type="radio" formControlName="headChapter" name="headChapter" value="false" [checked]="form.controls.headChapter.value === false"> No
  ...
  <ul formArrayName="defenses"> <!-- Must set the formArrayName -->
    <li *ngFor="let def of form.controls.defenses.controls; let i = index">
      <input type="checkbox" formControlName="{{i}}" > {{defenseArray[i].label}}
    </li>
  </ul>

A few things worth pointing out:

  • The "--Select--" option for the guild drop-down was something I added so that text was displayed in the select box when the current value was null. The control would work fine without it.
  • Setting the "checked" attribute on the radio buttons based on the current headChapter form control state was necessary in order to show the initial value.
  • When a form control belongs to either a sub-FormGroup or a FormArray (as in this case), you need to use the formGroupName or formArrayName as an attribute in an HTML element that encloses the HTML elements bound to the FormControls within the FormGroup or FormArray.

As mentioned earlier, a validator function returns an object literal with context information about the validation problem when validation fails.  Those object literals need to be translated into appropriate error messages to display to the user.  So in a similar fashion to what I did with my template-driven form, I had to provide some translations in my component as well as a collection of arrays to hold the translated error messages:


//sandbox/chapter-reactive-form/chapter-reactive-form.component.ts
  ...
  errMsgs: any = {
    name: [],
    guild: [],
    headChapter: [],
    defenses: []
  };

  translations: any = {
    name: {
      required: 'The name is required.',
      minlength: 'The name must be at least 4 characters long.',
      pattern: 'The name can only contain letters.'
    },
    guild: {
      required: 'Please select a guild.'
    },
    headChapter: {
      required: 'Please select either Yes or No.'
    },
    defenses: {
      noDefenses: 'The chapter must implement at least one defensive measure.'
    }
  };

Note how each translation block consists of the name of the form control and an object literal whose properties names match up with the object literal keys returned by the validator functions (including the one returned by my custom hasDefenses() function).

The checkFormValidity() function (executed when the form emits the event indicating a form value has changed) performs the work of examining the current validation errors generated by the reactive form controls and creating the proper user-appropriate error messages:


/sandbox/chapter-reactive-form/chapter-reactive-form.component.ts
  ...
  checkFormValidity( data?: any ){
    for( let k in this.errMsgs ) {
      this.errMsgs[k] = [];
      if( this.form.controls[k].errors && this.form.controls[k].dirty ) {
        for( let e in this.form.controls[k].errors ) {
          if( this.translations[k][e] ) {
            this.errMsgs[k].push( this.translations[k][e] );
          }
        }
      }
    }
  }

Note that the validation error translation only occurs when the invalid form control is in a "dirty" state:  like template-driven form HTML elements, each form control has status values denoting if the form control is pristine or dirty, valid or invalid, and untouched or touched.  Preventing the users from seeing any validation errors when the control is pristine is desirable when you have a form that may initially be empty:  you don't want to display an error on a required field before the user has entered any data.  However, there is a drawback:  if you do change a form value programmatically, the change will trigger a validation check on the form control but it won't change the control state to dirty.  The workaround for that is to manually mark the field as dirty prior to changing the value, as demonstrated in this method:


changeName() {
  this.form.controls['name'].markAsDirty();
  this.form.controls['name'].setValue( '999' ); //invalid based on the [a-zA-Z]+ pattern validator
}

Flipping back to the HTML template, the user-appropriate error messages are displayed under the form controls like so:


<div *ngIf="errMsgs.name.length" class="alert alert-danger">
  <ul>
    <li *ngFor="let error of errMsgs.name">
      {{error}}
    </li>
  </ul>
</div>

Another benefit to using the reactive form classes is that the FormGroup class comes with a reset() method that not only blanks/nulls out the targeted form control values, it also resets the form controls back to a pristine and untouched state.

The final piece of the puzzle was to write a submit method that would copy the form control values back to the Chapter object (I also coded the submit button to be disabled whenever the FormGroup representing the form was flagged as invalid):


  submitForm() {
    this.checkFormValidity()
    if( this.form.valid ) {
      this.chapter.name = this.form.value.name; //value is a key/value map
      this.chapter.guildId = +this.form.value.guild; //need this translated to number, hence +
      this.chapter.headChapter = this.form.value.headChapter === "true";
      this.chapter.defenses = [];
      for( let db in this.defenseBoxArray.controls ) {
        if( this.defenseBoxArray.controls[ db ].value == true ) {
          this.chapter.defenses.push( this.defenseArray[ db ].id )
        }
      }
    }
  }

I then added interpolations to the template that would display the state and raw error values of the form controls as well as the current Chapter model values so I could watch everything in action when using the form:

Some final notes:

  • You may notice in the animated GIF of the form that the reset action did not clear the radio buttons. That's due to the fact that I'm still using RC5: that bug was fixed in the official release of Angular 2.

  • Although you can supply a validator function as an argument when instantiating a new FormGroup, for some reason the FormBuilder syntax for creating a FormGroup does not allow you to provide a validator. So if you need to add validation to a FormGroup object, instantiate the object ahead of time and then reference it in the FormBuilder construction (just like I did with my FormArray).

Saturday, September 24, 2016

Learning Angular 2: Populating Properties With the Constructor And Using Promise.all

Version 0.0.5 of my GuildRunner sandbox Angular 2 application was focused on updating the model object graph of the application (mainly to provide more opportunities for exploring forms), which included the following changes:

  • Removed the Address domain class and replaced it with a Location object containing traditional, basic address properties. 
  • Created a Person class containing properties such as first name and last name as well as a "residence" property that is an instance of Location.
  • Added the concept of "Chapter", where each Guild has a number of geographically-based Chapters.  Each Chapter domain class is associated with a Guild and has a "location" property that is an instance of ChapterLocation, another new domain class that extends Location and contains properties like "floors" and "entryPoints".
  • Removed the Member domain class and replaced it with ChapterMember, which extends the Person class.
  • Simplified the Guild domain class.
  • Created new master list view for the Chapters and ChapterMembers and added them to the navigation bar.
During the process of refactoring the domain classes, I refined my approach to setting the domain class properties via the constructor.  Previously, I simply declared my properties (with a data type where appropriate) and used ternary operations to set the individual property values like so:

// domain/guild.ts
export class Guild {
  id: number;
  name: string;
  email: string;
  incorporationYear: number;

  constructor( guildData?: any  ) {
    if( guildData ) {
      this.id = guildData.id ? guildData.id : null ;
      this.name = guildData.name ? guildData.name : null ;
      this.email = guildData.email ? guildData.email : null;
      this.incorporationYear = guildData.incorporationYear ? guildData.incorporationYear : null;
    }
  }

It worked, but it would get tedious and hard to read with larger property sets. And having default values set by conditional logic isn't very "default-like" behavior. Compare that to the constructor method I wrote for the new Chapter domain class:


// domain/chapter.ts
import { ChapterLocation } from './chapter-location';

export class Chapter {
  id: number = null;
  guildId: number = null;
  name: string = null;
  location: ChapterLocation = new ChapterLocation();
  headChapter: boolean = false;
  founded: Date = null;
  defenses: Number[] = [];

  constructor( chapterData?: any ) {
    if( chapterData ) {
      let props = Object.keys( this );
      for( let p in props ) {
        if( chapterData[ props[p] ] ) {
          if( props[p] == 'location' ) {
            this.location = new ChapterLocation( chapterData.location )
          } else {
            this[ props[p] ] = chapterData[ props[p] ];
          }
        }
      }
    }
  }

}

It's worth noting that the technique of looping through the properties via Object.keys() only works if we have default values set for each property: properties without values are considered undefined and aren't retrieved by Object.keys().

I also realized that my new master lists of guild chapters and chapter members would look more realistic if they included related data, so I could for example denote the guild and chapter each member belonged to.

Under real-world conditions, a REST request for chapter members would probably include the related guild and chapter data in the returned data. But simulating that kind of all-inclusive data set with the in-memory web API is a bit problematic, because any changes I made to the Guild or Chapter data via the API wouldn't be reflected in the ChapterMember data set. So to avoid that problem, I needed to retrieve the full list of guilds and chapters along with the full list of members.

In Angular 1x, when you needed to collect data returned by multiple promises before proceeding, you could use $q.all() to combine all of the promise results into an array that would become available only after all of the promises returned successfully.  I was able to do the same thing with Promise.all():


// members-master/members-master-component.ts
export class MembersMasterComponent implements OnInit {

  members: ChapterMember[] = [];
  chapters: any = {};
  guilds: any = {};

  constructor(
    private memberService: MemberService,
    private chapterService: ChapterService,
    private guildService: GuildService
  ) { }

  ngOnInit() {

    Promise.all( [ //the array of service calls that return Promises
      this.memberService.getMembers(),
      this.chapterService.getChapters(),
      this.guildService.getGuilds()
    ]).then( (results:Promise[]) => {
      results[0]['data'].forEach( memberData => {
        this.members.push( new ChapterMember( memberData ) )
      });
      results[1]['data'].forEach( chapterData => {
        this.chapters[ chapterData.id ] = chapterData
      });
      results[2]['data'].forEach( guildData => {
        this.guilds[ guildData.id ] = guildData
      });
    });

  }

}

Each service method call returns an instance of my HttpResponse class where the "data" property is populated with the array of member, chapter, and guild data returned by the in-memory web API, and the code loops over each array. Note that the code doesn't access the "data" property via dot-notation: when I tried using dot-notation ("results[0].data") I got a compiler error stating that "data" was not a property of the object. Not sure why: I probably have it coded in such a fashion that TypeScript doesn't recognize the results item as an HttpResponse despite the data typing.

Note that only the member data gets translated into instantiated domain class objects (ChapterMember objects): for the chapters and the guilds, I simply need to capture them such that they can be referenced in the component view:


<-- members-master/members-master.component.html -->
<h3>Chapter Members</h3>
    <table class="table table-bordered table-striped">
      <thead>
      <tr>
        <th>ID</th>
        <th>First Name</th>
        <th>Last Name</th>
        <th>Guild</th>
        <th>Chapter</th>
        <th>Active?</th>
      </tr>
      </thead>
      <tbody>
      <tr *ngFor="let member of members">
        <td>{{member.id}}</td>
        <td>{{member.firstName}}</td>
        <td>{{member.lastName}}</td>
        <td>{{guilds[chapters[member.chapterId].guildId].name}}</td>
        <td>{{chapters[member.chapterId].name}}</td>
        <td>{{member.isActive ? 'Yes' : 'No'}}</td>
      </tr>
      </tbody>
    </table>

Again, this is not the ideal way of gathering related data for a master display of records, but in this case it gets the job done.

Monday, September 5, 2016

Learning Angular 2: Experiment in Validating a Template-Driven Forms

Version 0.0.4 of my GuildRunner sandbox Angular 2 application is now available.

In an earlier post, I shared my thoughts after working through the examples on the official documentation page for template-driven forms.  I came away underwhelmed with the features designed to help with validating the form input:

  • The classes Angular adds to form controls to indicate the control state are based on interactions with the DOM and don't reflect the state of the model data attached to the control (for example, once a form control is marked as "dirty", changing the control value back to its original value does not re-mark it as "clean").

  • Some basic form control attributes (like "required") could be used to set validation constraints that Angular would use to toggle the valid/invalid class on the control, but not the validation attributes introduced in HTML5, and there was no documentation about what worked and what didn't.

  • Even when Angular could toggle the valid/invalid class correctly, that only indicated that the form control should be considered invalid, not why it was invalid.

(The change log for the recently released RC6 version of Angular 2 hints that some of these issues may have been addressed.)

So when I decided that the next feature of GuildRunner would be a detail component for adding or editing a guild, I knew figuring out my strategy for validating the form would be a big part of the work involved.  What I came up for this release is a rough, first draft of an approach where the form takes its validation cues from validation logic and state data stored in the component.  There is a lot of room for improvement should I decide that this approach is viable and a reasonable alternative to the other method of generating and managing forms in Angular 2 (dynamic forms).

I started by making a few changes to my guild data and my Guild domain class.  I added two new properties:  "email" and "incorporationYear" (the year the guild was incorporated).  I also refactored the Guild constructor to make the object literal argument and all of properties optional:

//domain/guild.ts
...
constructor( guildData?: any  ) {
    if( guildData ) {
      this.id = guildData.id ? guildData.id : null ;
      this.name = guildData.name ? guildData.name : null ;
      this.email = guildData.email ? guildData.email : null;
      this.incorporationYear = guildData.incorporationYear ? guildData.incorporationYear : null;
...
I then created the initial GuildsDetailComponent and defined two routes to reach it from the GuildsMasterComponent, one route for editing and one for adding:

//app.routing.ts
{ path: 'guilds/:id', component: GuildsDetailComponent}, //Edit route
{ path: 'guild', component: GuildsDetailComponent },  //Add route
...I thought about just having the one route with the parameter value, where a parameter value of 0 would be used to trigger the add behavior, but I wanted to avoid that if I could. Having a route that didn't provide a parameter meant I had to handle that in the ngOnInit method of GuildsDetailComponent:

//guilds-detail.component.ts
...
export class GuildsDetailComponent implements OnInit {

  guild: Guild;
  ...
  ngOnInit() {
      this.route.params.forEach( (params: Params ) => {
        let id = params['id'] ? +params['id'] : null ;  //converts param string to number
        if( id ) {
          //Ask the GuildService for a Guild object instantiated with data for that record
        } else {
          this.guild = new Guild();  //Instantiate a "blank slate" Guild object
        }
...
I created a bare-bone GuildService method to provide GuildsDetailComponent with a populated Guild object for the selected guild, then started working on the form and the form logic. I tried a few different approaches before settling on the format in the current release.

The component HTML starts off with a header block:

<!-- guilds-detail.component.html -->
<div class="row">
  <div class="col-md-12">
    <h6 *ngIf="!guild && !serviceErrors">Loading...</h6>
    <h3 *ngIf="guild">{{(guild.id ? 'Edit' : 'Add' )}} {{(guild.name ? guild.name : 'Guild')}}</h3>
  </div>
</div>
...
The <h3> interpolation logic makes sure we end up with an appropriate title based on the situation, and the ngIf directives make sure we display the appropriate content under the appropriate conditions.

The form is styled with Bootstrap and contains text inputs for the name, incorporationYear, and email address for the guild.  Except for the attributes that are specific to the guild data bound to each control, the HTML is essentially the same:

<!-- guilds-detail.component.html -->
...
<div class="form-group">
    <label for="name" class="col-md-2 control-label">Name:</label>
    <div class="col-md-6">
      <input id="name" type="text" class="form-control" [(ngModel)]="guild.name" (change)="checkValidity( 'name' )" (keyup)="checkFix( 'name' )" name="name" #name="ngModel" />
      <div *ngIf="status.name.errors.length" class="alert alert-danger">
        <ul>
          <li *ngFor="let error of status.name.errors">
            {{error}}
          </li>
        </ul>
      </div>
    </div>
</div>
So [(ngModel)] binds this control to the name property of the Guild object of the component, and checkValidity() and checkFix() are executed in response to the change and keyup events emitted by the control. Any errors regarding this input are managed via an array of errors attached to the "name" property of a simple "status" object literal defined in the component.

All of the validation work occurs within the checkValidity() method of the component:

//guilds-detail.component.ts
...
checkValidity( propertyName: string ) {

      let yearRegEx = /[1-2]\d{3}$/;
      let emailRegEx = /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,3}$/;

      switch( propertyName ) {
        case 'name':
          this.status.name.errors = [];
          if( !this.guild[ propertyName ] ) {
            this.status.name.errors.push( 'The name field is required.' );
            break;
          }
          if( this.guild[ propertyName ].length < 5 ) {
            this.status.name.errors.push( 'The guild name is too short.' );
          }
          break;
        case 'incorporationYear':
          this.status.incorporationYear.errors = [];
          if( !this.guild[ propertyName ] ) {
            this.status.incorporationYear.errors.push( 'The year of incorporation is required.' );
            break;
          }
          if( isNaN( +this.guild[ propertyName ] ) ) {
            this.status.incorporationYear.errors.push( 'The incorporation year must be a number.' );
          } else {
            if( !yearRegEx.test( this.guild[ propertyName ] ) ) {
              this.status.incorporationYear.errors.push( 'The incorporation year must a valid 4-digit year (1xxx or 2xxx).' );
            }
          }
          break;
        case 'email':
          this.status.email.errors = [];
          if( !emailRegEx.test( this.guild[ propertyName ] ) ) {
            this.status.email.errors.push( 'Please enter a valid email address.' );
          }
          break;
      }

}
So every time one of the text inputs emits a change event, checkValidity() clears the existing validation error array for that control/guild property and executes the relevant validation logic, re-populating that error array with any validation issues that still exist.  And based on the component HTML, any such errors are displayed in an alert area beneath the text input.

The change event for the text inputs doesn't fire until the form input loses focus, which is fine when the user is first inputing data into the form control because you don't want any minimum length validation rules (like the one for the guild name) applied before they finish typing.  But that does mean that if a validation error is displayed, it won't disappear until after the user has modified the input and then exited the input again.  That's not a terrible experience, but I wanted to ensure the user doesn't leave the input again and still end up with an invalid value.  That's why the keyup event executes the checkFix() method in the component.

//guilds-detail.component.ts
...
checkFix( propertyName: string ) {
    if( this.status[ propertyName ].errors.length > 0 ) {
      this.checkValidity( propertyName );
    }
  }
The checkFix() method checks the validity with every keystroke until the validation issues have all been resolved. And that point, one would hope the user wouldn't enter more text in the input that would make the content and the control invalid again.

The rest of the form and form logic is pretty straightforward.  The form concludes with three buttons:
  • The "Cancel" button, which simply navigates back to the table list of guilds.
  • The "Save" button, which is disabled as long as there are any validation errors and when clicked executes checkValidity() for every property contained in the "status" object literal of the component (so for all of the form items).
  • The "Clear Form" button, which sets the name, incorporationYear, and email properties of the guild object to null and clears all of the previous validation errors, providing a clean slate for data entry.
The end result is a form that behaves like this:

In terms of the behavior, I'm pleased with the result, but the implementation could be better.  Most if not all of the validation configuration should belong in the Guild object rather than the component, the repetition of the template code for each form control suggests I could probably create a custom component to encapsulate the shared behavior, and I need to try applying the same technique to more complex forms to see if the implementation holds up under different scenarios.

Other notes regarding this release:
  • I created an HttpResponse domain class to use to pass data back from the service methods to the component methods that called them.  I did that in order to create consistency in how the response data from HTTP calls was packaged and presented to the calling methods, whether the HTTP call returned successfully or returned with a HTTP error code.

  • I wanted to account for the scenario where a user bookmarked the application URL that would pull up a particular Guild in the GuildsDetailComponent, but that guild no longer existed in the data.  So if the GuildService getGuild() method is executed in that scenario, the 404 error response will populate the HttpResponse object returned to the GuildsDetailComponent with an error message that no guild matching that id number exists, and that will end up being displayed instead of the form.

 

Tuesday, August 23, 2016

Learning Angular 2: Upgrading to Angular 2 RC5

Version 0.0.3 of my GuildRunner sandbox Angular 2 application is now available.  All of the differences between this version and the previous version (minus the updates to the version number and the README file) are changes made to upgrade the application to use Angular 2 RC5 (release candidate 5).

While there were some changes to the router/routing syntax, the biggest change that comes with RC5 is the introduction of Angular modules and the @ngModule decorator.  There is a long documentation page about Angular modules in the official developer guide, but essentially Angular modules allow you to bundle sets of shared injectable dependencies into a single file that provides those dependencies "downstream".

For example, prior to the upgrade my MainNavigationComponent received the directives needed for routing (like RouterLink) via the "directives" metadata property (which also meant it had to be imported):


//main-navigation.component.ts (previous version)
import { ROUTER_DIRECTIVES } from '@angular/router';
...
@Component({
  ...
  directives: [ ROUTER_DIRECTIVES ]
})

As another example, the GuildsMasterComponent received the GuildService for its constructor method via the "providers" metadata property:


//guilds-master.component.ts (previous version)
import { GuildService } from '../guild.service';
...
@Component({
  ...
  providers: [ GuildService ]
})

Now both of those dependencies are declared in the new application-level Angular module - app.module.ts:


//app.module.ts
...
import { routing } from './app.routing';
import { GuildService } from './guild.service';
...
import { SandboxModule } from './sandbox/sandbox.module';
...
@NgModule({
  imports:      [
    BrowserModule,
    HttpModule,
    routing,  //Provides the routing directives as well as the route definitions
    SandboxModule
  ],

  declarations: [
    AppComponent,
    VersionComponent,
    MainNavigationComponent,
    HomeComponent,
    GuildsMasterComponent
  ],

  providers: [
    { provide: XHRBackend, useClass: InMemoryBackendService }, // in-mem server
    { provide: SEED_DATA,  useClass: InMemoryDataService },     // in-mem server data
    VersionService,
    GuildService //Provides the GuildService downstream
  ],

  bootstrap:    [
    AppComponent
  ],
})

Because the MainNavigationComponent and GuildsMasterComponent are included in the module via the "declarations" block, they are part of the feature bundle of this module, and so they have access, via dependency injection, to the routing and GuildService dependencies without the need for the "directives" or "providers" metadata properties of the @Component.

Note the four properties in this @ngModule decorator. The "declarations" property is where you list all of the components, directives, and custom pipes used in your module: anything your templates need in order to operate (example: the inclusion of the MainNavigationComponent in the declarations allows the AppComponent template to understand how to render the "<app-main-navigation>" tag in the AppComponent HTML). The "providers" property is where you list your module services (things that would be injected into your component as a constructor argument).

The "imports" property is where you list other modules that provide functionality (services, directives, etc.) to your feature module. Some of the modules may be Angular library modules, such as the required BrowserModule or the HttpModule needed for performing HTTP operations. But it can also include other modules in your application. Note the inclusion of the "SandboxModule" in this example:


//app.module.ts
import { SandboxModule } from './sandbox/sandbox.module';
...
@NgModule({
  imports:      [
    ...
    SandboxModule
  ],

That is a separate Angular module file dedicated to the "sandbox" feature area of my application:


//sandbox/sandbox.module.ts
import { NgModule }       from '@angular/core';
import { sandboxRouting } from './sandbox.routing'
import { GuildListComponent } from "./guild-list/guild-list.component";
import { SandboxService } from './sandbox.service';

@NgModule({
  imports: [
    sandboxRouting
  ],

  declarations: [
    GuildListComponent
  ],

  providers: [
    SandboxService
  ]
})

export class SandboxModule {}

This module encompasses the components, services, and the routing related to the sandbox feature area of the application, and it's integrated with the rest of the application simply by the fact that it's declared in the "imports" property of the main application Angular module. Note that it doesn't contain the fourth property seen in app.module.ts: the "bootstrap" property is mainly for declaring the top-level component of a given module, something the sandbox feature area doesn't have.

So the introduction of Angular modules adds a new organizational construct to Angular 2 and cuts down on typing since there's no need to add "directives" and "providers" properties to your components in order to perform dependency injection.

However, there is one small caveat, best explained by example. Even though my app.module.ts file declares the GuildService in its array of providers, and I no longer need to use the "providers" metadata property on my GuildsMasterComponent, I still need to import the GuildService:


//guilds-master.component.ts (new version)
import { GuildService } from '../guild.service';
...
export class GuildsMasterComponent implements OnInit {

  guilds: Guild[] = [];

  constructor( private guildService: GuildService ) { }

This puzzled me, and in perusing some of the updated documentation and tutorial examples I couldn't find an explanation for why that import was still necessary if the GuildsMasterComponent was getting its instance of the GuildService from the application Angular module.

But then I looked at the JavaScript being generated from the guilds-master.component.ts file. Here are the relevant lines from that JavaScript file, with the significant lines followed by comments:


//guilds-master.component.js
...
var guild_service_1 = require('../guild.service');  //Significant line #1
...
GuildsMasterComponent = __decorate([
        core_1.Component({
            moduleId: module.id,
            selector: 'app-guilds-master',
            templateUrl: 'guilds-master.component.html',
            styleUrls: ['guilds-master.component.css']
        }), 
        __metadata('design:paramtypes', [guild_service_1.GuildService]) //Significant line #2
    ], GuildsMasterComponent);
    return GuildsMasterComponent;

Those two significant lines are generated by Angular compiler based on the argument declaration of the GuildsMasterComponent constructor. If you try to type the "guildService" argument of the constructor as another data type (like "any"), the compiler won't know what object/export it's supposed to use. And you can't set the "guildService" argument to type GuildService without importing GuildService so that the TypeScript compiler can recognize the data type.

Two other tidbits:

  • When I initially created the separate sandbox Angular module (sandbox.module.ts), I did not create a separate routing file with a route configuration for the single sandbox route:  that route was still part of the application Angular module and the app-level routing.  But when I ran the application, that generated an error message that my single sandbox component was "part of the declaration of 2 modules."  Fortunately I found a Stack Overflow post that pointed out the need for separating routing configurations.

  • In an earlier blog post, I noted how my IntelliJ IDE would automatically add the "import {} from ..." statement for any component I added to my router configuration via auto-complete (where IntelliJ would provide me a list of options as I typed the component name, and I could select the one I wanted from the list using the Tab key).  I was happy to see that same convenience feature at work as I added components to the "declarations" list of my app module.

Saturday, August 20, 2016

Augury: An Elegant Tool For Inspecting Angular 2 Applications

In episode 105 of the Adventures in Angular podcast, the panel spoke with one of the developers behind an open-source development tool called Augury. Augury is a Chrome extension that adds an "Augury" tab to the Chrome Development Tools panel, and that tab displays real-time information regarding Angular 2 activity on the current web page.  This information includes:
  • A "Component Tree" list of all of the Angular components and directives currently displayed on the pages.  Actions taken on the page that alter the components included on the page or change the state of a component are highlighted and updated in the Component Tree in real time.

  • A list of properties and providers associated with the selected component or directive in the Component Tree.  For example, you could select a form input and see the current form control status values (dirty, pristine, valid, etc.)

  • A "View Source" link associated with the selected component in the Component Tree, which when clicked will display the source code of the component's TypeScript file in the "Sources" tab of the Chrome Developers Tool.

  • An Injector Graph that displays a diagram of the dependenices injected into the currently selected component.

  • A Router Tree that displays a diagram of all of the routes defined in the application (using this feature does require injecting the Router in the root application component as explained on the Augury GitHub page).

  • A search tool for locating a desired component or directive element.

    • Related to this, Augury adds a custom identifier attribute to each component and directive it displays in the Component Tree, with the id value denoting where the item exists in the hierarchy and its place amongst its sibling elements, making it easy to find, say, link 5 out of 12 in ComponentX

To me, this is a no-brainer, must-have tool for existing and would-be Angular 2 developers.  Install the extension, and then take it for a spin with the "kitchen sink" demo application hosted by the Augury team.  

Wednesday, August 17, 2016

Learning Angular 2: Adding a Master Guild List Component To My Sandbox Application

I recently released version 0.0.2 of my GuildRunner sandbox Angular 2 application.  Changes made during this release include:

  • The addition of a Bootstrap-powered navigation bar (main-navigation.component.ts) which necessitated adding CDN calls for jQuery and Bootstrap JS (index.html).
  • The addition of Angular 2 routing (main.ts, app.routing.ts).
  • The creation of guild data for use by the in-memory web API (db/guilds.ts).
  • The creation of Guild, Address, and Member domain classes to be populated with the guild data (the address.ts, guild.ts, and member.ts files in the "domain" folder) via the GuildService (guild.service.ts).
  • The creation of a master view that displays data from a list of Guild objects within a table (guilds-master.component.ts).
  • The creation of a "sandbox" area of the application where I can keep experimental and diagnostic features (the "sandbox" folder). 

Some lessons learned during the coding of this release:

The in-memory web API has limitations

The in-memory web API is currently limited to mimicking a shallow data graph. It allows you to mock the following types of REST calls:

  • app/guilds (to retrieve all guilds)
  • app/guilds/1 (to retrieve the guild with an id of 1)
  • app/guilds/?name=Blacksmiths (to retrieve the guild or guilds based on the query string)

...but you cannot simulate deeper REST calls:

  • app/guilds/1/members/1 (retrieving the member with id of 1 from guild 1)

For this application at this particular point, it's not a big deal, but I will probably be looking at alternatives methods for faking HTTP calls at some point down the line.

Instantiating domain model classes

In the Tour of Heroes tutorial, the instructions have you create a Hero class with properties for the id and name of the hero. Later, that class is used to declare a component variable with a data type of an array of Heroes:


heroes: Hero[];

...which is then populated with the hero data, an array of object literals:


[
  {id: 11, name: 'Mr. Nice'},
  {id: 12, name: 'Narco'},
  ...
]

...like so:


this.heroService.getHeroes().then(heroes => this.heroes = heroes);

From a coding standpoint, declaring the "heroes" variable as an array of Hero objects ensures that another developer cannot use code to populate that variable with anything but Hero objects, but that declaration is meaningless at runtime. Doing the same thing with my guild data:


//Populates the "guilds" variable with the raw retrieved data (array of object literals)
export class GuildsMasterComponent implements OnInit {

  guilds: Guild[];
  constructor( private guildService: GuildService ) { }

  ngOnInit() {
    this.guildService.getGuilds().then( guilds => this.guilds = guilds )
  }
}

...results in the "guilds" variable being populated with the raw array of guild object literals, each with an address object literal and an array of member object literals. But that's not what I wanted: I wanted an array of Guild objects with included Address and Member objects.

So I wrote the code to instantiate the desired objects, populating the property values via the constructor method:


//guilds-master.component.ts
...
import { Guild } from '../domain/guild';
...
export class GuildsMasterComponent implements OnInit {

  guilds: Guild[] = [];
  
  constructor( private guildService: GuildService ) { }

  ngOnInit() {
    this.guildService.getGuilds().then( guilds => {
      guilds.forEach( guild => {
        this.guilds.push( new Guild( guild ) )
      })
    } );
  }
}

//guild.ts
import { Address } from './address';
import { Member } from './member';

export class Guild {
  id: number;
  name: string;
  expenses: number;
  revenue: number;
  profit: number;

  address: Address;
  members: Member[] = [];

  constructor( guildData:any ) {
    this.id = guildData.id;
    this.name = guildData.name;
    this.expenses = guildData.expenses;
    this.revenue = guildData.revenue;

    this.profit = this.calculateProfit();

    this.address = new Address( guildData.address );

    guildData.members.forEach( member => {
      this.members.push( new Member( member ) );
    }, this );

  }

  calculateProfit() {
    return this.revenue - this.expenses;
  }

}

Providing my master view with an array of Guild objects allowed me to display the profit of each guild in addition to the raw guild data provided by the in-memory web API.

The currency pipe

This release marked my first time using one of the built-in Angular 2 pipes, though it was pretty similar to my experiencing using the built-in filters in Angular 1.

I was a tad surprised that the default CurrencyPipe settings would result in the number being prefixed with "USD" rather than a dollar sign. But a quick glance through the CurrencyPipe documentation gave me the settings I wanted and instructions on how to further control the output with the DecimalPipe:


<td align="right”>{{guild.revenue | currency:'USD':true:'.2-2' }}</td>

In cases where you wanted your application to support internationalization, I imagine you could use a component variable to dynamically affect the currency code:


<td align="right”>{{guild.revenue | currency:currencyCode:true:'.2-2' }}</td>

 

Wednesday, August 10, 2016

IntelliJ, Angular CLI, and Indexing

As I started working on my Angular CLI-managed Angular 2 project, I discovered that making code changes while Angular CLI was either serving my application or waiting to re-execute unit tests would cause my IntelliJ IDE to start re-indexing my project files.  Each indexing run took several minutes and during that time IntelliJ was slow to respond to my attempts to edit and interact with the code files.

I solved this performance issue by selecting the "Project Structure" / "Project Settings" menu item, selecting "Modules", and marking the following folders as "Excluded" on the "Source" tab:

  • dist
  • tmp
Those two folders are created and updated by Angular CLI automatically while testing and serving the application: there's no benefit in having the IDE index them.

Monday, August 8, 2016

Learning Angular 2: Creating My First Sandbox Web Application

While there is still a lot out there for me to read regarding Angular 2, I tend to learn by coding and solving problems.  Even though there are a few aspects of Angular 2 that are in flux at this time (like forms), I feel that I can start writing an application without much fear that I'd have to go back and redo things because the API has changed.

So I've created my first "sandbox" Angular 2 application where I can practice writing Angular code and figure out ways to accomplish specific application tasks with Angular 2.  I'm going to keep a copy of the code up on GitHub and release milestones in my development so that I have a historical picture of the development and so I can potentially backtrack and create different solutions to a given problem.  Plus, it will allow anyone to pull down a tagged version on their own machine to look at the code.

My first sandbox is an application called "GuildRunner".  My plan is that it will be an application for managing a fictional collection of trade guilds, and so I can use it to exploring dealing with common application issues like authentication and authorization, data relationships, and searching.  But I wanted to start by simply creating the foundation for the application structure and getting it up and running.

So I started by creating the repo in GitHub, and then cloned the repo into a new IntelliJ IDEA project via the IntelliJ option for creating projects via GitHub.  I then opened a command prompt in the project directory and invoked the Angular CLI command "ng init" to create the starting project files: I was pleased that the command let me decided whether or not to overwrite the README.md file cloned from GitHub.  Another nice thing about the CLI-generated file I hadn't noticed before:  the .gitignore file is configured to ignore the IntelliJ-specific files as well as the node_modules and typings folder during commits, which is nice.

At that point, I had a basic, single-component app that I could run with the "ng serve" command of Angular CLI.  But I wanted to use the in-memory web API (at least initially) to provide the data for the application as if it was interacting with a server and a database, so I needed to reconfigure the application to utilize that feature.  The details of that reconfiguration ended up as a separate blog post: Adding the In-Memory Web API to a SystemJS-based Angular CLI Application.

In the Tour of Heroes example of using the in-memory web API, the mock data was defined/written out within the InMemoryDataService createDB() method.  Since I plan on creating a fair amount of mock data, I created a "db" folder under the "app" folder that would house all the modules that would export the data collections.  I then created my first bit of mock data: a single version record.


//src/app/db/version.ts

let version = [
  {id: 1, name: '0.0.1'}
];

export { version }

...and provided that to the InMemoryDataService via an import:


//src/in-memory-data.service.ts

import { version } from './db/version';

export class InMemoryDataService {
  createDb() {
    return { version };
  }
}

The purpose of the version record was to have some data to display on the main application page that would confirm that the in-memory web API was working (and also confirm the version of the sandbox application I was working with). So with the Tour of Heroes code as a guide, I created a VersionService to retrieve the version data and a VersionComponent to display it:


//src/app/version/version.service.ts

import { Injectable } from '@angular/core';
import { Http } from '@angular/http';

import 'rxjs/add/operator/toPromise';

@Injectable()
export class VersionService {

  private versionUrl = 'app/version'

  constructor( private http: Http ) { }

  getVersion() {
    return this.http.get(this.versionUrl)
      .toPromise()
      .then(response => response.json().data )
      .catch(this.handleError);
  }

  private handleError(error: any) {
    console.error('An error occurred', error);
    return Promise.reject(error.message || error);
  }
}

//src/app/version/version.component.ts

import { Component, OnInit } from '@angular/core';
import { VersionService } from './version.service';

@Component({
  moduleId: module.id,
  selector: 'app-version',
  templateUrl: 'version.component.html',
  providers: [
    VersionService
  ]
})
export class VersionComponent implements OnInit {

  versionNumber = '-.*.-';

  constructor( private versionService: VersionService ) { }

  ngOnInit() {
    this.versionService.getVersion().then( versions => this.versionNumber = versions[0].name );
  }

}

<-- src/app/version/version.component.html -->

<p><strong>Version:</strong> {{versionNumber}}</p>

Then (after adding Bootstrap to the project and adding some Bootstrap layout containers), I added the VersionComponent as a sub-component of the AppComponent:


//src/app/app.component.ts

...
@Component({
  ...
  directives: [
    VersionComponent
  ]
})

<-- src/app/app.component.html -->
<div class="container">
  <div class="row">
    <div class="col-md-10">
      <h1>{{title}}</h1>
    </div>
    <div class="col-md-2 text-right">
      <app-version></app-version>
    </div>
  </div>
</div>

Once all of that was done, I could run my application using "ng serve" and a moment after the page loaded I could see the version number.

I finished up this version of the sandbox by updating the current set of unit and end-to-end (e2e) test files such that they would pass. Previous experience with e2e testing let me update the single e2e test pretty easily, but getting the minimalist unit tests to work took some trial-and-error, and I don't yet have a clear sense of how to set up the unit tests such that the component under test has all the dependencies (or mocks of the dependencies) it needs.

The release of the GuildRunner sandbox that contains the application foundation code and the changes described above can be found on the GuildRunner GitHub repo as release 0.0.1:

https://github.com/bcswartz/angular2-sandbox-guildrunner/releases/tag/0.0.1 

Instructions for running the sandbox on your own machine via Angular CLI can be found on the main page of the GitHub repo.

Thursday, August 4, 2016

Adding the In-Memory Web API to a SystemJS-based Angular CLI Application

8/6/2016 EDIT: On 8/2/2016, the Angular CLI was updated to reflect the fact that the CLI was being refactored to use Webpack instead of SystemJS.  Currently, an npm install of Angular CLI will still give you a version that uses SystemJS, and the following instructions apply to that SystemJS version.

As of version 1.0.0-beta.10, the Angular CLI tool does not provide an option for generating a base Angular 2 application that includes the in-memory web API, which is a tool that lets developers simulate the return of data from HTTP calls.  I figured adding the in-memory web API to my CLI-generated application was just a matter of mimicking how the HTTP lesson in the Tour of Heroes tutorial did it, but it was a bit more involved than that. Here's how you do it.

(From here on out, I'm going to abbreviate "in-memory web API" as IMWA for the sake of brevity. Someone needs to come up with a shorter, cooler name for this tool.)

First, you add the IMWA as a dependency in the package.json file:


"dependencies": {
  ...
  "angular2-in-memory-web-api": "0.0.14"
}

...and then run "npm install" from the command prompt in the directory containing the package.json file to download the IMWA node module (I tend to delete my entire "node_modules" folder first just to make sure everything installs fresh).

Then you add the neccessary imports to your main.ts file and use those imports in the bootstrap() method:


import { XHRBackend } from '@angular/http';

import { InMemoryBackendService, SEED_DATA } from 'angular2-in-memory-web-api';
import { InMemoryDataService }               from './app/in-memory-data.service';

import { HTTP_PROVIDERS } from '@angular/http';

...

bootstrap(AppComponent, [
  HTTP_PROVIDERS,
  { provide: XHRBackend, useClass: InMemoryBackendService },
  { provide: SEED_DATA, useClass: InMemoryDataService }      
]);

Then create a in-memory-data.service.ts file in your src/app directory with some temporary placeholder data:


export class InMemoryDataService {
  createDb() {
    let tempData = [
      {id: 1, name: 'foobar'}
    ];

    return { tempData };
  }
}

Up to this point, all of the setup is nearly the same as it was for the Tour of Heroes tutorial, but the final changes needed are CLI-specific.

When you use the CLI's "ng serve" command to compile and run the application on your local machine, the CLI generates a "dist" directory with all of the necessary files to execute the application. The "dist" directory consists of:

  • The index.html and global configuration files (main.js and system-config.js) in the root of the "dist" folder.
  • The "app" folder which contains the rest of the Angular 2 files specific to your application, from the main component file on down.
  • A "vendor" directory that contains the files from the various node modules needed to run the application, such as the core Angular 2 library files.

The IMWA needs to be included as a separate folder under that "vendor" directory in order for the IMWA to be available to your application.

The "angular-cli-build.js" file in the root of your project filespace (in the same directory as the package.json) controls which node modules make it into the build (the "dist" folder). Add the IMWA to the array of modules like so:


vendorNpmFiles: [
  ...
  'angular2-in-memory-web-api/*.+(js)'
]

The "*.+(js)" syntax ensures that all of the ".js" files in the IMWA node module are copied to the appropriate folder ("angular2-in-memory-web-api") under "vendor" (at this time, there are no ".js.map" files in the IMWA module).

Finally, you need to make sure the IMWA module in the "vendor" directory is loaded by SystemJS along with the regular Angular modules by adding the IMWA to the package configuration in the "system-config.ts" file in the "src" directory of your project:


/** Map relative paths to URLs. */
const map: any = {
  'angular2-in-memory-web-api': 'vendor/angular2-in-memory-web-api'
};

/** User packages configuration. */
const packages: any = {
  'angular2-in-memory-web-api': { main: 'index.js', defaultExtension: 'js' },
};

That should do the trick: run your app using "ng serve", open up the browser console, and confirm that there are no 404 error messages regarding the IMWA.

Sunday, July 31, 2016

IntelliJ 2016.2 and Angular 2 Support

I realized today that the latest update (version 2016.2) for my IDE of choice - IntelliJ IDEA (Ultimate version) - includes additional support for Angular 2:

  • A collection of live templates for Angular 2 files such as components and services.
  • A better understanding of template syntax.
  • The ability to create a new IntelliJ project via the Angular CLI tool.
So I downloaded and installed the update, but that alone wasn't sufficient to access these new features.  Turns out I had never installed the "AngularJS" plugin (I remember coming across it before, just hadn't installed it).

Once I installed that plugin and restarted IntelliJ, I could select File -> New -> Project from the menu tree, and "AngularJS" (for Angular 1 projects) and "Angular CLI" were new options listed under the "Static Web" project option.  I went ahead and chose "Angular CLI", and IntelliJ invoked the global install of Angular CLI on my laptop and executed the "ng-init" command to create the application structure and foundation files for a new Angular 2 project.

Inside the Angular project, I could create a new component using live templates by creating a new empty TypeScript file, hitting Control/Command-J to insert a live template, typing "ng2-component" until it was the selected template and hitting the Tab key.  The template then lets you tab through the update points in the template so you can enter the directive, template, and component names you want.

Very cool, but I think I would probably end up creating my components using Angular CLI from within the Terminal window in the IDE, because the CLI can generate the full set of files for a given component (the TypeScript file, the template HTML file, the CSS file, and the unit test file).  It also looks like the templates that contain code related to routing need updating.

Still, it's always nice when your IDE adds new features to making your coding a little easier.

First Impressions of Angular CLI

Before creating a demo Angular 2 project of my own from scratch, I decided to play with Angular CLI, the command line tool provided by the Angular team to help streamline Angular 2 development.

There are a number of posts and articles out there about Angular CLI, so I'll only share a few personal observations:

  • The "--help" option for displaying documentation for the overall list of commands or individual commands is well executed:  much more useful and readable than most command line tool documentation.

  • I really like the "dry-run" option provided with the commands that generate the application skeleton and config files.  It lets you see a list of the files and folders that would otherwise be created by the command without actually creating them, giving you an idea of what to expect.

  • The application skeleton structure is a bit different from the structure used in the Quick Start and Tour of Heroes tutorial, moving the "app" directory under an "src" directory.  It does this to make room for a "dist" directory parallel to the "src" directory where it can output runtime files for testing and environment-specific distribution builds.  I found it interesting that it places the "main.ts" file in that "src" directory instead of the "app" directory.

  • I liked how the default development distribution build retains the separate .js and .js.map files for the project code files, while the production build concatenates those files and generally packages your assets to make them more efficient.

  • The "ng generate" command is most useful for generating new components.  The generated component contains the appropriate @angular/core imports and @Component() metadata, contains an empty constructor method, and implements ngOnInit.  Option flags used with the generation command can customize certain aspects of the generated component, such as whether the component uses external HTML and CSS files (the default) verses inline template and inline styles, and whether all of the component assets are bundled in a separate directory.  The other files you can generate with the command are mostly empty shells (although generated service files do include the @Injectable() decorator).

  • I like that the generated components use the module.id technique to handle relative pathing for the templateUrl and styleUrls properties.

  • The CLI documentation refers to the types of files you can generate with "ng generate" as "blueprints".  I hope that means that there will one day be an option to add your own personal blueprints into the mix.

  • It's interesting that "ng test" starts by creating a development build in the "dist" folder before performing the tests...presumably because the tests are run against that folder.  I'm sure there's a reason for doing it that way (making sure everything works after packaging?), but it makes the startup time for testing slow.  On the flip-side, once it's started it watches for file changes and re-tests on the fly, so if your coding process involves running unit tests in the background all the time the start-up time penalty is a one-time cost.  I also wonder what the implications are for performing unit testing via testing tools in your IDE:  would those IDE tools also need to test the build files rather than the .js files in the "app" folder?

Overall, I really like the tool so far, and I look forward to seeing it evolve alongside Angular 2.

Sunday, July 24, 2016

Recognizing TypeScript's Jurisdictional Boundary

While I was exploring the current Angular 2 documentation regarding forms and form field validity, I caught myself wondering why the Angular code wouldn't block or complain about an attempt to assign an incorrect data type value to an object property.  Given the following TypeScript object:


export class Villain {
  id: number;
  name: string;
  age: number;
  dateOfBirth: Date;
}

...you could be forgiven if you thought, for a brief moment at least, that a user entering property values for a Villain via a form would experience an error of some kind if they tried to enter a non-number in the age form field,or a string value of "7/14/84" in the date of birth field.

But of course that wouldn't happen. TypeScript only enforces those types when it compiles the code, preventing programmers from using the wrong data type in the code. That type enforcement is not carried through to the resulting JavaScript.

This is hardly a revelation.  TypeScript is a tool for writing JavaScript: it doesn't alter the base behavior or functionality of JavaScript.  But I can see developers spending a few hours coding classes and service methods in TypeScript, then turning their attention to the code that interacts with the web UI and having to remind themselves that the type protection doesn't apply to user/UI actions that change the class property values.  In that area of the code, you have to enforce the data types with explicit code.

And it made me wonder if there should be a way to carry those data type restrictions on class properties down to the resulting JavaScript code by default.  Not sure how feasible that would be.  I would think you'd have to make each property a private property with getter/setter methods where the setter method would ensure the incoming value met the data type criteria.  But then how would a data type mistmatch be handled?  You probably wouldn't want to throw an error:  you'd want to record the attempt in some readable property.  Would you prevent the property from being set to an invalid value, or would you allow it and count on the developer to write code to inspect the object for validity issues before proceeding?  And how would you provide a mechanism for adding custom validations on top of the data type validations?

No matter how you went about it, you'd end up with an opinionated process for enforcing the data types that probably wouldn't work for everyone, which is probably why TypeScript doesn't do anything like that with the compiled JavaScript code.

Learning Angular 2: Exploring the Current Features of Forms

One of the things I noticed when I completed the official "Tour of Heroes" Angular 2 tutorial was that there wasn't a lesson on using forms:  in Angular 1 input bindings that were managed under ngForm provided data state, validation, and error-handling features, and I had heard that Angular 2 had the same thing.

Apparently forms are another aspect of Angular 2 that is still somewhat of a moving target: the current "Forms" chapter under the "Basics" category of the Angular 2 site documents a deprecated version and points to a newer documentation page.  I decided to read through the newer documentation page and try out the current forms functionality myself, building off of my existing Tour of Heroes project codebase.

The decision to use my Tour of Heroes code ended up causing a few problems.  The first problem I ran into was that I didn't have an "@angular/forms" module to import the form providers from per the documentation instructions.  It's not included in the package.json file used for both Tour of Heroes and the QuickStart.  An exection of "npm view @angular2/forms" told me that the forms module current version was "0.2.0".  I updated package.json, deleted my current node_modules folder, and ran "npm install", and after that I had an "@angular/forms" module folder, and I thought I was in business.

However, I got a 404 error trying to load "@angular/forms" when I tried to run the application.  That one caused some head-scratching until I realized where I went wrong,  Having been several weeks since I set up the Quick Start tutorial and then later having copied over those configuration files, I had forgotten about the role of the systemjs.config.js file.  The array of ngPackageNames determines what packages under the "@angular" node_modules folder are loaded, and "forms" was not in the array.  Once I added it, the error went away and I could actually focus on the exercises in the documentation.

The biggest takeaway from the page was that using the [{ngModel}] binding on a form control leads to that form control being decorated with CSS classes that describe the state of the form control:

  • ng-untouched vs. ng-touched, which indicate if the user has interacted with the form control via the mouse or keyboard.
  • ng-pristine vs. ng-dirty, which indicate whether the value of the form control has changed.
  • ng-valid vs. ng-invalid, which indicates if the value of the form control is valid or invalid.
There are some nuances to those explanations, some of which were explained on the documentation page and some that I determined for myself:
  • The class change from untouched to touched doesn't take place until the form control loses focus after the user has touched it (put the form control in focused stated) with either the mouse of keyboard.

  • The class change from pristine to dirty only takes place if the user changes the value of the form control via the UI, such as by typing or by performing a paste action in the form control.  Changing the value of the model data bound to the input programmatically does not trigger the change from pristine to dirty.

  • The untouched-to-touched and pristine-to-dirty transitions are one-way transitions.  If you delete the last letter of the value in a text input and then restore it (so the value is the same as it was when the text input DOM element was created on the page), the text input is still labeled with ng-dirty.  The document emphasizes this point with an example of how to "reset" the pristine state of the form controls by destroying and recreating the form using ngIf and a conditional, and hints that a proper "form reset" action may be forthcoming.  There is a GitHub issue on the topic:  https://github.com/angular/angular/issues/4933.  Having had some programmatic experience with resetting form values, I'm interested to see how they solve the reset issue.

  • The documentation page demonstrates the transtion of a text input control from validity to invalidity in conjunction with the use of the "required" attribute on the <input> element. But it currently doesn't explain how Angular determines the validity of the form control value under other circumstances.  Angular didn't mark the input as invalid when I entered a non-URL value in an input with the HTML5-supported type of "URL", nor did it react when I entered a value in another text input that exceeded the value of the "min" attribute.  A search through the Angular.io site didn't turn up any page that clearly explained how to perform the validation with the latest implementation of forms, though the references to Validators and their use implies that the answer likely involves applying validation rules/logic programmatically.

The documentation page concluded with code exercises that demonstrated how the form as a whole has a validity state property (courtesy of the ngForm directive that is quietly attached to the <form> tag automatically) which is affected by the validity/invalidity of the individual form control values, and then how the form validity property can be used to block the submission of the form if it's currently invalid.

After going through this page, I can see why forms were not covered as a topic in the Tour of Heroes tutorial.  The implementation of form-related behavior in Angular 2 is still evolving, and though this documentation page illustrates some of the expected behavior and benefits it does so at a basic and somewhat vague level. I'll have to revisit this topic down the road after the documentation is more fleshed out.

Saturday, July 16, 2016

Learning Angular 2: Tour of Heroes Tutorial, Lesson 7

The final lesson of the Tour of Heroes tutorial covers using Angular 2 with HTTP.

It starts off with what seems to be a bit of a contradiction:  it shows how to add the set of HTTP services to the application via the bootstrap invocation in main.ts (following the pattern set to add the router), but then makes a point of mentioning that usually application-wide services are registered in the AppComponent providers (HeroService being the prime example in the tutorial up to this point).  The implication seems to be that if we didn't need to mock the HTTP transactions because we have no actual server to talk with, we could register HTTP_PROVIDERS in the AppComponent, but I wish they had said that explicitly.

The revisions to the HeroService to utilize HTTP calls start with a revision that includes adding "Http" to the new constructor method, but leaves out mentioning the need to import Http into the file.  Same with the Headers class used in the new service methods for updating heroes, so HeroService needs the following imports:


import { Headers, Http } from '@angular/http';

Interesting how the import of the rxjs toPromise() operator is not imported with a variable reference like the rest of the imports.

One thing that's not explained in the lesson is the relationship between the heroesUrl ( 'app/heroes') and the array of heroes in the in-memory-data.service.ts file. According to the in-memory web API documentation, the latter half of the "URL" in this particular call references a key name created in the createDB() method that refers to an array of objects. So changing the HeroService to call from a list of monsters instead of heroes is as easy as:


//in-memory-data.service.ts

createDb() {
  //…The heroes array in the lesson
  let monsters = [
    {id: 11, name: 'Mr. Munch Munch'},
    {id: 12, name: 'Grumpy Pants'},
  ]
  return { heroes, monsters };
}

//hero.service.ts

private heroesUrl = 'app/monsters';

And you can target an individual object in the data array by id value, as is done in the put() and delete() methods described in the lesson.  I wondered though if that meant you were locked into a convention of having an "id" property, so I looked around and found the GitHub page for the in-memory-web-api, which said you could specify the property name to use as the identifier as well as the value ("id" apparently being the default property name if none is specified).  I couldn't get the example syntax where the property name was preceded by a "?" (so maybe the documentation is a tad out-of-date), but I could create a URL targeting a Hero by name instead of id without the "?":


let url = `${this.heroesUrl}/name=${hero.name}`;

The need to add the Content-Type header to every add, update, and delete action to specify the use of JSON caught my eye.  It makes sense given the http methods take an array of headers as an argument, but I could see making a private function that would handle creating and returning that headers array that the http functions could all share. Like so:


private getHeaders(): Headers {
  let headers = new Headers();
  headers.append( 'Content-Type', 'application/json' );
  return headers;
}
//...
private put(hero: Hero) {
  let url = `${this.heroesUrl}/${hero.id}`;

  return this.http
    .put( url, JSON.stringify( hero ), { headers: this.getHeaders() } )
    .toPromise()
    .then( () => hero )
    .catch( this.handleError );
}

The next step of the lesson involves updating the code of the HeroDetailComponent to invoke the public save() method on the HeroService (which calls either the put() or post() private service methods as appropriate).  I don't know why the @Input decorator is applied to the hero property of HeroDetailComponent:  while it's true that later in the lesson HeroDetailComponent is once again made a subcomponent of the HeroComponent, the HeroComponent never passes a Hero object to HeroDetailComponent, and removing the @Input decorator doesn't break any of the new add, update, and delete functionality.

The @Output decorator and the "close" EventEmitter object are a different story.  At first, when I was simply following along with the lesson, I didn't pick up on exactly how the HeroComponent knew to listen for the emission of the saved Hero object that occurs in the HeroDetailComponent goBack() method.  The HeroComponent is coded to react to the "close" EventEmitter of HeroDetailComponent through the event handler put on the directive:


<my-hero-detail (close)="close($event)"></my-hero-detail>

I find it interesting that the argument passed to the close() method of HeroComponent is "$event", and yet what the goBack() method emits and what the close() method expects as its argument is a Hero object. If I change the argument name in the directive from $event to something else, like "sentHero", the incoming argument in the close() method ends up as undefined. In contrast, the delete event handler in HeroComponent passes both a Hero object and an $event event object to the HeroComponent deleteHero() method.

The lesson neglects to mention the need to define a Boolean "addingHero" property to the HeroComponent, but of course an IDE like IntelliJ is quick to point that out.

The delete() method of the HeroService starts with an "event.stopPropagation()" statement.  The lesson doesn't explicitly explain why, but the reason it's there is because the delete button in the UI is contained within each hero <li> block, which all have a click event handler that sets the selected hero.  So the stopPropagation prevents the invocation of the click event that would briefly display the mini-detail UI for the selected hero prior to deletion.

This lesson marks the end of the Tour of Heroes tutorial in its current form.  Overall, I thought it was an excellent introduction to the basic elements involved in creating an application with Angular 2.  I was surprised that it didn't include a lesson on forms, but a quick glance at the overall documentation implies that the forms API is still evolving.  I'll have to explore that on my own in the near future.