Entry Components

There are two types of components within an Angular application: declarative and entry components.  Declarative components are what you are most used to dealing with – they are generated by declaring a reference to the selector in a template.  Entry components are imperatively loaded by type.  There are two ways in which you previously have interacted with entry components, most likely without knowing it:

• The root application bootstrapped component – generated during the bootstrap process and loaded into the DOM as the application starts
• Routed components – dynamically created by the router and loaded into the DOM in the router-outlet

For a component to be declared as an entry component, it must be added to the entryComponents array in the module.  Below is the module definition for our sample where you can see the entryComponents definition:

So what exactly is an entry component? For that we can reference the Angular documentation on entry components:

For production apps you want to load the smallest code possible. The code should contain only the classes that you actually need and exclude components that are never used. For this reason, the Angular compiler only generates code for components which are reachable from the entryComponents; This means that adding more references to @NgModule.declarations does not imply that they will necessarily be included in the final bundle.

In fact, many libraries declare and export components you’ll never use. For example, a material design library will export all components because it doesn’t know which ones you will use. However, it is unlikely that you will use them all. For the ones you don’t reference, the tree shaker drops these components from the final code package. If a component isn’t an entry component and isn’t found in a template, the tree shaker will throw it away. So, it’s best to add only the components that are truly entry components to help keep your app as trim as possible.

So when an Angular application is built, Angular will start at all entry components and walk down the template tree to see what is used in order to build the application bundle.

There are some complexities when using entry components in a lazy loaded module that can cause some unexpected headaches. The simplest solution is to declare all entry components in non-lazy loaded modules, however there are workarounds available when needed. For more detail see the related issue #14324

NOTE: With all that being said, the Ivy rendering engine aims to remove the need declaring entry components as this will automatically be handled by the @Component decorator.

Another pattern is to use a directive. In the directive you can get access to the ViewContainerRef for the directive’s element using dependency injection and then access that through the ViewChild instance.

Let’s walk through what is happening here to discuss each step:

1. Create the factory variable to hold the correct factory depending on the data in the request.  This demonstrates how we can programmatically determine which type of component to create.  We can select between as many components as we want as long as the component is defined as an entry component.

 

2.   Create a target variable to hold the correct ViewContainerRef where the component should go.   Here we are selecting by using the index value passed in by the request object.

 

3.  Create the component by passing the factory to the ViewContainerRef instance.   The reference to the resulting component is returned from this method so we can access that later to modify the component.

 

4.  Set input values on the component by interacting with the instance on the ComponentRef handle created in step 3. 

 

5.  Subscribe to output events using the same instance property.  Here you can see that when the remove event is fired we call the destroy method on the ComponentRef.   This triggers Angular to remove the component from the DOM and fire all the destroy life-cycle hooks.

 

6.  Keep a reference to all the components we create.   We don’t further interact with them in this example but it is often helpful to keep this reference for further interaction (generally destroying the component from some other interaction).

 

Here you can see the components getting created in different locations and styles dynamically, they also function as independent components by tracking the creation time and closing individually.

When clicking the button to generate a value, both cards showed a spinner and the same resulting random number.  This happens because all services are singletons in Angular when injected at the root level.  When an object is created that requests a provider through the constructor, Angular will pass the same instance to all objects that request the provider.  Normally, this is what we want and allows for a single location to store and share data throughout an application and ultimately manage the state of the application.  This default approach is exactly what is expected for something like an authentication service, we wouldn’t want multiple instances that have different users or authentication states. But in this case, the default approach is misleading and could lead to unexpected behavior.

To test this, I’ll add the option to create cards of both types in our home component:

Now, when clicking a single load button on a globally scoped service component we can see all the global components react and start loading as before and also load the same random value from the service as before – however the components with a locally scoped service remain in the initial state. when clicking the load button on one of those services it will load separately and create a different random number.  The other locally scoped component still remains in the initial state. 

You can see how with a single change we can control how data is shared and controlled in the application.  Our global cards are bound together and work off the same set of data, the local cards have their own service instance and don’t share data with each other. 

The buttons are still bound to the isLoading value for the instance of the provider that comes from the parent component.  Remember, Angular walks up the component tree to find the lowest level provider to inject so the button will find the service scope at the global or local level depending on the setup of the parent. This means you can alter the provider at any level of an application – a module, a route component, down the the smallest display component and alter the behavior for any children.

We don’t see an injection error, we just aren’t seeing the mock value because an actual instance of the service is being used.  The creation of the component is lower in the tree than the TestBed module, so that takes precedence.  What needs to be done is to override the component level definition:

Now the test is using the mock service we as we expect it to.

The high level overview of this component is:

1. It uses an array of a RatingStar class that is used to determine which icon to show for a given star

 

2. The rating array is recalculated whenever an input changes or the user clicks on a star 

 

3. The user’s click on a star also emits the new value to enable two way data binding

The resulting component is used in a parent component bound to a max rating input and displays the output rating value to verify functionality.

Using the Component without ControlValueAccessor

We have a component that gives us some data, let’s see if we can use it in a form.  Below is the form test bed we will use for testing, it includes the following features:

1. A native input for comparison to the custom control we are building
2. The custom rating control – note that the two way binding to rating is no longer included or needed
3. Default values for each control
4. Options to enable or disable the entire form
5. A button to reset the state of the form
6. Output of the form value and touched status

The error specifies that for the element we specified as the ‘rating’ form control, Angular isn’t able to find a value accessor to know how to interact with the component.  So what exactly is a value accessor?

The ControlValueAccessor Interface

ControlValueAccessor is an interface than Angular uses to keep the view in sync with forms data models and vice-versa.  There are 4 methods on the interface, one of which is optional.  We will walk through each method to better understand how Angular handles forms under the hood:

WriteValue

The writeValue method is responsible for updating the view when there are programmatic changes to the form.  In the example of our rating component, this would be when the Input value changes for the rating and we need to recalculate which stars are shown.

RegisterOnChange

The registerOnChange method is called at the initialization of the form and registers a callback function to notify Angular when our control view has changed and the data needs to propagate to the form data model.  The parameter of this method is a function that the control will need to save the reference and then call at the appropriate times.  In our example, this should fire whenever a user clicks a star.

RegisterOnTouch

The registerOnTouch method is similar to the registerOnChange method as it also registers a callback function.  This function is to notify the forms data model that the control has been touched.  In a standard input, this is the blur event when a user clicks or tabs into the input but has not yet made a change.  In our example, there is no blur method so we won’t have anything to implement.  This is not uncommon and the touched property will get updated along with the change callback.

SetDisabledState

The setDisabledState method is an optional method for the interface.  The method receives a boolean parameter that specifies if the control should be disabled or enabled.  This is used to set the appropriate styling on the component to signify the state.

Implementing ControValueAccessor on a Component

There are two necessary steps to set a component to serve as a form value accessor, we must implement the ControlValueAccessor interface and also identify the component as a control value provider.

Step 1 – Interface Implementation

We can implement each interface method one by one to see how they function.

Write Value

To implement writeValue we will need a way to store the current value of the control within the component.  We can use the rating property, but we no longer need to set it as an input to the control.  When writeValue is called, we should set the rating to the provided value and update the view:

To implement registerOnChange we need a property to save a handle to the function provided.  This method can replace the ratingChange event we had implemented as it serves the same exact purpose.  All we need to do is save the method passed into the function and call it with the new value every time the control changes:

RegisterOnTouched

We could leave registerOnTouched as an empty function as we don’t really have a touch event for the form control.  However, for demonstration we can consider the control touched when the user hovers over the rating.  All we need to do is call the method whenever the mouseleave event occurs on the wrapping element:

The setDisabledState method is optional, but we can fairly easily implement it for this control.  All we need to do is apply some styling to gray out the control and prevent the user click’s from changing the value.  First – in the component we need to track if the control is disabled and make a change to setRating to stop any changes from happening when disabled:

Step 2 – Control Provider

Even with the ControlValueAccessor interface implementation we still get the same error as before when testing the form.  The reason is that once the code is compiled, Angular has no way to identify that a component implements an interface.  Instead, we need to register the component as a provider so Angular can easily obtain a reference to the class it will use to communicate with the form view.  To do so, we can add a provider to the RatingControlComponent:

Control Defined Validation

Custom controls may have internal validation that is always active – for example a date picker control may validate that the input is a valid date.  For this example we can implement a minimum rating option that we define as an input to the component. To prepare we can add an input to the component to

Validate

The required method to implement is the validate method.  It provides the control as a parameter (as an AbstractControl) to the method and expects a null (valid) or a key-value pair (invalid) result.  This signature is very similar to implementing any custom form validator.  For our example, we just want to make sure that the value is above or equal to the minimum rating:

RegisterOnValidatorChange

The registerOnValidatorChange method is optional and registers a callback to call whenever the logic to determine if the control is valid changes.  If the validation is a static check then this is not required.  Going back to the date picker example we would only want Angular to check the validation whenever the control value changed.  In our example, a change from outside the form (the minRating input value) could impact the valid status of the control so we want to execute the callback to trigger Angular to recheck the control.  It’s sufficient for this control to just put the callback in the ngOnChanges method.

Provider Registration

We also need to register the component as a Validator, this is nearly identical to the process for ControlValueAccessor just using a different token:

User Defined Validation

Custom controls can have validation also applied the way you would for any other input.  Here we can make the rating required so we can see how the two methods of validation interact:

Visualizing Status

We want to be able to see when the component is invalid, so we can add some simple CSS to the form component to change the stars to red when invalid.  Angular applies a ng-invalid class to controls automatically when they are not valid that we can utilize:

Testing Validation

With this in place, we can test the validation and see how the control reacts.

We can see that when the rating goes below the minimum the control is invalid. Also, when it is reset the required error is triggered and the control is also invalid.  There is no difference between the two methods for how the control displays as both will add the ng-invalid class to be used for styling.

To begin, we can create a component that will represent our sub form.  We want the form to have three inputs: first name, last name, and email address.  We will implement some validation by requiring the last name and validating the email address pattern.  I have added some validation styling using Bootstrap to help clearly show the status of the controls at all times:

Implement ControlValueAccessor

Just as with a single value control, we can implement ControlValueAccessor for our sub-form.  The forms API makes some of this quite easy to implement, the relevant changes are show below:

Template

Implement Validator

We also want any validation errors on our form to propagate to the consuming parent level form.  In order to do this, we need to implement the Validator interface.

Register Providers

Lastly – we just need to register the component as a value accessor and validator provider:

The sub form works as expected to populate the user data, validation on the individual controls in the sub form carry to the parent form validity, and all controls follow the disabled and reset commands just as the native input on the parent level of the form.

To follow along with the articles there a two repositories created: a starting point and final solution.

In order to use a custom implementation of the RouteReuseStrategy, you need to complete two steps:

1. Create a class extending the RouteReuseStrategy – a sample minimal implemenation is below that uses the default Angular functionality as a starting point:

A common situationin web applications is a master-detail relationship.  There is some master page (e.g. search results) which the user can select individual details to view.  In this pattern, we are going to set a few constraints for how we want the application to perform:

• The master page should have some interactivity state that should be maintained between detail views such as sorting, filtering, etc. – we will represent this by a random number displayed in the component where if we maintain the same random number we can demonstrate a preservation of the state of the component

• The detail is viewable via a distinct URL containing an ID for the detail record

• The detail view should load the details upon routing and be able to run some initialization for the detail 

• Components need to run cleanup code when destroyed such as unsubscribing from observables – we will represent this by logging a message to the console. 

We can implement two commonly used designs to meet the requirements.  As we will see, each can have some drawbacks and areas that we can gain additional control using the RouteReuseStrategy.  Both approaches will use the same detail page and a similar base class for the master page. 

Shared Components

This example will share as much as possible between the implementations to help distill the different approaches to only the differences. 

Master

The first shared functionality is a base abstract class to be used by the master page.

There are a few things happening in this component to take note of: 

1. When the component initializes, it generates a new list of results – this represents user interaction with a list of items such as filtering or sorting
2. The component logs a message with an identifier to be overridden by the consuming component

Detail

 Both approaches will use the same detail component:

There are a few things happening in this component to take note of:

1. When the component initializes, it gets the route parameter from the URL to display in the view – this represents any data loading for the detail from a back-end service

 

2. Generates a new random value to display in the view – this represents some view initialization for the detail page

 

3. The component logs a message with the route parameter when it is destroyed 

 

Parent-Child Design

The first design is a parent-child relationship where the contents of the master page stay on screen when viewing the detail.  This is best used when the detail is small and can reasonably fit on the same page. This method places a router-outlet in the master page to display the child content: 

And adds the detail as a child route for the detail in the application route configuration:

We can test and see how this setup meets our needs when navigating between detail pages:

It is also important to note that the console for the application is completely empty, but when navigating elsewhere we see the destroy message. 

When comparing these results to our requirements, we see the following results: 

• PASS – Master page is maintained 

• PASS – Detail view is a unique URL 

• FAIL – Detail view initialization does not run – the random value is the same every time even when routing between different details

• PARTIAL – Detail component is never cleaned up between detail views, but it is after navigating away 

This approach initially results in one failure and one partial that we need to review.  Why does this fail to meet our requirement? 

Look at the Angular DefaultRouteReuseStrategy class – specifically the shouldReuseRoute method.  The implementation returns true when the destination route has the same route configuration as the source route.  When going from one detail to the next this is always true – only the parameter changes and the same route configuration and components are used.  When the shouldReuseRoute method returns true, Angular will not destroy the component tree in turning firing the ngOnInit and ngOnDestroy hooks – instead the only thing that happens it the router emits new values for the route parameters and other Observables.  Therefore, we see the Detail ID update but not the random number.   

We could easily solve the random number generation issue by moving the code into the subscribe callback on the params Observable.  This is often the best method in a detail type view to distinguish between code that creates the component and updates its contents when new data arrives or the route parameter changes.  Angular is designed around the idea of using Observables for communication and it shows here.  Most of the time, using the approach of binding to the param update instead of the overall life-cycle hooks will meet your application needs, but what happens when it doesn’t?  What if we really need the ngOnDestroy hook to fire when navigating away for that parameter and not just the component? 

Returning to the RouteReuseStrategy – we can provide a custom implementation of the shouldReuseRoute method. We can set up a custom class implementation as discussed earlier copying the functionality of the default Angular implementation.  The only change we will make now is to not reuse any routes: 

With only this change let’s test again and see what happens when we select a detail this time:

The ngOnDestroy hook runs all right, but we’ve made this far worse.  The ngOnDestroy hook ran for the ParentComponent as well and we lost the state of the parent, we have new random links so a fresh search to the back-end has been called and the user loses all interaction.  We can now see why Angular has the default functionality we saw earlier.  When a routing event happens, it doesn’t just happen at the detail level.  Angular needs to review the entire component tree generated by the route.  When routing between siblings, the default functionality keeps the parent components intact and only rebuilds what is necessary – which not only gives a mostly expected behavior but has large performance benefits as well.  

What we need is a way to direct Angular to only rebuild certain components but reuse others by default.  We want to add the default functionality back in to shouldReuseRoute and only deviate when we specifically request it.  We can accomplish this by using the data property on the route configuration which is designed exactly for this type of extensibility to a route.  Let’s add a flag to the detail route definition: 

And check for this in shouldReuseRoute: 

Now to test again:

Excellent!  We now are only rebuilding the detail component and we leave the parent component untouched.  We have a design that meets all our requirements – just be aware of the consequences if the detail view is to have any children added to it. 

Search-Detail

The other design approach is to create two separate pages, a search results page and a detail view page.  This situation becomes far more desirable than the Master- Detail as the detail page gets larger and adds functionality that doesn’t easily fit on a single page.  It is also very reasonable for a single site to employ both approaches – for example JIRA allows users to switch between both display options when reviewing search results. 

To implement this approach, we create sibling routes instead of a parent-child relationship.  These can be moved around to different parents depending on the desired URLs for the application, but we will put both under an empty parent to match the URL design of the Parent-Child approach: 

Let’s review how this stacks up against our requirements: 

• FAIL – The master page loses its context when we return to it 
• PASS – Detail view is a unique URL 
• PASS – Detail view initialization runs and gives a new random value 
• PASS – Detail component is cleaned up between detail views 

This approach gives an opposite problem as the Parent-Child design.  We initialize the detail view as expected, but we lose the context of the search results.  

NOTE: The problem we had before with the initialization of the detail view still would exist if the detail view provided a direct link to another detail – this approach just doesn’t show it with this testing because we are using the master page to navigate between details.  

As we are navigating to a new page, we need some way to store the results of the search page somewhere in memory so we can retrieve it when returning to the page.  There are three commonly seen approaches to this: 

1. Using a service or other state management technique, but this approach often requires manually binding everything in the component into a service which gets tedious and error prone as the application grows. 

 

2. Use the Parent-Child approach and hide or cover the parent page when a detail is visible (e.g. detail is a modal window or some other overlay).  This again can work for simple implementations but has drawbacks for side effects and requires tightly coupling the components. If trying to use a full screen overlay this can also have adverse effects on usability if the user uses the back button to try to go back to the parent.

 

3. RouteReuseStrategy to the rescue! 

To see how we can use RouteResuseStrategy we need to examine the process of routing and how the methods are used: 

1. shouldDetach – This determines if the route the user is leaving should save the component state.  

 

2. store – This stores the detached route if the method above returns true.

 

3. shouldAttach – This determines if the route the user is navigating to should load the component state.

 

4. retrieve – This loads the detached route if the method above returns true.

With these methods, we would expect the following for our custom implementation: 

• shouldDetach returns true for the search results page and false for all other routes 

 

• shouldAttach returns true when we have a saved search result 

 

• we need a way to clear a saved search for when the user conducts a new search 

Let’s start with a similar approach we took before by adding a flag to the route configuration.  This could also be done through identifying the URL or any other identification technique: 

This gives a straightforward approach to the shouldDetach method: 

And to store the component we need an internal map to use for storage, we can add this as a private property to the custom RouteReuseStrategy class: 

And now to store the component under a unique key (this is important to prevent conflict between multiple saved routes if this strategy is used for multiple routes): 

That completes the setup for saving the component when leaving, now to check if we should load a saved component when navigating to a route we can check if we have anything saved for the provided route and return the value as needed: 

Now we can test with this implementation of RouteReuseStrategy: 

Success!  We are maintaining the search result component state across navigation and creating a new detail component for each detail we view. 

There is one remaining item to address, what happens when we want to conduct a new search?  Even if the contents of the search result page are populated via an Observable, we may still want the ngOnInit hook to fire to reset the sorting, filters, pagination, etc.  We need a way to clear the saved component on demand.  Let’s create a method to do so in the custom RouteReuseStrategy class: 

We need a way to access this method however.  Think back, what is the key to implementing a custom RouteReuseStrategy in the first place? We implemented a provider – we can use that! This would likely happen in a service and be executed whenever the user conducts a new search, but for simplicity lets add a button on the detail page: 

Note we need to cast the injected object to our custom class – the injection token is for the abstract class so that’s all that Typescript gives us.  Also note that we need to provide the URL key that was generated in our class implementation as the saved handle key.  Keep this in mind when determining an implementation for triggering a save of a route.  This example mixed a URL route and route config data, but generally a single approach is preferred for simplicity and maintenance.  

Let’s see this in action – first a test to make sure it still works as before then clearing the search: 

There we have it – a new search result any time the Clear Search button is clicked.  There is one very subtle problem left.  We have a new search component – but the old one never got destroyed! This would result in memory leaks and other potential unintended consequences.  When Angular detaches a component, it pulls it out of its responsibility and hands it over to our RouteReuseStrategy implementation.  When we cleared the saved handle, we just removed the object from our tracking map, but that never triggers the lifecycle hooks we would expect.  Let’s add some logic to address this in our custom RouteReuseStrategy: 

We have access to the component instance itself from the saved handle so all we need to do is call destroy to trigger the destruction life-cycle of the component. 

Let’s say we have a reporting dashboard with 3 components, a criteria component, a results component, and an input component.  The input component provides the trigger to run or update the report, but we need to get the criteria from a separate component in order to know what to run.  That builds a request to send to a service, and displays the resulting data in the results component.  We have some unique situation that prevents the input component from interacting with the criteria component, for example the input is a toolbar and the criteria is a filter section in another location.  We will need to get the criteria as it current is set at any point – this means we need to use ViewChild instead of an Output event:

To test this component, we will need to generate a testing component that we can use to render instead of the actual component.  The first step we can implement is leveraging TypeScript to provide some insurance that our mock implementation aligns with our actual implementation.  We can do this by using an interface that we implement for the component and the mock component.  Let’s implement an interface now.  We can even make it generic to the type of data we get from the service so we could re-use this for other criteria or forms:

Mock Component

Let’s start by creating our test spec, if there is anything unfamiliar here then review the testing documentation from Angular.  We set up a standard test with a service spy providing some dummy data.

Secondly, notice the selector of the component.  This must match the selector for the actual component.  This is how Angular finds the component to inject in the template, so the selector (and Inputs and Outputs) must match.  We just need to declare the component in our test to use it:

Black Slate takes the worry out of custom software development.