JSS Angular Tips / Best Practices

Do not use the <base> tag!

Most Angular applications make use of the <base> tag in their HTML template to set a base href for routing. JSS Angular apps cannot use this technique, as it is incompatible with Sitecore's Experience Editor capabilities. Instead JSS Angular apps should use the APP_BASE_HREF token to provide their base href via dependency injection, thus avoiding the other semantics that come with a <base> tag. The sample application does this, but it can become an issue integrating with any existing Angular infrastructure.

Ensure components are display: block

When writing UI components in Angular, the default style for display for all new components is inline. For components to work as expected in the Experience Editor, set the display style to display: block; for all components root elements. I.e:

:host {
  display: block;
}

Another way of working around this is to change the selector of the component to use an existing DOM element like div to get a display: block;. This approach is discouraged by the Angular Style Guide but is an effective way none the less. For example:

@Component({
  selector: 'div [app-hello-world]',
  templateUrl: `
    Hello world
  `,
})
export class HelloWorldComponent {
  rendering: any;
}

Use sc-placeholder as an attribute

Your application DOM will be cleaner if you utilize sc-placeholder as an attribute, rather than a custom element, for example instead of <sc-placeholder> use <div sc-placeholder>.

Use ng-container if necessary with structural directives

Because JSS makes use of structural directives for its field helpers, other structural directives such as ngIf, ngFor, and ngSwitchCase may need to be applied on a wrapper such as <ng-container />. Angular does not allow multiple structural directives on a single element. For example:

<ng-container *ngIf="condition">
  <span *scText="myField"></span>
</ng-container>