ngx-fragments

Ever needed a modal, popup or sidenav that worked based on the URL?
This module takes care of that!

This module does NOT provide the implementation of above mentioned use cases.

Demo

Getting Started

npm install ngx-fragments

Usage

Create Fragment Container Component

The container component is basically the component you want to render your child components content.
Since this module does not provide any container components, we have to provide it to the module.

An example modal container component could look like this:

import { Component } from '@angular/core';
import { FragmentOutletComponent } from 'ngx-fragments';

@Component({
  styles: [`
   :host {
    position: relative;
    display: block;
  }
  
  /* The Modal (background) */
  .modal {
    display: block;
    position: fixed;
    z-index: 9999;
    left: 0;
    top: 0;
    width: 100%;
    height: 100%;
    overflow: auto;
  }
  
  .modal-content {
    margin: 15% auto;
    padding: 20px;
    border: 1px solid #888;
    width: 80%;
  }
  
  .close {
    color: #aaa;
    float: right;
    font-size: 28px;
    font-weight: bold;
  }
`],
  template: `
  
    <div class="modal" (click)="outerClick($event)">
    
        <div class="modal-content">
            <span class="close" (click)="outlet.close()">&times;</span>
            <ng-content></ng-content>
        </div>
        
    </div>

  `
})
export class MyCustomModalContainerComponent {
  constructor(public outlet: FragmentOutletComponent) {
  }

  public outerClick(event: any): void {
    event.stopPropagation();
    if (event.target.className === 'modal') {
      this.outlet.close();
    }
  }
}

By injecting the FragmentOutletComponent we have access to the close function.

Create Entry Component

Now that we have a container, we will create a component which we want to show inside the container.
For this we will create a simple GreeterModalComponent. This component will display the value of the queryParameter as greeting.

import { Component } from '@angular/core';
import { FragmentOutletBase } from 'ngx-fragments';

@Component({
  styles: [
    `.greeting {
      font-size: 1.5rem;
      color: cornflowerblue;
      text-shadow: #333333;
    }
    `,
  ],
  template: `
    <div class="greeting">
      Greeting: {{ whenQueryParamValueChanged$ | async }}
    </div>
  `,
})
export class GreeterModalComponent extends FragmentOutletBase {
  constructor() {
    super();
  }
}

Notice that we extend FragmentOutletBase class. This class provides the following observables we can subscribe to.

| Property | Description | --------------------------- | ---------------------------------- | | whenClosed$ | Event on close | | whenQueryParamValueChanged$ | Event on query param value changed | | queryParamValue | Initial query param value |

Provide the configuration

The configuration object is a dictionary of Fragment where each key can have his own containerComponent and entries list consisting out of FragmentEntry objects

export interface Fragment {
  containerComponent: Type<any>;
  entries: FragmentEntry[];
}

| Property | Description | --------------------------- | --------------------------------------------- | | containerComponent | Angular component we want to use as container | | entries | List of FragmentEntry objects |

export interface FragmentEntry {
  key: string;
  type: Type<T>;
  priority?: number;
}

| Property | Description | --------------------------- | -------------------------------------------------------------------- | | key | The query parameter key to use to display this fragment | | type | The component to render inside the container | | priority (optional) | Useful if you want to control which fragment should always be on top |

Configuration (based on the example from above)

const configuration = {
  modal: {
    containerComponent: MyCustomModalContainerComponent,
    entries: [
      {
        key: 'greeter',
        type: GreeterModalComponent,
      },
    ],
  }
}

Finally, pass the configuration to the forRoot method in your AppModule.

@NgModule({
  imports: [
    NgxFragmentsModule.forRoot(configuration)
  ]
})

Or use forFeature for lazy loaded modules

// In AppModule
@NgModule({
  imports: [
    NgxFragmentsModule.forRoot() // --> configuration object is optional here
  ]
})

// In Feature Module
@NgModule({
  imports: [
    NgxFragmentsModule.forFeature(configuration) // --> configuration is REQUIRED for lazy modules
  ]
})

To test the working, we have to navigate to the route we defined.
Since our greeter modal is part of the modal parent object, the key greeter will automatically get prefixed with modal: to avoid query parameter collisions.

 <a [routerLink]="[]" [queryParams]="{'modal:greeter': 'Hello from year 2021!'}" queryParamsHandling="merge">open greeter</a>