DEV Community: Martin McWhorter

Extending Angular Material Theme System: Additional Shades

Martin McWhorter — Fri, 16 Apr 2021 11:39:35 +0000

In Part 1 of this series, we discussed how the Angular Material theme system is a powerful tool that may seem overly opinionated. In reality it is very extendable.

In the previous example we added a palette to the theme.
In this example we will add additional named hues to palettes.

Angular Material gives you a lighter and darker named color in each palette -- but these may not be enough for your organization or project.

  mat-color($primary, lighter);
  mat-color($primary, darker);

We are going to add additional helpers extra-light and extra-dark. First we are going to go over a few fundamentals.

Quick Detour

Quick definitions of hue, tint, shade and tone.

Hue = a pure color.
Tint = hue + white
Shade = hue + black
Tone = hue + grey

A hue is a mix of primary colors (red, blue and green are the primary colors of light, where red, yellow and blue are the primary colors of pigment). Tints, shades and tones vary to give gradients.

Theme Palettes

Let's look at a theme pallets and see how they work.

Each palette starts as a map (like a dictionary or array) of shades and tints, with a key starting from 50 to 900 going from brightest to darkest -- then A100 to A700 with a gamma shift into pastel tints.

Then a key of contrast containing another map containing a text contrast shade or tint for each of the keys.

$mat-red: (
  50: #ffebee,
  100: #ffcdd2,
  200: #ef9a9a,
  300: #e57373,
  400: #ef5350,
  500: #f44336,
  600: #e53935,
  700: #d32f2f,
  800: #c62828,
  900: #b71c1c,
  A100: #ff8a80,
  A200: #ff5252,
  A400: #ff1744,
  A700: #d50000,
  contrast: (
    50: $dark-primary-text,
    100: $dark-primary-text,
    200: $dark-primary-text,
    300: $dark-primary-text,
    400: $dark-primary-text,
    500: $light-primary-text,
    600: $light-primary-text,
    700: $light-primary-text,
    800: $light-primary-text,
    900: $light-primary-text,
    A100: $dark-primary-text,
    A200: $light-primary-text,
    A400: $light-primary-text,
    A700: $light-primary-text,
  )
);

A palette is then created by passing this map to the mat-palette(..) (being renamed to define-palette(..)) function.

$primary: mat-palette($base-palette: $mat-red, $lighter: 100, $darker: 700);

Adding additional helpers

We are now going to extend the mat-pallete() (or define-palette()) function.

@function my-palette($base-palette, $default: 500, $lighter: 100, $darker: 700, $extra-light: 50, $extra-dark: 900, $text: $default) {
  $new-palette: mat-palette($base-palette, $default, $lighter, $darker, $text: $default);

  $extra-palette: (
    extra-light: map-get($base-palette, $extra-light),
    extra-dark: map-get($base-palette, $extra-dark),
    extra-light-contrast: mat-contrast($base-palette, $extra-light),
    extra-dark-contrast: mat-contrast($base-palette, $extra-dark),
  );

  @return map_merge($new-palette, $extra-palette);
}

Now we can update our example above and get a palette with the extra-light and extra-dark helpers.

$primary: my-palette(
  $base-palette: $mat-red, 
  $lighter: 100, 
  $darker: 700, 
  $extra-light: 50, 
  $extra-dark: 900); 

$light-theme: mat-light-theme($primary, ...);

// elsewhere in a component theme 
@mixin some-theme($theme) {
  $primary: map-get($theme, primary);

  $primary-lighter: mat-color($primary, lighter);
  $primary-darker: mat-color($primary, darker);
  $primary-extra-light: mat-color($primary, extra-light);
  $primary-extra-dark: mat-color($primary, extra-dark); 
}

Conclusion

There we have it. Designers and developers can use extra-light and extra-dark as named shades or tints in designs and implementations.

Your use case will likely be different. You can suit these techniques to your own situation.

Generate Angular ReactiveForms from Swagger/OpenAPI

Martin McWhorter — Sat, 01 Aug 2020 20:10:30 +0000

Angular ReactiveForms, despite their problems, are a powerful tool for encoding form validation rules reactively.

Single Source of Truth for Validation Rules

Your backend code should be the single source of truth for validation rules. Of course we should validate input in the UI for a better user experience.

Likely we are either implementing the same rules from the same spec, or copying what has been implemented in the API, or layers behind that. We should be asking ourselves, Where should the single source of truth for validation rules live? It probably shouldn't be in the Angular app. We can eliminate this manual duplication by generating Angular ReactiveForms from OpenAPI/Swagger specs, rather than hand coding them.

This eliminates bugs where the validation rules between the UI and API fall out of sync -- or copied incorrectly from the backend to the frontend. When new validation rules change, just rerun the command to generate the reactive form from the updated OpenAPI spec.

This works very well in conjunction with Rest API proxies generated using the openapi-generator.

Prerequisite

If your projects do not meet following prerequisite, you can still use the Quick Start.

In order for this to work with your Rest API you will need to have your backend provide a well formed Swagger (OpenAPI 2) or OpenAPI 3 spec that includes model-metadata for validation expressed as type, format, pattern, minLength, maxLength, etc. Frameworks such as SwashbuckleCore and SpringFox (and many others) do this for you based on metadata provided using attributes or annotations.

Quick Start

This quick start uses a hosted swagger spec, so if you can still go through it whether or not your API exposes the required model-metadata.

First, let's create a new app.



npm i -g @angular/cli
ng n example
cd example

Second, install the generator into your Angular project as a dev dependancy.



npm install --save-dev @verizonconnect/ngx-form-generator

Third, update your package.json scripts to include a script to generate the form. This way when the API changes we can easily rerun this script to regenerate the form.



{ 
 . . . 
  "scripts": { 
  . . .
    "generate:address-form": "ngx-form-generator -i https://raw.githubusercontent.com/verizonconnect/ngx-form-generator/master/demo/swagger.json -o src/app/"
  },
  . . .
}

Now run the script.



npm run generate:address-form

Within your src/app you will now have a new generated file based on the name of the OpenAPI title property, in this case myApi.ts. You can change this using the -f argument and provide the filename you like.

We can now import the form into a component and expose it to the template.



import { Component } from '@angular/core';
import { addressModelForm } from './myApi'; // <- import the form

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  addressForm = addressModelForm; // <- expose form to template
}

We will add Angular Material to our project to provide styles for our form in this example. Of course there is no dependency on any CSS or component library.



ng add @angular/material

In the module lets import ReactiveFormModule, MatFormFieldModule and MatInputModule.



import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { ReactiveFormsModule } from '@angular/forms'; // <- ESM imports start
import { MatFormFieldModule } from '@angular/material/form-field';
import { MatInputModule } from '@angular/material/input';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    BrowserAnimationsModule,
    ReactiveFormsModule, // <- NgModule imports start
    MatFormFieldModule,
    MatInputModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

We will build the form. For demonstration purposes only need the first field.



<form [formGroup]="addressForm">

  <mat-form-field>
    <mat-label>First Name</mat-label>
    <input matInput formControlName="firstName">
    <mat-error *ngIf="addressForm.controls.firstName.invalid">This field is invalid</mat-error>
  </mat-form-field>

</form>

We can now run this with ng serve and see our single field form.

An invalid name can be entered into the field and we will see this validated based on the validation rules from exposed to the Angular application through the OpenAPI spec.

Here we can enter a valid name and see that the validation updates.

If this were a real RestAPI we could add the rest of our form fields and go.

Isolate Generated Code into a Library

We can improve this by putting the generated form into its own library within the Angular workspace. The benefits of this are:

Clear separation of boundaries between the generated and crafted code. One of the power-dynamics of generating API proxies and forms is being able to safely regenerate them. This will help prevent a team-member from manually modifying the generated form.
No need to recompile the form during local development. The form project will only need to be recompiled when after it has been regenerated.
We can add this generation process as part of the CICD build process.

Create a new library



ng g lib address-form

We can now remove the scaffolded component, service and module from the lib.



rm -fr projects/address-form/src/lib/*

We are placing only generated code into this library. We do not want to create unit tests for generated code. Tests should live with the code generator itself. So lets get rid of the unit test support files.



rm projects/address-form/karma.conf.js
rm projects/address-form/tsconfig.spec.json
rm projects/address-form/src/test.ts

We don't need to lint generated code, so lets get rid of tslint.json



rm projects/address-form/tslint.json

We need to remove the references to the test and lint files in the workspace angular.json. Open angular.json and find "address-form": { property. Remove the "test": { and "lint": { sections.

It should then look something like this.



    "address-form": {
      "projectType": "library",
      "root": "projects/address-form",
      "sourceRoot": "projects/address-form/src",
      "prefix": "lib",
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-ng-packagr:build",
          "options": {
            "tsConfig": "projects/address-form/tsconfig.lib.json",
            "project": "projects/address-form/ng-package.json"
          },
          "configurations": {
            "production": {
              "tsConfig": "projects/address-form/tsconfig.lib.prod.json"
            }
          }
        }
      }
    }

In package.json we need to add a script to build our lib as well as update the path where we generate the form.



    "generate:address-form": "ngx-form-generator -i https://raw.githubusercontent.com/verizonconnect/ngx-form-generator/master/demo/swagger.json -o projects/address-form/src/lib",
    "build:libs": "ng build address-form"

Now lets generate the form into the lib.



npm run generate:address-form

Now replace all of the exports in proects/address-form/src/public-api.ts with:



export * from './lib/myApi';

Build the lib with:



npm run build:libs

We can remove the old generated myApi.ts



rm src/app/myApi.ts

Last, update the import of the form



import { addressModelForm } from 'address-form';

Conclusion

Generating forms will allow you to keep your validation rules in sync with the backend. Like generating proxies, this will greatly reduce integration bugs that occur by trying to manually implement backend to UI data contracts.

Introducing Commitiquette

Martin McWhorter — Sat, 22 Feb 2020 08:32:03 +0000

Commitiquette is a Commitizen plugin that uses your CommitLint configuration, allowing you to maintain a single set of rules for commit messages.

Consistent commit messages that follow a convention are useful for automating generation of changelogs, automating versioning based on fix (patch), feature (minor) and breaking change (major) of the commit.

Conventional commits have the beneficial side-effect of causing developers to make more small commits, rather than fewer large commits, limited to the type and scope of the change. This may actually be the most important feature of conventional commit messages.

Commiting code should be like voting in Chicago. Commit early and commit often.

If you are already familiar with CommitLint and Commitizen, you can skip the next two sections and just configure Commitiquette.

Commitizen

There are more options for installing and configuring Commitizen than we will go into here. See the official documentation to learn more.

To add Commitizen to your project, paste the following command in the project's root directory.

npx commitizen init cz-conventional-changelog --save-dev --save-exact

Next add Husky to manage git hooks

npm install husky --save-dev

Finally we will add the following snippet to our packages.json

"husky": {
  "hooks": {
    "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true",
  }
}

At this point Commitizen should be configured in your repository. When you commit changes with git commityou will be prompted by Commitizen.

CommitLint

While Commitizen is helpful in guiding contributers in creating commit messages, developers using a GUI to commit won't be prompted by can easily unwittingly bypass it. This is why it is important to lint the commit messages.

CommitLint had lots of options for installation and configuration, including setup for CI. See the official documentaion for more options.

Install and configure CommitLint in your project

npm install --save-dev @commitlint/{cli,config-conventional}
echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js

Next we will need to add another like to the husky configuration within package.json

"husky": {
  "hooks": {
    "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true",
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
}

At this point, Commitlint should stop commits where the message fails the lint. Again, this is not bulletproof. If you require gated commits CommitLint should be configured in CI.

Commitiquette

CommitLint and Commitizen should be somewhat in sync applying similar rules. Though as soon as you apply project or workspace specific rules, you will find you will need to maintain these rules twice.

This is where Commitiquette comes in by using the CommitLint config for Commitizen.

We will install Commitiquette

npm install commitiquette --save-dev

Next we update Commitizens's config to use Commitiquette. In package.json find the Commitizen config added previously by npx commitizen init... and update is so

  "config": {
    "commitizen": {
      "path": "commitiquette"
    }
  },

Now we can change our commitlint.config.js and Commitizen will pick these changes up automatically!

See the CommitLint documentation for a complete list of rules that may be applied to both CommitLint and Commitiquette.

So now let's configure CommitLint to validate our scope is an item in an array.

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'scope-enum': [2, 'always', ['docs', 'core', 'lib', 'misc', 'etc']]
  }
};

CommitLint will now validate that the scope is one of the elements defined in the above rule. Commitizen, through the Commitiquette plugin, will prompt the contributor to select from this list for the scope of the commit.

Commitiquette can help guide contributors to make smaller, focused commits that follow a shared set of rule based conventions.

Deceptive Sales Tactics at Halfords

Martin McWhorter — Tue, 31 Dec 2019 22:29:53 +0000

On December 16th 2019 I went into Halfords, Carrickmines, Dublin 18, to buy a bicycle for my daughter's birthday. I spoke with a sales person and explained I am only interested in the bicycle if it is in stock, as with the holidays -- I would not have faith that they would be able to order one for me to pickup on the 27th of December, the day before my daughters birthday.

They checked the backroom and told me it was indeed in stock and I could take it in the box that day, or have it assembled by the staff and pick it up on the 27th.

I agreed to have the in stock bike assembled, with the addition of stabilisers, and pick it up on the 27th. I was then quoted a price for the bike, assembly and stabilisers for €192. I paid that in full on the day with a credit card. I noted to the sales person that the assembly and stabilisers were not on the receipt. He told me not to worry, that they are included in the price.

On the day I was to pick up the bike I got a telephone call at 9:56 am to tell me that they did not have the bike I had purchased, that they sold it to someone else. I asked if the in store display was in good condition, as if not I could still go to another bike shop. The store employee agreed to check and ring me back. I never got a call back and spent the next four hours at work trying to ring the store, they never answered the phone that day.

The next day, the 28th (my daughters birthday). I finally got through to the store to -- and then to the manager. He said he would look into it and call me back. I missed a few of his calls as we were driving in the car to my daughter's birthday party when he rang. Though I rang him back and he said they could give me a 15% discount on the damaged in store display (prominent scratch on the frame and badly discoloured white tyres) -- or that they would build a new bike the following Monday -- but would not do anything to remedy selling the bicycle I had already purchased to another customer.

Then when I went to the shop to pickup the display model, they told me they would need to charge me extra for the stabilisers, even though this was included in the quoted price on the 16th of December by the sales person.

In my view their are two deceptive practices here:

Selling a product as in stock -- then selling that stock to another customer. I would have left the shop and gone to another shop if they were honest and told me they were going to do this. I stipulated upfront I was only interested in purchasing the bike if it was in stock.
Claiming the stabilisers were included at time of the sale and then changing this when I went to pick up the bike.

I left the shop without the bicycle because it was clear to me that they are engaged in deceptive practices. I felt bullied and condescended-to by the manager when I brought up these deceptive tactics.

After contacting Halfords customer support and reporting the above, this is the response I received:

Dear Martin,

Thank you for the response. After speaking to the store and my managers here at Head Office, we have come to the conclusion that we would stick by the store with this matter.

I can advise if you wish to go to the store to get your refund for the bike you can go there with the card this was paid for and I can then advise the store of this for you. The other option is that the store are advising the most they can do is the 15% off the bike as discussed in the store.

I am ever so sorry about this. If you are unhappy with the outcome you can seek legal advice regarding this

I hope this helps and if I can be of any further assistance, please do not hesitate to contact me via email or on 0330 135 9779.

Kind regards,

Niamh
Customer Support Team

Recipe: Chicago Tavern Style Pizza

Martin McWhorter — Mon, 30 Dec 2019 17:25:57 +0000

Though Chicago may be known for its stuffed, deep dish and thick crust pizzas, a vast majority of the pizzas sold and consumed are thin crust, what is known in the trade as Tavern-Style Pizza. The stuffed and deep dish being a relatively recent invention from the early 1970s and 1940s respectively. Thin tavern style dates back to Vito and Nick's Tavern opened and operated by Sicilian immigrants in the 1920s. Thick crust is the second oldest Chicago pizza tradition based off of Sicilian pan pizza as well.

I spent my teenage years working in a Barnaby's Pizza in the suburbs of Chicago and ran the pizza kitchen 6 nights a week. The oven had 6 rotating shelves that held 6 large pizzas each. I didn't think I would ever make pizza again when I left Barnaby's.

When I moved to Ireland I was able to find good Neapolitan style pizza. There is even a Rays Original New York pizza in Dublin -- as well as Broadway Pizza Parlour if you are the the mood for New York style pizza.

As far as Chicago style here in Ireland, there are no options but to make it myself. There is one place that offers what they call Chicago style, but it is just an Irish pizza with chicken and corn -- the farthest thing from Chicago style. Chicken and corn don't belong on a pizza.

So here is my recipe based on a copycat Home Run Inn dough recipe that is now blocked in Europe, Barnaby's, Fassano's, and of course JB Alberto's -- the best pizza in the world.

Dough

NOTE: Since dough has a long fermentation period it is impractical to make dough for 1 pizza. The dough recipe will make 3 pizzas, where unless noted the rest of the recipes following is for 1 pizza.

After fermentation you can evenly split the dough into three dough balls and freeze the remaining for later use.

1 cup warm water
4 cups of plain flour
2 tsp salt
2 tsp or 10 grams of active dry yeast or 14 grams of instant dry yeast or 30 grams of fresh yeast
2/3 cup of corn oil

Directions

Dissolve the salt in the warm water. Add the yeast, mix well, and allow to activate for 5 minutes.

If you are using a Thermomix or a bread machine, you can just add the remaining ingredients and allow the machine to knead the dough for 2-5 minutes.

For the manual method:

Add 1 cup of flour and mix well.
Add 2/3 cup oil and 1 and 1/2 cup flour and mix well.
Add remaining 1 and 1/2 cup flour and mix well.
Knead the dough for five minutes.

Place the dough in a large bowl and cover the dough with a dampened cloth and allow to ferment in a warm place. It may be helpful to place the dough in a proving box or in the oven with the oven light on, or set to 50°C with oven door open, for an hour to help start the fermentation process.

After an hour or two punch down the dough.

Allow the dough to ferment at, or a little above, room temperature for 24 hours. Place the dough in the refrigerator and allow to ferment for an additional 24-48 hours for a total of 48 to 72 hours.

Sauce

700g passata should give you enough sauce for 3 pizzas.

500 - 700g Passata
140g Tomato Puree
1 tsp salt
1/2 tsp Ground Black Pepper (do not use coarse ground -- the finer ground the better)
1 tbsp Dry Basil
2 tsp Dry Oregano

The thicker or more rustic the passata the better. Passata from sweet tomatoes, rather than acidic, works better -- though avoid adding sugar.

Directions

Pour the passata into a large bowl and mix in the tomato puree.
Mix in the salt to taste, it should be a balanced.
Mix in the black pepper to taste, the pepper should not overwhelm the sauce.
Mix in the basil and oregano. This should give the sauce its signature taste.

Sausage

Except for dough, sauce and cheese -- all of the other toppings are optional.

Sausage on pizza is not a thing here in Ireland. Ordering sausage on a pizza and you may end up with hotdogs or breakfast sausages on your pizza.

Pizza sausage is not a cased sausage, but rather the sausage filling. The key to the flavour is the fennel seeds.

In Chicago it is the most popular topping, where pepperoni or salami would be the most popular the rest of the world over, which may trace back to Chicago once being the "hog butcher to the world" with the industrial pig slaughterhouse and now infamous stockyards at the end of the 19th century.

100g minced pork (should be between a ping-pong and billard ball in size). You can ball and freeze the remaining pork -- or make more sausage.
2 tsp Salt
2 tsp Ground Black Pepper (fine ground)
2 tsp Smoked Peperica
2 tsp Dry Basil
1 tbsp Fennel Seeds

Directions

Flatten the minced pork onto a plate.
Spread the ingredients over the pork.
Mix the sausage well by folding it into itself, then form back into a ball.
This can be refrigerated until needed.

Onion

Peel and hand dice one white onion into 1 cm cubes.

Mushroom

Wash and thinly slice 2-3 medium white mushrooms.

Green Pepper

Wash and cut inwards on the stem side of the pepper to remove the seeds. Remove any connecting tissue and wash the inside of the pepper.
Thinly slice rings, .5 to 1cm thick, from the open side of the pepper.
Then slice these rings in half.

NOTE: 1 green bell pepper is enough for two pizzas.

Black Olive

Soak 6-8 black olives in water for 5-20 minutes to remove salt and brine.
Slice the olives as thin as possible.

Cheese

NOTE: Use dry mozzarella blocks rather than fresh mozzarella or grated mozzarella. Fresh mozzarella has too much moisture and grated mozzarella will lack the flavor. Dunnes, here in Ireland, stocks mozzarella blocks.

Grate 200g dry mozzarella block with Thermomix, food processor or by hand.

Assembly

Preheat your oven as hot as it goes. If you have a pizza stone place it on the bottom rack of your oven and allow it to preheat for 40 minutes.

Crust

Separate the dough into three even balls.

Flour your workspace and roll out the dough into a circle 15 inches in diameter. Use a 14" oven pizza tray as a template or guide. Around the pizza track you should have a half inch overlap around the pizza. It should be about 1/2 (.5) cm thick. Use a rolling pizza cutter to trim off any extra.

Dust your pizza peel or a large preparation tray with corn meal (polenta) and transfer the dough and pizza tray. Crimp the edges around the pizza dough with the your thumb and forefinger.

If your oven does not go to at least 250°c or 500°f, blind bake your pizza crust for 5-7 minutes on a well greased baking or pizza tray before assembling the pizza.

If your oven goes up to at least 250°c and you have a pizza stone, there is no need to blind bake.

Sauce

Spread 5 tbsp of sauce with a ladle or large spoon over the dough all the way to the inside of the edge crimps. Be sure not to leave any gaps.

Left over sauce may be used as a pasta sauce.

Sausage

Sausage is the first topping on the pizza.

With your thumb and forefinger grab 20 cent to 50 cent balls of sausage and press down onto the pizza edge just inside the crimp, circling inward at 1-2 inch spaces. Be sure to flatten these out as any peaks sticking out from the cheese will burn.

Pepperoni (alternative to or additional to sausage)

Pepperoni cannot be ignored as a pizza topping.

The best pizza pepperoni I have found is Horgan's Brand pepperoni (made in Germany) sold in Fresh markets. The Tesco brand pizza pepperoni is also good.

Pepperoni goes under the cheese between the sausage and onion, not on top of the cheese.

Place each slice around the all the way to the edge crimp, with no gap between each pepperoni and wind all the way in.

1 package of Horgan's pepperoni makes 1 pizza.

Mushroom and Onion

Both of these go under the cheese as well.

Spread the onion, and then the mushroom, evenly over the pizza being sure to get to each edge.

Cheese

Start with the outside of the pizza and spread the cheese all the way around just inside, and all the way up to, the crimp at the edge working your way to the center of the pizza.

Because outside of the pizza will cook faster than the ceter, you should imperceptibly cheese the parameter more than the center.

Green Peppers and Olives

Spread the peppers and olives all the way to the edges of the pizza.

Final touches

Sprinkle a tsp of basil and a pinch of fine ground black pepper over the pizza.

Bake

Bake until the (white) cheese starts to turn from yellow to brown.

Remove from oven. Place a cold oven grate onto your workspace and pass the pizza peel or a large knife (or both) under the pizza to remove as much of the polenta (corn meal) from the bottom of your pizza before cutting.

Put the pizza back onto the peel and cut into squares with three parallel cuts across the pizza, then repeat with three cross parallel cuts. Use a large knife rather than a circular pizza cutter.

Extending Angular Material Theme System: Additional Palettes

Martin McWhorter — Tue, 17 Dec 2019 09:57:27 +0000

The Angular Material project provides a powerful theming system. This theme system provides a few palettes: Primary, Accent and Warn. It may not be obvious how to extend the theme system to provide additional palettes -- or how to then use those extended palettes.

Here we will go through how to

Add palettes to a theme
Use these additional palettes

Theme System

First we have to familiarize ourselves with how the theme system works before we can extend it.

The theme is constructed as a set of SCSS maps. A map in SCSS is just an array of key-value pairs. Similar to a Map in Java, a Dictionary in C# or a Record in TypeScript.

If we take a look at the source we can see the functions for creating a light or dark theme just return a map containing the three material palates, a foreground and background maps, and an is-dark boolean.

@function mat-light-theme($primary, $accent, $warn: mat-palette($mat-red)) {
  @return (
    primary: $primary,
    accent: $accent,
    warn: $warn,
    is-dark: false,
    foreground: $mat-light-theme-foreground,
    background: $mat-light-theme-background,
  );
}

So we can add our successpalette simply by wrapping the function and adding our new bit in.

@function my-light-theme($primary, $accent, $warn: mat-palette($mat-red), $success: mat-palette($mat-green)) {
  @return map-merge(mat-light-theme($primary, $accent, $warn), (success: $success));
}

We can now repeat this for the dark theme.

@function my-dark-theme($primary, $accent, $warn: mat-palette($mat-red), $success: mat-palette($mat-green)) {
  @return map-merge(mat-dark-theme($primary, $accent, $warn), (success: $success));
}

In our style.scss where we would include a custom theme using mat-light-theme(..) or mat-dark-theme(..), we now use my-light-theme(..) and my-dark-theme(..).

At this point we will be be able to use this theme palette in our own components. These components can now easily be re-themed.

@import '~@angular/material/theming';

@mixin awesome-component-theme($theme) {
  $success: map-get($theme, success);
  $success-color: mat-color($success);
  $success-contrast: mat-color($success, default-contrast);

  .app-awesome {
    background: $success-color;
    color: $success-contrast;
  }
}

What about Material components?

This is well and good, we can use our new theme palette in our own components. But how can we use this in Angular Material components?

Lets add this to the MatButton component.

First we need to override the _mat-button-theme-property mixin to add the mat-success classes.

@mixin _mat-button-theme-property($theme, $property, $hue) {
  $primary: map-get($theme, primary);
  $accent: map-get($theme, accent);
  $warn: map-get($theme, warn);
  $success: map-get($theme, success);
  $background: map-get($theme, background);
  $foreground: map-get($theme, foreground);

  &.mat-primary {
    #{$property}: mat-color($primary, $hue);
  }
  &.mat-accent {
    #{$property}: mat-color($accent, $hue);
  }
  &.mat-warn {
    #{$property}: mat-color($warn, $hue);
  }
  &.mat-success {
    #{$property}: mat-color($success, $hue);
  }

  &.mat-primary, &.mat-accent, &.mat-warn, &.mat-success, &[disabled] {
    &[disabled] {
      $palette: if($property == 'color', $foreground, $background);
      #{$property}: mat-color($palette, disabled-button);
    }
  }
}

Now we cannot simply use:

<button mat-button color="success">SUCCESS</button>

This will work ok, until it doesn't.

It only works because of regression bug in Angular that fails to type check string literals. This will be fixed in the future. This means that we can try to use the mat-button color="success" to apply our new color to the Angular Material components -- but it only works because of a bug. So let's not do this.

Using a CSS Class

One solution would be to simply add a class to the element:

<button mat-button class="mat-success">SUCCESS</button>

Using a Directive to Extend Angular Material

Or we can create a directive to do this for us.

type ColorClasses = 'mat-primary' | 'mat-accent' | 'mat-warn' | 'mat-success' | undefined;

@Directive({
  selector: '[myColor]'
})
export class MyColorDirective {

  @Input() set myColor(value: ColorClasses) {
    this.renderer.addClass(this.element.nativeElement, `mat-${value}`);
  }

  constructor(private element: ElementRef, private renderer: Renderer2) { }
}

<button mat-button myColor="success">SUCCESS</button>

When the regression bug that is preventing string literals from being type checked in templates is fixed, this approach will improve developer experience.

Conclusion

Angular Material is powerful, though it may seem too prescriptive at times. That is until you look into the internals of the SCSS themes, typography and see there are many extension points.

One of the strengths of Angular is being able to extend using attribute directives. Adding behaviours and palettes using directives is simply the least obtrusive method for extension.

Throttling Events in Angular with Rxjs

Martin McWhorter — Wed, 14 Dec 2016 12:03:00 +0000

Both Angular and Rxjs give you the ability to easily listen to events. Using Angualr's @HostListener() annotation allows a declarative binding while using Rxjs event binding allows for filtering, debouncing and throttling of events, to name a few.

The prefered way to bind to events in an Angular component is to use the @HostListener() annotation. This provides a clean declarative binding from an event to a method, and best of all works without the need to access any browser specific APIs such as document or window. Avoiding direct browser DOM APIs becomes important if you want to use the Universal server-side rendering or run the applicaton in a WebWorker. Keeping your code open to either of these possibilities, even if you have no plan at the moment, allows you to take advantage of future optimizations.

Throttling Resize

You may ask, why do I need to listen to resize events?

You may not need to. As many of your UI elements as possible should respond to form factor changes through CSS cues rather than scripted cues. Mobile and Tablet devices don't have any real stories where the viewport changes sizes that aren't handled by the deviceorientation event. Their are probably some edge cases like split screen and some virtual keyboards pushing up on the browser window.

Their may be some exceptions to this where you will need to script the responsiveness. For example, you may have a menu that is pinned open on desktop form factor, pinned in a minimized mode on tablets in landscape mode, and hidden behind a hamburger menu on portrait tablets and phones.

Even with this scenario a valid situation where a user is resizing, not rotating, the browser window is at best an edge case.

In reality the use case is a developer story. As a developer you want to be sure that your UI behaves at every width between the smallest acceptable width to the largest. You want to be able to stretch your responsive browser developer tools from tiny to extra-large and ensure that the app will display correctly for every pixel width.

With Rxjs we can accomplish very simply:

private resizeObservable = Observable.fromEvent(
    window, 
    'resize'
  ).throttleTime(200);

Nice and clean. But there is a problem with this. We are accessing the DOM window directly. We could wrap this in a try/catch, or inject a window into our component that gets replaced with a fake if we run on the server, but then if we decide to run in a WebWorker we are out of luck and will need to replace this code.

The Solution

We can use the Rjxs throttle method in conjunction with Angular's @HostLister() decorator annotations.

In our example below we create a Subject of type number named resizeSubject. We will call the next() method on resizeSubject in our event handler.

We create an Observable from our Subject and throttle it for 200 miliseconds. Then within our ngOnInit() we will subscribe to our throttled observable.

app.component.ts

export class AppComponent implements OnInit { 

  private resizeSubject = new Subject<number>(); 
  private resizeObservable = this.resizeSubject.asObservable()
    .throttleTime(200); 

  @HostListener('window:resize', ['$event.target.innerWidth']) 
  onResize(width: number) { 
    this.resizeSubject.next(width); 
  } 

  ngOnInit() { 
    this.resizeObservable.subscribe(x => 
      this.doSomethingWithThrottledEvent(x)); 
  } 

  private doSomethingWithThrottledEvent(width: number) { 
    // . . . 
  } 
}

AngularJS 1.x with TypeScript (or ES6) Best Practices

Martin McWhorter — Tue, 01 Mar 2016 11:37:00 +0000

After working with AngularJS with TypeScript for the last couple of years there are a few best practices that seem to be missing from most tutorials.

These practices apply whether you are developing in plain old JavaScript (ES5), ES6 (ES2015) or TypeScript.

Code should never be future proofed, instead it should be extendable. Following these practices should help you create code that will easily be upgraded to Angular2 -- as well as be more maintainable.

Use External Modules

Using external modules will do two things for you.

When bundling your application external module use will automatically order your dependencies for you.
External modules will eliminate the need to use ///<reference path="..." /> notation.

Example:

app.ts

import {module} from 'angular'; 

export let app = module('app', [
  require('angular-ui-router'), 
  require('angular-animate'), 
  require('angular-ui-bootstrap'), 
  require('angular-translate')
]);

PersonComponent.ts

import {app} from './app'; 

export class PersonComponent { 
  // . . . 
} 

app.component('PersonComponent', PersonComponent);

Don't Use TypeScript Internal Modules/Namespaces

Before the common use of external modules it was commonplace to use TypeScript internal modules, now renamed namespaces.

TypeScript namespaces are based on the JavaScript Internal Module pattern. This pattern came about because of the lack of module encapsulation in JavaScript. With the introduction of CommonJS and ES6 modules and module syntax, the internal module pattern should be avoided.

Use external commonJS/ES6 modules instead of TypeScript namespeces.

Don't use IIFE (Immediatly-Invoked Function Expression)

IIFEs are common in JavaScript development as they allow you to encapsulate your code.

(function() { 
  // encapsulated closure protected from other code 
})();

Using external modules eliminates the need for explicity wrapping your code in IIFE closures. Instead a build time task (browserify, jspm or webpack) and module system will bundle and load your code into closures.

IIFEs will also cause problems exporting types from your modules.

Only create AngularJS Modules for a purpose

Keep the number of AngularJS modules to the minimum needed. Have a reason for creating new AngularJS modules.

Such as:

Sharing common code among different applications
Making code more testable

AngularJS modules were created because of the lack of module system in JavaScript. With ES6 module syntax and commonJS modules AngularJS internal modules are a legacy artifact of AngularJS 1.x.

Define Services as Classes

Defining your services as classes, which AngularJS's DI mechinism will instantiate as singletons, will make your code cleaner, easier to read, easier to maintain and easier to test.

Lastly, defining your service as a class will make your code more friendly to static typing with TypeScript.

userProxy.ts

import {IHttpService} from 'angular';
import {app} from '../app'; 

export class UserProxy { 
  static $inject = ['$http']; 

  constructor(private $http: IHttpService) { } 

  login(login: UserLogin) { 
    return this.$http.post('/api/login', login); 
   } 

  logout() { 
    return this.$http.post('/api/logout', {}); 
  } 
} 

app.service('userProxy', UserProxy);

import {app} from '../app'; 
import {UserProxy} from './userProxy'; 

export default class LoginController { 

  static $inject = ['userProxy']; 

  constructor(private userProxy: UserProxy) {} 

  model: UserLogin = {}; 

  submit(model: UserLogin) { 
    this.userProxy.login(model).then( () => { 
      // handle success 
    }, () => { 
      // handle error 
    }); 
  } 
} 

app.controller('LoginController', LoginController);

In the previous example we demonstrate clean type encapsulation using imports.

We import the type import {UserProxy} from './userProxy';
Then we use the imported type in the constructor injector, constructor(private userProxy: UserProxy) {}
Finally we demonstrate use of the static typing that was imported this.userProxy.login(model).then(

This is a much more manageable approach than using TypeScript internal modules/namespaces to access types.

Only use the Factory Method when Needed

In most cases your services will be singletons. Use the service method to register these with AngularJS's DI, app.service('userProxy', UserProxy).

The obvious use case for the factory method is when using the factory pattern. Let's use the previous UserProxy class as an example. For this example let's assume there are more than one JSON/HTTP end points that impliment this same API. We can make this class reusable with a factory.

Lets update the class to look like this:

import {app} from '../app'; 

export class UserProxy { 

  constructor(private $http: ng.IHttpService, private basePath: string) {}

  login(login: UserLogin) { 
    return this.$http.post(this.basePath + '/login', login); 
  } 

  logout() { 
    return this.$http.post(this.basePath + '/logout', {}); 
  } 
}

We can now use a factory to create instances of this class:

userProxyFactory.ts

import {IHttpService} from 'angular';
import {app} from '../app'; 
import {UserProxy} from './userProxy'; 

export UserProxy; 
export type userProxyFactory = (basePath: string) => UserProxy; 

userProxy.$inject = ['$http']; 
function userProxy($http: IHttpService): userProxyFactory { 
  return (basePath: string) => { 
    return new UserProxy($http, basePath);
  } 
} 

app.factory('userProxy', userProxy);

This can then be used in the controller as:

import {app} from '../app'; 
import {userProxyFactory, UserProxy} from './userProxyFactory'; 

export default class LoginController { 
  private userProxy: UserProxy; 

  static $inject = ['userProxy']; 
  constructor(userProxyFactory: userProxyFactory) { 
    this.userProxy = userProxyFactory('/api1'); 
  } 

  model: UserLogin = {}; 

  submit(model: UserLogin) { 
    this.userProxy.login(model).then(
      () => { 
        // handle success 
      }, 
      () => { 
        // handle error 
      }); 
  } 
} 

app.controller('LoginController', LoginController);

Bind Directly to Controller Properties and Methods

Many examples still bind methods and properties to the injected $scope within the controller.

// DON'T DO THIS 
export class PersonController { 

  static $inject = ['$scope']; 
  constructor(private $scope: ng.IScope) { 

    $scope.name = "Person's Name"; 

    $scope.save = () => { 
      // . . . 
    } 
  } 
}

This is a bad practice for a few reasons.

This has a memory impact. Every instance of this controller will have its own copy of each method bound to the scope. If the methods were instead defined as instance methods the implementation will be shared across instances.

The API for this class is not exported and usable in unit tests.

With larger nested applications you will run into scope inheritance collisions. These collisions will cause strange behaviour that can seem to defy reason. They are often hard to track down.

It becomes easier to pass a value by reference when you include the properties parent object in the expression, person.name rather than name.

Instead define the above controller like this:

export class PersonController { 
  name = "Person's Name";

  save() { 
    // . . . 
  } 
}

With ng-router and ui-router you will just need to name your instance of the controller with the controllerAs configuration property.

Use TypeScript for Unit Tests

One of the main advantages of using TypeScript are the type annotations for the classes you want to test. Fear of breaking tests should not prevent you from refactoring rotting code. Using types with your tests will help keep your tests clean and readable.

Summation

TypeScript can be a great tool to keep your code base and easier to refactor. Your services will have solid APIs that your controllers and components will consume. Bugs will be found at compile time rather than in QA or Production.

Even without the TypeScript, many of these practices can be applied to both ES6 and ES5. In ES5 you will just need to use commonJS require syntax instead of the ES6 import systax -- and the JavaScript Prototype Pattern instead of the class keyword.

Just a couple final thoughts:

Use a build system -- gulp or grunt.

Use NPM -- don't use bower. You only need one JavaScript package manager system. Bower is redundant.