JSS for Angular API reference

Version: 22.x

The JSS Angular SDK provides modules, components, placeholder, and field helper directives to help render components and fields based on data returned from the Sitecore Layout Service.

Registering components in an Angular module

The SDK for Angular comes with modules, components, and other utilities that assist development. When creating a module, you can add a component to the list of components that can be rendered by a placeholder using the withComponents method provided by the JssModule class:

RequestResponse

import { JssModule } from '@sitecorelabs/sitecore-jss-angular';
import { WelcomeComponent } from './components/welcome/welcome.component';

@NgModule({
  ...
  declarations: [
    WelcomeComponent,
    ...
  ],
  imports: [
    JssModule.withComponents([
      { name: 'Welcome', type: WelcomeComponent }
    ])
  ],
  ...
})
export class FooModule { }

Note

In the Angular sample app, JssModule is imported and dynamically generated by convention, with the components being registered based on their presence on the disk at build time. This reduces the maintenance of the component registrations.

Placeholder directives

JSS for Angular provides a component to help render placeholders returned by Layout Service. The placeholder component dynamically instantiates additional Angular components based on the components defined in the Layout Service data.

The basic placeholder technique consists of passing the rendering data injected into the component:

RequestResponse

<sc-placeholder name="jss-styleguide-layout" [rendering]="rendering"></sc-placeholder>

Advanced usage is also possible, using templates to customize the markup emitted around each child component:

RequestResponse

<div class="row" sc-placeholder name="jss-reuse-example" [rendering]="rendering">
  <ng-template renderEach let-rendering="rendering">
    <div class="col-sm">
      <sc-render-component [rendering]="rendering"></sc-render-component>
    </div>
  </ng-template>
  <ng-template renderEmpty let-renderings="renderings">
    <div class="col-sm">
      <sc-placeholder [renderings]="renderings"></sc-placeholder>
    </div>
  </ng-template>
  <ng-template scPlaceholderLoading>
    <img src="loading.gif">
  </ng-template>
</div>

See the layout reuse example in the sample app's style guide for more details about advanced placeholder techniques.

Field helper directives

The library provides structural directives to help output Sitecore field values. The benefit of using structural directives is, as a developer, all features of a tag are available, and not wrapped inside another component. When running inside Experience Editor, a marked tag is replaced with another element for editing if the field is editable.

For example, to enable editing on an image:

RequestResponse

<img *scImage="rendering.fields.logoImage" />

Here is a list of all supported structural directives, and how they are used.

Note

In the following examples, we assume the field is data coming from a placeholder component.

Text

RequestResponse

<p *scText="field; editable: true; encode: true"></p>

This structural directive supports the following input properties:

Name	Description
default / `scText`	The component or route field you wish to render. Usually of Sitecore type Single-Line Text or Multi-Line Text but can be used with numeric types as well.
`editable`	Indicates whether the experience editor / Sitecore-formatted HTML output should be used. (Default: true)
`encode`	Enables or disables HTML encoding of output value. A false value also implies editable: false. (Default: true)

For Multi-line Text, the provided editable value will have any line breaks replaced by<br /> already. If using the non-editable value, you can process field.value yourself to replace JSON newlines with the desired markup, or use a CSS white-space value such as pre-wrap.

RichText

RequestResponse

<div *scRichText="field; editable: true"></div>

This structural directive supports the following input properties:

Name	Description
default / `scRichText`	The component or route field you wish to render. Should be of the Sitecore type Rich Text.
`editable`	Indicates whether the experience editor / Sitecore-formatted HTML output should be used. (Default: true)

Image

RequestResponse

<img *scImage="field; editable: true" />

This structural directive supports the following input properties:

Name	Description
default / `scImage`	The component or route field you wish to render. Should be of the Sitecore type Image.
`editable`	Indicates whether the experience editor / Sitecore-formatted HTML output should be used. (Default: true)
`urlParams`	The query string parameters added to the image URL. Note that because JSS does not support security hashing of media URLs, these parameter sets will need to be white-listed on the server.
`attrs`	Key/value attribute values for the resulting image tag. Note that attributes added to the host element will also be passed through, but will not support data binding.

The *scImage directive gives special treatment to the srcSet attribute if provided via the attrs input property. You can provide an array of objects which represent query string parameters for each element of a srcSet. This enables responsive images with server-side rendering when combined with a sizes attribute.

Link

RequestResponse

<a *scLink="field; editable: true"></a>

This structural directive supports the following input properties:

Name	Description
default / `scLink`	The component or route field you wish to render. Should be of the Sitecore type General Link.
`editable`	Indicates whether the experience editor / Sitecore-formatted HTML output should be used. (Default: true)
`attrs`	Key/value attribute values for the resulting output tag. Note that attributes added to the host element will also be passed through, but will not support data binding.

If using editable output from Sitecore, scLink will create a wrapper span around the Sitecore-provided markup, and apply host element attributes and attrs to this span.

Note

In the Experience Editor, in editor mode, a link description is always rendered. If the link has any children, they are rendered as siblings to the link description.

File

RequestResponse

<a *scFile="field"></a>

This structural directive supports the following input properties:

Name	Description
default / `scFile`	The component or route field you wish to render. Should be of the Sitecore type File.

The File field does not support inline editing via the Experience Editor in Sitecore, but can be edited via the default field editor on components.

Do you have some feedback for us?

If you have suggestions for improving this article,