DEV Community: Elanna Grossman

How I Switched My Website to Analog

Elanna Grossman — Sat, 23 Dec 2023 02:08:59 +0000

Updated Sep 09, 2024 - added information about more recently implemented features, like search, skeleton loader, and tag cloud.

Introduction

As I switched my website to Analog, I had to make some decisions. I wanted to migrate every post, and most of the other text content. Analog adds some very nice quality of life features to Angular, which is already a powerful batteries-included front end framework. My previous portfolio, however, is built in WordPress, which provides a lot of template options for making sites like portfolios or blogs. Analog does not have a large template ecosystem at the moment, so that meant that I would need to build a lot of blog and portfolio functionality from scratch. I still wanted to use Analog, because the markdown and file routing support promise minimal friction if I just want to write a new post.

Planning

Once I knew what content I wanted to bring over and that I would have to build a lot of the site functionality myself, I looked at how my WordPress site is structured for inspiration and made lists for what features I wanted to keep vs discard:

Keep
- Homepage
- About page
- Blog
- Blog index page
- Blog post page
- Categories
- Tags
- Previous/next post links
- Archives
- Filtering posts and route by year and year/month
- RSS
Discard
- Accounts
- Comments
Nice to haves for later
- Search (decided to implement a simple client side only version)

This site is the canonical source for posts, but I currently repost them to dev.to, which has account and comment support.

New Features

In addition, I thought of new features I would want to have:

Markdown support
Photos page
- Simple service that reaches out to the Flickr API to get some of my photos
Talks page
- Place to list any talks I have given
Light/dark mode
- Set by system preference initially
- User toggle for light/dark mode
- Mode updates syntax highlighing theme also

Styling

I decided to use Tailwind CSS, both to become more familiar with it and because it seemed like a good fit. The Analog create analog@latest package template includes an option to generate a new project with Tailwind support from the start. It has been easy to build the site responsively with Tailwind, as it is designed around mobile-first layouts. I added the @tailwindcss/typography plugin for some decent text styling defaults. The other default styles were useful, but I did customize the tailwind configuration slightly:

Added a text shadow effect, which I adapted from this article
Removed showing the back ticks when styling text with a monospace font

Tailwind is opinionated, but it isn't a full component framework. This site is simple enough that I didn't see the need to add any other CSS frameworks. I made UI elements from scratch, like the popover, which is built with content projection.

Data Handling

I decided early on that this site would only have a client. The main reasons to have a back-end would be to support things like accounts, which I don't think I need. Since the majority of the routes interact with markdown files in some manner, I decided to use front matter as a pseudo-api. The front matter on a given markdown file has the title, route slug, and date. injectContentFiles() and injectContent() effectively became my get() and getById() methods. I made the following interface to interact with the front matter:

  export interface BlogPost {
    author?: string;
    category?: string;
    cover_image?: string;
    cover_image_author?: string;
    cover_image_source?: string;
    cover_image_title?: string;
    date?: string;
    description?: string;
    last_updated?: string;
    published?: boolean;
    slug?: string;
    tags?: string;
    title?: string | null;
  }

I did make a small API service for Flickr, where I host my photos. Flickr does have a public API for this purpose. If I could no longer rely on Flickr, I would need to come up with an alternate solution.

Other Priorities

Accessibility

Accessibility is really important, and like a lot of things in web development, it is much easier to implement from the beginning rather than with a complete project. Aside from the usual considerations, I made sure that the site is fully navigable from the keyboard. While styling the site, I also spent time considering the contrast for the light and dark themes, and the syntax theme for Prism. I found a set of prism themes that are a11y compliant. I also tweaked the wrapping on the code blocks after following this guide.

While the best accessibility testing comes using tools like screen readers directly, I have found these plug-ins very helpful:

WAVE Evaluation Tool
- Provides a simple audit of individual pages for accessibility concerns. Needs to be reloaded after navigating to a new route within a SPA. Available for Chrome, Firefox, and Edge.
Color Contrast Checker
- Shows if color contrast is sufficient, at different standard sizes. It can help developers have a consistent flow if checking contrast in multiple browsers.

SEO

I don't care a lot about SEO for this site, but I wanted to at least set meta tags including OG tags and have a sitemap. I made a set of utility methods to dynamically build sitemap links for things like posts, categories, and tags.

The official Open Graph tool is very useful to confirm that the OG tags are working as expected.

Building the Site

Since this is a personal project, I was okay with starting simple and seeing what my needs were. I don't think I'll need to implement NgRx in this project, for instance.

Routing

My WordPress site had a blog route structure of /:year/:month/:slug. For this site, I decided to use /blog/:year/:month/:slug. I wanted to be able to navigate to either /blog/:year or /blog/:year/:month and show posts that matched those parameters. The year and month are consumed from the date property in the front matter, so that the posts could control the routing programmatically. Under the hood, slug and file name are still the real unique identifiers, so I couldn't have two files with the same slug and different dates without additional work. I would implement that for a client project, but I think that will be fine for this site.

Archive Component

I created a component that traverses the provided list of posts and creates an array of labels and routes for years and months that have posts.

Pills Component

The site supports both categories and tags for organizing content. I decided to create a generic pills component for both. The tags are saved as a comma separated string, so I split the string into an array.

Search

I added a simple search feature to the header. It is client-side only for now. If I write enough articles that it does not scale well, I can create a back-end to host posts and perform searches. At the moment, it only searches the post front matter.

Images

Between wanting to support cover images for blog posts, and showcase some of my photos, I knew I would need to support a lot of functionality for images.

Cover Images

In order to support cover images for posts, I added a number of properties to the front matter:

cover_image?: string;
cover_image_author?: string;
cover_image_source?: string;
cover_image_title?: string;

Some of these apply to the cover image directly, and I use some for the popover.

I used a version of this for the recent photo album component that I added to the home page.

Popover

For the post cover images, I wanted to provide an easy way to show the photo name, author, and link. I decided to use a popover for this. Since I needed to make one by hand, I decided to use content projection. I made a component with the responsibility of having the popover icon, that would open a passed in additional component as projected content. I set the tab index on the popover icon so keyboards could navigate to it. This worked out nicely, and so I added it to the photos in the masonry grid also.

Skeleton Loader

After the site had been live for a little while, I wanted to improve the loading experience by adding skeleton loaders. With the way that the site is constructed, image skeleton loaders made the most sense. I made a skeleton card component that accepts height, maxWidth, and width as bindings. I also added a screen size service so I could listen to resize events to make the skeleton cards responsive.

Masonry Grid

I have used Flickr for many years, and I have always liked the way that masonry grids look. I wanted to put some of my favorite photos on a page, where they would randomly load from a list into a masonry grid. My initial approach involved a directive, which felt too heavy for what I needed. I looked around for a CSS only solution, and found this very useful article. I tweaked the styling and ended up with these rules.

Object Fit

After implementing the masonry grid, I styled the post and talk thumbnail images with object-fit: cover to improve the flow of the cards.

Broken Image Directive

I wanted a solution to help prevent image link rot. I added a directive that listens to the onerror event for the target element, which in this case is img. If it fires the onerror event, it replaces the broken image a fallback instead, which I host locally.

Draft Functionality

I wanted to be able to support draft functionality, where a post would be hidden from routing if it didn't have published: true. Draft posts still support direct navigation. To support this, I had to add filters to the lists of posts, tags and categories, and the post navigation buttons. I also added a banner to a draft post to make it easier to distinguish.

RSS

One of the nice features that Analog supports is RSS. I wanted to continue to provide an RSS feed, which is something that comes with WordPress sites by default. I personally prefer making the entire post text available and not just a blurb. The implementation can be found here: feed.xml.ts.

Static Site

As the same became usable, I started leaning toward building and deploying it as a static site. Static sites are very portable, which is important to me. I don't want to be stuck with a hosting service that I don't like because I can't easily switch. After evaluating the available options and my needs, I chose GitHub Pages for hosting. It is free for small scale sites, which this is. I was able to adapt the Nitro Github Action template to build and deploy. I configured it to deploy when I push to the main branch.

There are limitations to static sites and hosting on GitHub Pages. If I wanted to have a back end, I would need to host it somewhere else. In order to make changes to the site, whether programmatic changes or adding a new post, I would need to commit to the GitHub repository. I don't have any kind of admin panel I could use to make changes from any web browser. I also need to build the site in order to deploy it. The build times are quick, but not instant.

For this site, none of these are deal breakers, but I wouldn't choose static sites for all use cases.

Gotchas

Initially, I used the standard /blog/:slug route structure for individual posts. However, after I decided I wanted to preserve the /blog/:year/:month/:slug structure, I ran into an issue with how Angular deals with rerendering a component if only a route parameter value changes. If I navigated from one route structure to another, like /blog to /blog/:year/:month/:slug, the routing and rerendering worked as expected. However, if I only changed the /blog/:year/:month/:slug router params, like moving from one post to another using the navigation buttons, the route would update but the page would not rerender. This is intentional behavior in Angular. In order to get the behavior I wanted, I needed to add listeners to the route parameters.

Conclusion

Recreating my site in Analog took me a while because I had less free time to work on it than I liked and kept finding things to add, but I am very happy with the results so far. I still have some polish to apply, and some new features I want to implement, but I now have a site where it's easy for me to just publish a new post. The site is easy to move to new hosting if I need to, and it doesn't require a lot of dependencies or resources to build.

The post How I Switched My Website to Analog appeared first on Hapax Legomenon.

Time for a Change: Switching to Analog

Elanna Grossman — Sat, 25 Nov 2023 21:07:53 +0000

Hapax Legomenon 3.0

This is the third version of this site. I started the original site in 2014, built in WordPress. I revamped the content and theme and started learning the WordPress ecosystem better in 2015. The second version was good enough to suit my needs for years. However, my end-of-life WordPress theme recently broke. That was enough of a motivator to redo this site. What follows is an exploration of why I decided that switching to Analog was the right choice.

I had been thinking about redoing my website in something other than WordPress for a while. WordPress was definitely a good choice for this site originally. I was new to web development and I appreciated the batteries-included nature. However, I don't develop much in PHP or WordPress, and haven't kept up with the ecosystem much recently. I did not enjoy using Gutenberg block system for blog posts, which is the primary focus of my site.

The Use Case

I had looked at various Jamstack and SSG tools, especially ones built around writing content in Markdown. I don't find myself using full word processors much anymore, and Markdown is a sweet spot between simplicity and versatility. For this site, I don't need a back-end. I don't need to have user accounts or comments (dev.to works for that), and I host the majority of the images I link on my flickr (I'd figure out a contingency if flicker ever goes down). As a result, I wanted to make a simple site that I could deploy statically to something like GitHub Pages. I also wanted to retain RSS functionality, as one of the vanishing few who still use it.

I value portability in websites because I don't want to be stuck in a particular ecosystem. I haven't liked the direction that Medium has taken in the past few years. While I do re-post articles from my site my dev.to, I maintain my site as the canonical source. I had only recently heard of Analog when my WordPress site started having problems, so I decided to check it out.

Enter Analog

Analog is a meta framework for Angular, like Next.js is for React and Nuxt is for Vue. This means that while most of tooling is pure Angular, it adds some extra features like markdown rendering, file-based routing, SSG support, RSS support, what seems to be more reliable a SSR implementation (my historical experience with the official Angular Universal was a mixed bag), along with some other benefits. It also uses Vite instead of Webpack, and Vitest instead of Jasmine or Jest.

It's a new framework, and not fully finished, so I spent some time making a sandbox site to see if it would suit my needs. I am not using all of its features, but I have been enjoying it a lot so far. I am using it for this site, which is a personal site and blog. I'm not sure if I would use it for a client project until it's more mature, but I haven't run into any real issues yet. The biggest issue I've found is that the app sometimes caches while developing locally, but reloading in a private window fixes that.

While I wish that the main support infrastructure used something like a forum instead of Discord (since Discord is a closed ecosystem and can't be searched externally), I find the community very welcoming and helpful. As Analog is quite new, it doesn't have a large template or plugin ecosystem yet.

I wrote a follow-up post on how I made the switch, but I wanted to write a more general overview of my experience with switching to Analog so far and why I chose it. I'm looking forward to seeing how it evolves.

The post Time for a Change: Switching to Analog appeared first on Hapax Legomenon.

Recommended Development Tools in Linux, MacOS, and Windows

Elanna Grossman — Sat, 18 Feb 2023 02:39:42 +0000

I use Linux, MacOS, and Windows, and I like all three operating systems. There might be a tool I like more in one than the others, but I can write code and spin up environments regardless of which OS I’m using. In this article I have put together a list of my recommended development tools.

I have a work-provided Macbook Pro that runs MacOS. It is based on Apple Silicon and I have found that the ecosystem is a lot better than it was in 2021 when I first switched. Most applications I need are now native or universal and even NodeJS runs decently well on the native architecture.

My personal computer is a desktop that runs Windows 10 and Manjaro (Manjaro is an arch-derivative rolling release distro. I use the Cinnamon DE because I can keep my window-snapping muscle memory). Since the desktop is my personal machine, I have found it useful to do most of my programming there on Linux. This helps me separate coding time mentally. I deliberately did not install anything like games in Linux so it could be a focused environment.

Development Tools

Package Manager

yay
- Linux
- yay wraps the built-in pacman. I use it to install all of the Linux software.
- This is only available for arch and arch-derivative distros.
homebrew
- MacOS
- Install most software available on homebrew with it.
- Since I’m on Apple Silicon, I check if the homebrew packages are native or universal, and if they still point to Darwin, I install manually. In the past year, this situation has gotten a lot better.
I don’t use a package manager on Windows. I have been watching the development of winget and I plan to try it out now that it is out of preview.

Terminal

Terminator
- Linux
iTerm
- MacOS
Windows Terminal
- Windows

IDE

Visual Studio
- Windows
- I like to use Visual Studio in Windows for .NET projects , but I think that for .NET Core API projects Visual Studio Code works very well. I do not use Visual Studio for front end projects.
- I also don’t use Visual Studio on MacOS unless I am working with Xamarin. It is not the same product under the hood as the original Visual Studio on Windows and I use Visual Studio Code instead.

Code Editor

Visual Studio Code
- Linux
- MacOS
- Windows
- I listed my recommended extensions here.

Git Client

GitKraken
- Linux
- MacOS
- Windows
- I like using Git GUI clients because I have a very visual memory. GitKraken helps me commit only final code and not debug stuff. I also like to use it to commit specific lines which helps me do atomic commits.

Database Tools

DBeaver
- Linux
- MacOS
- Windows
- I most frequently use Postgres and MSSQL. DBeaver does not work as well for non-relational databases.
SQL Server Management Studio (SSMS)
- Windows

HTTP

Postman
- Linux
- MacOS
- Windows

Notes

Boost Note
- Linux
- MacOS
- Windows
- There is an older and a newer version of Boost Note. I still use the older version because I prefer the feature set. The older version is in maintenance mode and might be an acquired taste at this point, but I really like it.

Sync

Dropbox
- Linux
- MacOS
- Windows

If I find any other recommended development tools, I will add them here.

Recommended VS Code Extensions

Elanna Grossman — Sat, 07 Jan 2023 02:10:54 +0000

Visual Studio Code is my code editor of choice. I regularly use Linux, MacOS, and Windows, and it is very nice to have a consistent tool between each operating system. I have listed my recommended VS Code extensions below. In this post, I talk about general development tools I like to use in each operating system.

General

GitLens — Git supercharged Awesome parsing of the project’s git information. This extension pulls in the git history and blame from the project, and can show git history on the highlighted line.
change-case An easy way to change the case of selected text.
Code Spell Checker A regular spell checker. It’s smart enough to parse most words separately in a variable name.
IntelliSense for CSS class names in HTML Auto-completion for CSS names based on existing rules.
Path Intellisense Path auto-completions.
Docker Useful tooling for Docker.
ESLint The de facto Javascript linter.
Excel Viewer Can parse CSV as a table.
Markdown All in One Shortcuts and tooling to help write Markdown in the VS Code editor. My personal favorite utility here is creating and keeping an up to date a table of contents based on the header structure.
Live Server An easy way to launch a server from inside the project.
Todo Tree Helps organize TODOs so they don’t get lost.
Live Share Extension Pack This is a really powerful paired programming tool. It works and is cross-compatible Visual Studio Code, Visual Studio, or in a browser (the session host has to use Visual Studio or Visual Studio Code).

Angular

Angular Essentials A pack of extensions maintained by John Papa, one of the celebrities in the Angular world. I have found this to be a comprehensive set of extensions for Angular, especially since I don’t use snippets much.

C#

C# This is the official C# extension from Microsoft and handles everything including syntax highlighting, IntelliSense, and debugging. It is a dogfooded tool and it shows.

Settings

In addition to the above extensions, I have some settings I configure in Visual Studio Code:

CodeLens for Javascript and Typescript. This parses projects for class, method, and property references and shows them above the class/method/property declaration. It does cause slight slowdown when loading a file, but I consider it a worthy tradeoff.
Breadcrumbs. These show file path breadcrumbs above the editor window.

If I find any other recommended VS Code extensions, I will add them here.

The post Recommended VS Code Extensions appeared first on Hapax Legomenon.

A Curated List of Angular Resources

Elanna Grossman — Tue, 10 Aug 2021 02:18:41 +0000

Having worked with Angular since mid-2017, I have collected many resources that I have found useful. I will keep this list up to date.

Updated Oct 21, 2021 - fixed broken links.

Angular Resources

General Documentation

Angular.io Includes good tutorials, detailed documentation, and API references along with interactive code snippets. This should be the default destination for Angular questions. Note: There are multiple versions of the “Tour of Heroes” tutorial demonstrating different concepts.
Angular.io Resources The official and hopefully maintained list of resources from the Angular team.
John Papa style guide The de facto style guide for Angular has been officially adopted by the Angular team and is now hosted on the official website. It is highly opinionated, but makes good cases for its suggestions. I follow most of it and do not disagree strongly with any of its suggestions.
Netanel Basal Another skilled Angular developer with useful tutorials and deep dive articles.
Angular University Has multiple tutorials and deep dives for all things Angular.
inDepth.dev community Formerly Angular In Depth. Covers RxJS, NgRX and Angular in depth – has articles explaining how and why Angular is architected.
Todd Motto A Google Developer Expert who writes detailed articles explaining Angular functionality and convention. His writing and explanation style differ sufficiently from the official documentation that it is a good supplemental resource.
Strong Brew Technical high level articles for Angular, RxJS, and coding practices.

Essential articles

Angular Dependency Injection Infographic A visual explanation of how Dependency Injection works (and used to work) in Angular, and the different strategies available.
The 7-step process of Angular router navigation Helps demystify the Angular routing lifecycle.
Angular Architecture – Smart Components vs Presentational Components This explains the thought process behind the container/presenter pattern (also referred to as smart/dumb components) very well.
Container components with Angular
Everything you need to know about the ExpressionChangedAfterItHasBeenCheckedError error Here is an explanation of how to prevent an error that learning Angular developers run into a lot.
How to architect epic Angular app in less than 10 minutes! Explanation of the project organization that I prefer.
Choosing The Right File Structure for Angular in 2020 and Beyond !

Angular Best Practices

Performance

10 Tricks to Optimize Your Angular App – Bits and Pieces
Angular – Lazy-loading feature modules Lazy loading splits the app into chunks that are only loaded on demand. This both reduces bundle size, and helps separate discrete features (e.g. the admin dashboard from the user dashboard).
Reduce Change Detection Cycles with Event Coalescing in Angular
Angular OnPush Change Detection and Component Design – Avoid Common Pitfalls
Everything you need to know about change detection in Angular A deep dive into how Angular’s change detection works.
The Last Guide For Angular Change Detection You’ll Ever Need – Mokkapps (Michael Hoffmann) – Freelance Angular Software Engineer This is a wonderful article that explains change detection and provides a lot of visual examples and a working sandbox to test different change detection strategies.
Angular Change Detection Demos Code demo that goes with the above article.
Angular ngFor – Learn All Features, Not Only For Arrays Angular’s template looping directive *ngFor has a lot of neat features, and one of them, trackBy, can help a lot with performance.

Unit Testing

Testing Tools

Error Handling

Expecting the Unexpected — Best practices for Error handling in Angular – Angular inDepth

Security

Angular.io Security This is the official documentation on security in Angular, best practices, and how to avoid creating vulnerabilities.
6 Angular Security Best Practices – Snyk
Angular Security Best Practices – Ordina JWorks Tech Blog

RxJS

Getting Started

Official documentation The official guide for Observables. Easier to read than the API reference on the same site.
Angular.io Observables Angular documentation of Observables and RxJS. All examples are within Angular, and the guide explains how Angular uses RxJS beyond http calls.
RxJS Best Practices

Understanding Higher Order Observable Operators

Pitfalls

Subscriptions

Understanding Hot and Cold Observables

RxJS Error Handling

RxJs Error Handling: Complete Practical Guide

Advanced RxJS

Rx Book This is out of date but it is still one of the best deep dives into how ReactiveX works.
What are schedulers in RxJS

TypeScript

Introduction

Documentation · TypeScript Official documentation resource for TypeScript. Regularly updated.

Advanced Types

Generics

Generics · TypeScript Generics are a great way of avoiding having to use any because they enact ‘generic’ behavior on the type passed in.

All of my posts on Angular are tagged and collected here.

The post A Curated List of Angular Resources appeared first on Hapax Legomenon.

Creating a Multi-Control Custom Validator in Angular

Elanna Grossman — Wed, 23 Jun 2021 03:56:30 +0000

Custom validators in Angular’s reactive form library are one of the most powerful (and in my opinion overlooked) tools a developer has to create better form UI/UX. Custom validators aren’t just limited to a single control. It is easy to evaluate an entire group. This is great for comparing multiple controls. In this article I create a multi-control custom validator that validates two fields if their values match to show an example of what is possible.

As I mentioned in my previous article about custom validators, I like using them to both handle custom logic that the built-in validators don’t, and to be able to create the validation error messages in one spot. This makes custom validators powerful and very reusable.

Creating a Multi-Control Custom Validator

Creating a multi-control custom validator is very similar to creating a single-control one. The validator needs a passed in AbstractControl parameter. In single-control validators, the control is normally a FormControl. However, for multi-control validators, I need to pass in the parent FormGroup as the control. Doing this gives me the scope of all of the children controls inside of the FormGroup. To make this validator more reusable, I also pass in the names of the controls I want to compare. I also can pass in the name of the kind of values I am comparing to make the error messages more dynamic.

I then create variables for the values from the form controls. Once I have those, I set up some simple conditionals. Since I passed in the FormGroup as the AbstractControl instead of a specific FormControl, if I want to set errors on the FormControls, I need to call setErrors() on the specific control. Otherwise, if I just return the ValidationErrors, they will apply to the FormGroup, which isn’t what I want here.

export class MatchFieldValidator {
  static validFieldMatch(
    controlName: string,
    confirmControlName: string,
    fieldName: string = 'Password',
  ): ValidatorFn {
    return (control: AbstractControl): ValidationErrors | null => {
      const controlValue: unknown | null = control.get(controlName)?.value;
      const confirmControlValue: unknown | null = control.get(
        confirmControlName,
      )?.value;

      if (!confirmControlValue) {
        control.get(confirmControlName)?.setErrors({
          confirmFieldRequired: `Confirm ${fieldName} is required.`,
        });
      }

      if (controlValue !== confirmControlValue) {
        control
          .get(confirmControlName)
          ?.setErrors({ fieldsMismatched: `${fieldName} fields do not match.` });
      }

      if (controlValue && controlValue === confirmControlValue) {
        control.get(confirmControlName)?.setErrors(null);
      }

      return null;
    };
  }
}

Now that I have a working validator, I need to wire it up to the component. Since I want to be to interact with multiple FormControls, I need to attach the validator to the parent FormGroup. The FormBuilder takes an options argument after the control config where I can pass in validators. I add the match field validator, along with the names of the controls I want to compare, and what kind of field I’m comparing. I’ve simplified the below code to just focus on what is relevant:

private createForm(): FormGroup {
  const form = this.fb.group({
    password: [
      '',
      Validators.compose([PasswordValidator.validPassword(true)]),
    ],
    confirmPassword: [''],
  },
  {
    validators: Validators.compose([
      MatchFieldValidator.validFieldMatch('password', 'confirmPassword', 'Password'),
    ]),
  });

  return form;
}

As I now having working validation, I can bind the errors to the template. I am still using the loop through the errors object via the KeyValuePipe for simplicity.

<div class="field-group">
  <mat-form-field>
    <input
      name="password"
      id="password"
      type="password"
      matInput
      placeholder="Password"
      formControlName="password"
    />
    <mat-error *ngIf="form.get('password')?.errors">
      <ng-container *ngFor="let error of form.get('password')?.errors | keyvalue">
        <div *ngIf="error.key !== 'required'">{{ error.value }}</div>
      </ng-container>
    </mat-error>
  </mat-form-field>
  <mat-form-field>
    <input
      name="confirmPassword"
      id="confirmPassword"
      type="password"
      matInput
      placeholder="Confirm Password"
      formControlName="confirmPassword"
      required
    />
    <mat-error *ngIf="form.get('confirmPassword')?.errors">
      <ng-container *ngFor="let error of form.get('confirmPassword')?.errors | keyvalue">
        <div *ngIf="error.key !== 'required'">{{ error.value }}</div>
      </ng-container>
    </mat-error>
  </mat-form-field>
</div>

Testing the Validator

Like other custom validators, it is easy to test multi-control custom validators. Writing unit tests for this validator helped me find and handle an edge case that I wasn’t handling initially also. Here are some of the example tests:

  describe('validFieldMatch() default field name', () => {
    const matchFieldValidator = MatchFieldValidator.validFieldMatch(
      'controlName',
      'confirmControlName',
    );
    const form = new FormGroup({
      controlName: new FormControl(''),
      confirmControlName: new FormControl(''),
    });
    const controlName = form.get('controlName');
    const confirmControlName = form.get('confirmControlName');

    it(`should set control error as { confirmFieldRequired: 'Confirm Password is required.' } when value is an empty string`, () => {
      controlName?.setValue('');
      confirmControlName?.setValue('');
      matchFieldValidator(form);
      const expectedValue = {
        confirmFieldRequired: 'Confirm Password is required.',
      };
      expect(confirmControlName?.errors).toEqual(expectedValue);
    });

    it(`should set control error as { fieldsMismatched: 'Password fields do not match.' } when values do not match`, () => {
      controlName?.setValue('password123!');
      confirmControlName?.setValue('password123');
      matchFieldValidator(form);
      const expectedValue = {
        fieldsMismatched: 'Password fields do not match.',
      };
      expect(confirmControlName?.errors).toEqual(expectedValue);
    });

    it(`should set control error as null when values match`, () => {
      controlName?.setValue('password123!');
      confirmControlName?.setValue('password123!');
      matchFieldValidator(form);
      expect(controlName?.errors).toEqual(null);
      expect(confirmControlName?.errors).toEqual(null);
    });

    it(`should set control error as null when control matches confirm after not matching`, () => {
      controlName?.setValue('password123!');
      confirmControlName?.setValue('password123!');
      matchFieldValidator(form);
      controlName?.setValue('password123');
      matchFieldValidator(form);
      controlName?.setValue('password123!');
      matchFieldValidator(form);
      expect(controlName?.errors).toEqual(null);
      expect(confirmControlName?.errors).toEqual(null);
    });

    it(`should set control error as null when confirm matches control after not matching`, () => {
      controlName?.setValue('password123!');
      confirmControlName?.setValue('password123!');
      matchFieldValidator(form);
      controlName?.setValue('password123');
      matchFieldValidator(form);
      confirmControlName?.setValue('password123');
      matchFieldValidator(form);
      expect(controlName?.errors).toEqual(null);
      expect(confirmControlName?.errors).toEqual(null);
    });
  });

Custom validators are easy to make and very powerful. Since they can be made at any level of a reactive form, it is possible to make multi-control custom validators like this one that can interact with multiple controls. This helps developers craft highly reactive UI/UX for users.

Resources

The repository includes unit tests for the validator to help dial in the desired behavior. Here is the repository on GitHub, and here is a working demo of the code on StackBlitz. All of my posts on Angular are tagged and collected here.

The post Creating a Multi-Control Custom Validator in Angular appeared first on Hapax Legomenon.

Exploring Custom Form Validators In Angular

Elanna Grossman — Wed, 16 Jun 2021 04:42:07 +0000

I believe that the reactive form library in Angular is one of the most powerful tools in the framework. Developers can create performant and reactive forms that provide great UI/UX. One part of the reactive form toolkit that I think people often overlook is creating custom validators. In this article I show how to create a custom password field validator and how to use it.

Reactive forms create objects that all inherit from the same AbstractControl. The AbstractControl has an errors object property, which is where I can get or set validation errors for the form or particular control. This errors object contains key value pairs. When using the default built-in validation, these key value pairs are predefined with specific (often boolean) values. That means that I would need to evaluate the error value and decide what error message to show the user. However, it is possible to create custom validators, and they can return key value pairs with error message values instead of booleans. This means that I can set up reusable validators to both perform validation, and handle setting up their own human-readable error messages.

Using the Built-in Validators

The built-in validators are powerful and easy to use. The official documentation shows each one and how to use it. For this example, I want to add the following validation to the password field:

Make the field required.
Require a minimum of 8 characters.
Require at least one number.
Require at least one special character.

In my sample register form, I could add four of the built-in validators to do this:

private createForm(): FormGroup {
  const form = this.fb.group({
    email: [''],
    password: [
      '',
      [
        Validators.required,
        Validators.minLength(8),
        Validators.pattern(/[-+_!@#$%^&*,.?]/),
        Validators.pattern(/[0-9]/),
      ],
    ],
  });

  return form;
}

Then I would bind the error properties to the template, and write messages based on which errors are active:

<mat-form-field>
  <input
    name="password"
    id="password"
    type="password"
    matInput
    placeholder="Password"
    formControlName="password"
    required
  />
  <mat-error *ngIf="form.get('password')?.errors">
    <div *ngIf="form.get('password')?.errors?.required">
      Password is required.
    </div>
    <div *ngIf="form.get('password')?.errors?.minlength">
      Password must be at least 8 characters.
    </div>
    <div *ngIf="form.get('password')?.errors?.pattern?.requiredPattern === '/[-+_!@#$%^&*,.?]/'">
      Password requires at least one special character.
    </div>
    <div *ngIf="form.get('password')?.errors?.pattern?.requiredPattern === '/[0-9]/'">
      Password requires at least one number.
    </div>
  </mat-error>
</mat-form-field>

This works fine, and gives the user reactive feedback on if their password meets the requirements. There are two reasons that I prefer using custom validators, however. The first is that the built-in validators only handle the most common use cases. The second is that I like to consolidate where I create validation error messages. The built-in validators provide me the tools I need to write error messages, but the properties are not readable by regular users. So I need to write the messages by hand, it makes this code hard to reuse. It would be nice to have code where I can keep the responsibility of creating human-readable error messages, and handle any complex validation logic.

Creating a Custom PasswordValidator

Custom form validators are simply functions. I prefer to put them in classes, and I usually make them static because of how straightforward the logic is to write. Custom validators act on the passed in AbstractControl. This is where the I can evaluate whatever I want about the AbstractControl. Custom validators expect one of two values returned. null means that validation passed, and there are no errors. ValidationErrors is just a wrapping for a key value pair and is how I return error messages. These error messages can be static and hard coded, or dynamic. Below I show an example for some simple validation I could do for creating a new password:

export class PasswordValidator {
  static validPassword(isRequired: boolean = false): ValidatorFn {
    return (control: AbstractControl): ValidationErrors | null => {
      if (!control.value) {
        return isRequired ? { invalidPassword: `Password is required.` } : null;
      }
      if (control.value.length < 8) {
        return { invalidPassword: `Password is too short.` };
      }
      if (!CONSTANTS.SYMBOL_REGEX.test(control.value)) {
        return {
          invalidPassword: `Password requires at least one special character.`,
        };
      }
      if (!CONSTANTS.DIGIT_REGEX.test(control.value)) {
        return {
          invalidPassword: `Password requires at least one numeric character.`,
        };
      }

      return null;
    };
  }
}

This custom password validator checks for the same four requirements that I listed separately with the built-in validators. If I know that I will want to always check for those four requirements, it is nice to have them collected in a single method.

I like putting a amount of logic to handle if the field is required or not here (as seen with if (!control.value)) so I don’t need to bind multiple validators to a single control, but that’s personal preference. I moved the regular expressions to a constants file and named them since I can find them hard to read. The default behavior is that form validators update whenever a user changes a value on the form. However, it is possible to do something like add a debounce to tweak how often it fires.

Using the Validator

Custom validators are easy to use. In the component where I set up my reactive form, I can use my custom validators at any level of the form. This means that I can apply the validator to a FormControl, a FormArray, or an entire FormGroup. In a future post I will show how to create a validator that can evaluate and compare multiple control values. Here though, I just need to pass the validator to the FormControl value I am creating. I am using FormBuilder in this example:

private createForm(): FormGroup {
  const form = this.fb.group({
    email: [''],
    password: [
      '',
      Validators.compose([PasswordValidator.validPassword(true)]),
    ],
  });

  return form;
}

Since I made my method static, I invoke it as PasswordValidator.validPassword(true). If I had used a service, I would inject like this.passwordValidator.validPassword(true) instead. As I like to handle if it’s required or not with a single validator, I pass true to the method (again, this is just personal preference and not required when making a custom validator).

Now that I have moved the logic of figuring out what message to show to the user out of the template, I can simplify what is in the template a lot:

<mat-form-field>
  <input
    name="password"
    id="password"
    type="password"
    matInput
    placeholder="Password"
    formControlName="password"
  />
  <mat-error *ngIf="form.get('password')?.errors">
    <ng-container *ngFor="let error of form.get('password')?.errors | keyvalue">
      <div *ngIf="error.key !== 'required'">{{ error.value }}</div>
    </ng-container>
  </mat-error>
</mat-form-field>

I added the second check of error.key !== 'required' here to skip over the required error that Angular adds automatically when I add the required attribute to the input element. For non-example projects, I normally use a custom pipe to handle traversing the errors object rather than the keyvalue pipe here. I’ll explain that in more detail in a follow up article.

Testing the Validator

It is really easy to write unit tests for these kinds of validators. This way I can write custom logic and feel confident that it does what I expect and that I am handling edge cases. Below are some example test snippets, and the rest are here:

it(`should return null if value matches RegEx`, () => {
  passwordControl.setValue('passwordTest1!');
  expect(passwordValidator(passwordControl)).toEqual(null);
});

it(`should return { invalidPassword: 'Password is too short.' } when value is too short`, () => {
  passwordControl.setValue('test');
  const expectedValue = { invalidPassword: 'Password is too short.' };
  expect(passwordValidator(passwordControl)).toEqual(expectedValue);
});

it(`should return { invalidPassword: 'Password requires at least one special character.' } when missing special characters`, () => {
  passwordControl.setValue('passwordTest1');
  const expectedValue = {
    invalidPassword: 'Password requires at least one special character.',
  };
  expect(passwordValidator(passwordControl)).toEqual(expectedValue);
});

it(`should return { invalidPassword: 'Password requires at least one numeric character.' } when missing numeric characters`, () => {
  passwordControl.setValue('passwordTest!');
  const expectedValue = {
    invalidPassword: 'Password requires at least one numeric character.',
  };
  expect(passwordValidator(passwordControl)).toEqual(expectedValue);
});

Between creating custom validators like this and then listening to the form state, developers can create reactive and engaging content for users.

Resources

The post Exploring Custom Form Validators In Angular appeared first on Hapax Legomenon.

Making a Password Strength Component in Angular

Elanna Grossman — Wed, 09 Jun 2021 07:28:38 +0000

The Situation

Reactive Forms in Angular are incredibly powerful and let developers design experiences that provide immediate feedback to users. In this post I show how to use RxJS in a reactive form to provide useful UI feedback for a common use case: creating a password strength component to show password indicators to users creating passwords.

The Register Form

First, I decided to create distinct check box form controls for each password requirement and strength indicator. This lets me update the control for each indicator independently. I set the controls to disabled, so that the values can only be triggered programmatically, rather than directly by the user. The requirement indicator values start as false since none of them should be checked at first. I like to set this up in the parent component where I set up my reactive form. That is because I believe the parent component should be the source of truth for the controls in a form.

I go over creating custom validators like PasswordValidator.validPassword() in a follow up post. For the sake of simplicity in this example, I combined using both password requirement indicators with a validator and the password strength indicator. In a real world scenario, I don’t think I would use the validator with the password strength indicator. To achieve that effect, it would be easy enough to remove Validators.compose([PasswordValidator.validPassword(true)]), below:

private createForm(): FormGroup {
  const form = this.fb.group({
    email: [''],
    password: [
      '',
      Validators.compose([PasswordValidator.validPassword(true)]),
    ],
    passwordMin: { value: false, disabled: true },
    passwordDigit: { value: false, disabled: true },
    passwordSpecial: { value: false, disabled: true },
    passwordSlider: { value: 0, disabled: true },
  });

  return form;
}

The register template is very straightforward. I moved the password strength part to its own component to make it easier to reuse. I pass the form instance with an input binding to app-password-strength.

<form [formGroup]="form">
  <div class="register-field">
    <mat-form-field>
      <input
        name="email"
        id="email"
        type="text"
        matInput
        placeholder="Email"
        formControlName="email"
        required
      />
    </mat-form-field>
  </div>
  <div>
    <mat-form-field>
      <input
        name="password"
        id="password"
        type="password"
        matInput
        placeholder="Password"
        formControlName="password"
        required
      />
    </mat-form-field>
  </div>
  <button
    class="submit-button"
    type="submit"
    mat-raised-button
    color="primary"
    [disabled]="!form.valid"
  >
    Register
  </button>
  <app-password-strength [form]="form"></app-password-strength>
</form>

The PasswordStrengthComponent

In PasswordStrengthComponent, most of the work happens in setupConditionalValidators(). Reactive forms can expose observable streams for individual form controls or the form itself. There are two stream choices: statusChanges and valueChanges. Here, I use valueChanges because I want to update the password requirement and strength indicators as specific values change. setupConditionalValidators() creates a subscription that listens to the valueChanges stream on the password form control. This way it can listen to the values emitted by the password field and update the requirement and strength indicators for each value.

The method then calls setIndicatorValues(), which sets each of the indicator values based on simple checks. As I find some regular expressions hard to read, I moved them to a constants file and gave them descriptive names. The subscription needs to be actively managed, so I added it to an array that is managed by ngOnDestroy. I prefer managing subscriptions this way instead of by using takeUntil(). takeUntil() marks subscriptions as complete as a side effect, and I prefer not to do that. There is a little more code in the component like the control getter methods that I removed here for brevity.

public ngOnInit(): void {
  this.setInitialIndicatorValues();
  this.setupConditionalValidators();
}

private setIndicatorValues(controlValue: string): void {
  let passwordSliderMinValue = 0;
  let passwordSliderSpecialValue = 0;
  let passwordSliderDigitValue = 0;

  if (controlValue.length >= 8) {
    this.passwordMin.setValue(true);
    passwordSliderMinValue = 1;
  } else {
    this.passwordMin.setValue(false);
    passwordSliderMinValue = 0;
  }
  if (CONSTANTS.SYMBOL_REGEX.test(controlValue)) {
    this.passwordSpecial.setValue(true);
    passwordSliderSpecialValue = 1;
  } else {
    this.passwordSpecial.setValue(false);
    passwordSliderSpecialValue = 0;
  }
  if (CONSTANTS.DIGIT_REGEX.test(controlValue)) {
    this.passwordDigit.setValue(true);
    passwordSliderDigitValue = 1;
  } else {
    this.passwordDigit.setValue(false);
    passwordSliderDigitValue = 0;
  }
  this.passwordSlider.setValue(
    passwordSliderMinValue +
      passwordSliderSpecialValue +
      passwordSliderDigitValue
  );
  switch (this.passwordSlider.value) {
    case 0:
      this.strengthHint.message = 'Weak';
      this.strengthHint.color = 'red';
      break;
    case 1:
      this.strengthHint.message = 'Okay';
      this.strengthHint.color = 'orange';
      break;
    case 2:
      this.strengthHint.message = 'Good';
      this.strengthHint.color = 'yellow';
      break;
    case 3:
      this.strengthHint.message = 'Strong';
      this.strengthHint.color = 'green';
      break;
  }
}

/** Set the indicator values based on the initial password form control value. */
private setInitialIndicatorValues(): void {
  this.setIndicatorValues(this.password.value);
}

/** Listens to the password input in the form and updates the requirements list. */
private setupConditionalValidators(): void {
  const passwordControlSubscription: Subscription = this.password.valueChanges.subscribe(
    (controlValue: string) => this.setIndicatorValues(controlValue)
  );

  this.subscriptions.push(passwordControlSubscription);
}

The constants file with the regular expressions looks like this:

interface Constants {
  readonly DIGIT_REGEX: RegExp;
  readonly SYMBOL_REGEX: RegExp;
}

export const CONSTANTS: Constants = {
  DIGIT_REGEX: /[0-9]/,
  SYMBOL_REGEX: /[-+_!@#$%^&*,.?]/,
};

The password strength template just contains the styling for the component along with the form controls:

<form [formGroup]="form">
  <div class="password-container">
    <h2>Password Requirements</h2>
    <div class="password-requirements-row">
      <mat-checkbox formControlName="passwordMin">
        Password length
      </mat-checkbox>
      <mat-checkbox formControlName="passwordDigit">
        Contains at least 1 digit
      </mat-checkbox>
      <mat-checkbox formControlName="passwordSpecial">
        Contains at least 1 symbol
      </mat-checkbox>
    </div>
    <mat-slider
      class="password-strength"
      [max]="3"
      [min]="0"
      formControlName="passwordSlider"
    >
    </mat-slider>
    <mat-hint class="hint-text" [ngStyle]="{ color: strengthHint.color }">{{ strengthHint.message }}</mat-hint>
  </div>
</form>

I made a simple UI using checkboxes for the password strength indicators. Using the password valueChanges subscription above though, it would be easy to design any number of highly reactive UIs to help the user as they set up a password.

I made this as a simple tutorial example. If I were to use this in production, I would also pass a config object to PasswordStrengthComponent which gives the names for the indicator controls. That way, I could have that implementation come from the parent component.

Resources

The repository includes unit tests for the indicator controls to help dial in the desired behavior. Here is the repository on GitHub, and here is a working demo of the code on StackBlitz. All of my posts on Angular are tagged and collected here.

The post Making a Password Strength Component in Angular appeared first on Hapax Legomenon.

Making a LocaleUpperCasePipe for Angular

Elanna Grossman — Mon, 22 Mar 2021 11:57:04 +0000

Paris Métro Graffiti

The Problem

Angular uses pipes to help transform how data appears in the template. It provides a number of built-in pipes like DatePipe and UpperCasePipe. However, while working on a localization feature for a work project, a coworker pointed out that UpperCasePipe uses toUpperCase() under the hood. toUpperCase() is not locale aware, and will fail at capitalizing letters for certain locales correctly, namely Turkish. Since it is easy to create custom pipes in Angular, I decided to create one that is locale-aware. In this post, I will share the code for the LocaleUpperCasePipe, explain how to use it, and provide links to the repository and a demo.

When given a lowercase value like “ılıman ilik”, the UpperCasePipe will return ILIMAN ILIK, which is wrong. The correct result should be ILIMAN İLİK. (I apologize for the silly Turkish. I am not a speaker and I was looking for an easy test value).

The LocaleUpperCasePipe

Pipes can take arguments. I have designed this one to accept an optional locale argument. If it receives no argument, it uses a fallback value of a default language.

import { Pipe, PipeTransform } from '@angular/core';

import { Constants } from '../../utils/constants';

@Pipe({ name: 'localeuppercase' })
export class LocaleUpperCasePipe implements PipeTransform {
  transform(
    value: string | null | undefined,
    language?: string
  ): string | null {
    if (value == null) {
      return null;
    }
    if (typeof value !== 'string') {
      return '';
    }
    const locale = language || Constants.defaultLanguage;

    try {
      return value.toLocaleUpperCase(locale);
    } catch (error) {
      console.warn(error);
      return value.toLocaleUpperCase(Constants.defaultLanguage);
    }
  }
}

I designed the pipe to prefer a passed-in locale argument to the fallback value. If the locale argument is an invalid value, the pipe catches the error, outputs it as a warning to the console, and falls back to using the default locale value. There is a default language value so in cases where the default language would be something like Turkish, it can be set, and then the pipe can be used without needing to pass in an argument (unless capitalizing a word from a different language).

The constants file looks like this:

export interface IConstant {
  defaultLanguage: string;
}

export const Constants: IConstant = {
  defaultLanguage: 'en-US',
};

Using the Pipe

Here is an example of using the pipe with no argument:

{{ testValue | localeuppercase }}

And here is the pipe with a locale argument:

{{ testValue | localeuppercase: "tr-TR" }}

Resources

The repository includes unit tests for the pipe to help dial in the desired behavior, and shows multiple examples of the pipe being used.

Here is the repository on GitHub, and here is a working demo of the code on StackBlitz. All of my posts on Angular are tagged and collected here.

The post Making a LocaleUpperCasePipe for Angular appeared first on Hapax Legomenon.

DEV Community: Elanna Grossman

How I Switched My Website to Analog

Introduction

Planning

New Features

Styling

Data Handling

Other Priorities

Accessibility

SEO

Building the Site

Routing

Archive Component

Pills Component

Search

Images

Cover Images

Popover

Skeleton Loader

Masonry Grid

Object Fit

Broken Image Directive

Draft Functionality

RSS

Tag Cloud

Static Site

Gotchas

Conclusion

Time for a Change: Switching to Analog

Hapax Legomenon 3.0

The Use Case

Enter Analog

Recommended Development Tools in Linux, MacOS, and Windows

Development Tools

Package Manager

Terminal

IDE

Code Editor

Git Client

Database Tools

HTTP

Notes

Sync

Recommended VS Code Extensions

General

Angular

C#

Settings

A Curated List of Angular Resources

Angular Resources

General Documentation

Essential articles

Angular Best Practices

Performance

Unit Testing

Testing Tools

Error Handling

Security

RxJS

Getting Started

Understanding Higher Order Observable Operators

Pitfalls

Subscriptions

Understanding Hot and Cold Observables

RxJS Error Handling

Advanced RxJS

TypeScript

Introduction

Advanced Types

Generics

Creating a Multi-Control Custom Validator in Angular

Creating a Multi-Control Custom Validator

Testing the Validator

Resources

Exploring Custom Form Validators In Angular

Using the Built-in Validators

Creating a Custom PasswordValidator

Using the Validator

Testing the Validator

Resources