Documentation

Read and search through all the Sitecore JSS documentation

JSS Angular API

The sitecore-jss-angular package is a UI library that delivers components for rendering data from the Sitecore Layout Service.

Getting started

Note: Most users should use this library as part of the Angular sample app; these instructions are general and do not cover many aspects of configuration.

Step 1: Install sitecore-jss-angular

You can use the npm command-line tool to install packages. Use whichever is appropriate for your project in the examples below.

npm install @sitecorelabs/sitecore-jss-angular

Step 2: Import the JssModule

For this example we show how a WelcomeComponent is added to the list of components that can be rendered by a placeholder, by registering them with the JssModule.withComponents() method.

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, the JssModule is imported and dynamically generated by convention, with the components being registered based on their presence on disk at build time. This reduces maintenance of the component registrations, however it is also optional.

Step 3: All setup and ready

The sitecore-jss-angular library is all setup and all the structural directives for field types as well as the placeholder component can now be used.

Check out the sample app walkthrough to see usage of the library.

Placeholder Directives

A component is provided by the library to help render placeholders returned by Layout Service. The placeholder component dynamically instantiates additional Angular components within it based on the components defined in the Layout Service data.

Basic placeholder technique consists of passing it the rendering data injected into the component:

<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:

<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>
</div>

See the layout reuse example in the sample app's styleguide for more details about advanced placeholder technique.

Field Helper Directives

The library provides structural directives to help output Sitecore field values. The benefit of using structural directives are, as a developer, all features of a tag is 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, do:

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

Here is a list of all supported structural directives, and how they are used (where field is data coming from a placeholder component):

Text

Example

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

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

Example

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

Input Properties

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

Image

Example

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

Input Properties

name description
default / scImage The component or route field you wish to render. Should be Sitecore type Image.
editable Indicates whether the experience editor / Sitecore-formatted HTML output should be used. (Default: true)
urlParams The query string parameters that should be 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.

Example

<a *scLink="field; editable: true"></a>
name description
default / scLink The component or route field you wish to render. Should be 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.

File

Example

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

Input Properties

name description
default / scFile The component or route field you wish to render. Should be 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.


Found a problem? Have something to add? Edit this on GitHub