Merge pull request #223 from Essent/lazy-loading

[Angular] Allow lazy loaded components to show a loading state

Author: sc-dawidrutkowski

docs/data/routes/docs/client-frameworks/angular/angular-placeholders/en.md

@@ -271,4 +271,14 @@ class MyRendering {
   @Input() something: Function;
   @Output() onSomething = new EventEmitter<string>();
 }
-```
+```
+
+## Lazy loading placeholder
+
+When lazy-loading a sitecore component, the placeholder will appear empty by default. A temporary body during loading of the component can be added to the placeholder by adding a body. When the component finished loading, the temporary body is replaced with the actual content. A simplified example is:
+
+``` html
+  <sc-placeholder [rendering]="rendering">
+    <img *scPlaceholderLoading src="loading.gif">
+  </sc-placeholder>
+```

docs/data/routes/docs/client-frameworks/angular/reference/en.md

@@ -76,6 +76,9 @@ Advanced usage is also possible, using templates to customize the markup emitted
       <sc-placeholder [renderings]="renderings"></sc-placeholder>
     </div>
   </ng-template>
+  <ng-template scPlaceholderLoading>
+    <img src="loading.gif">
+  </ng-template>
 </div>
 ```
 
@@ -175,4 +178,4 @@ Here is a list of all supported structural directives, and how they are used (wh
 |------|-------------|
 | 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.
+> 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.

packages/sitecore-jss-angular/src/components/placeholder-loading.directive.ts

@@ -0,0 +1,8 @@
+import { Directive, TemplateRef } from '@angular/core';
+
+@Directive({
+  selector: '[scPlaceholderLoading]',
+})
+export class PlaceholderLoadingDirective {
+  constructor(public templateRef: TemplateRef<any>) {}
+}

packages/sitecore-jss-angular/src/components/placeholder.component.spec.ts

@@ -1,6 +1,6 @@
 // tslint:disable:max-classes-per-file
 import { Component, DebugElement, EventEmitter, Input, NgModuleFactoryLoader, Output } from '@angular/core';
-import { ComponentFixture, TestBed, async } from '@angular/core/testing';
+import { async, ComponentFixture, TestBed } from '@angular/core/testing';
 import { By } from '@angular/platform-browser';
 import { SpyNgModuleFactoryLoader } from '@angular/router/testing';
 
@@ -12,7 +12,9 @@ import { convertedDevData as nonEeDevData, convertedLayoutServiceData as nonEeLs
 @Component({
   selector: 'test-placeholder',
   template: `
-    <sc-placeholder [name]="name" [rendering]="rendering"></sc-placeholder>
+    <sc-placeholder [name]="name" [rendering]="rendering">
+      <img *scPlaceholderLoading src="loading.gif">
+    </sc-placeholder>
   `,
 })
 class TestPlaceholderComponent {
@@ -52,7 +54,7 @@ describe('<sc-placeholder />', () => {
   let de: DebugElement;
   let comp: TestPlaceholderComponent;
 
-  beforeEach(() => {
+  beforeEach(async(() => {
     TestBed.configureTestingModule({
       declarations: [
         TestPlaceholderComponent,
@@ -70,8 +72,10 @@ describe('<sc-placeholder />', () => {
       providers: [
         { provide: NgModuleFactoryLoader, value: SpyNgModuleFactoryLoader },
       ],
-    });
+    }).compileComponents();
+  }));
 
+  beforeEach(() => {
     fixture = TestBed.createComponent(TestPlaceholderComponent);
     de = fixture.debugElement;
 
@@ -83,6 +87,12 @@ describe('<sc-placeholder />', () => {
     expect(comp).toBeDefined();
   });
 
+  it('should show a loader while no rendering is defined yet', () => {
+    const img = de.nativeElement.getElementsByTagName('img')[0];
+    expect(img).toBeDefined();
+    expect(img.getAttribute('src')).toBe('loading.gif');
+  });
+
   const testData = [
     { label: 'Dev data', data: nonEeDevData },
     { label: 'LayoutService data - EE off', data: nonEeLsData },
@@ -105,6 +115,9 @@ describe('<sc-placeholder />', () => {
           const downloadCallout = de.query(By.directive(TestDownloadCalloutComponent));
           expect(downloadCallout).not.toBeNull();
           expect(downloadCallout.nativeElement.innerHTML).toContain('Download');
+
+          const img = de.nativeElement.getElementsByTagName('img')[0];
+          expect(img).not.toBeDefined();
         });
       }));
 

packages/sitecore-jss-angular/src/components/placeholder.component.ts

@@ -21,6 +21,7 @@ import { ComponentRendering, HtmlElementRendering } from '@sitecore-jss/sitecore
 import { Observable } from 'rxjs';
 import { takeWhile } from 'rxjs/operators';
 import { ComponentFactoryResult, JssComponentFactoryService } from '../jss-component-factory.service';
+import { PlaceholderLoadingDirective } from './placeholder-loading.directive';
 import {
   PLACEHOLDER_MISSING_COMPONENT_COMPONENT
 } from './placeholder.token';
@@ -38,6 +39,7 @@ function getPlaceholder(rendering: ComponentRendering, name: string) {
 @Component({
   selector: 'sc-placeholder,[sc-placeholder]',
   template: `
+    <ng-template *ngIf="isLoading" [ngTemplateOutlet]="placeholderLoading?.templateRef"></ng-template>
     <ng-template #view></ng-template>
   `,
 })
@@ -46,6 +48,7 @@ export class PlaceholderComponent implements OnChanges, DoCheck, OnDestroy {
   private _differ: KeyValueDiffer<string, any>;
   private _componentInstances: any[] = [];
   private destroyed = false;
+  public isLoading = true;
 
   @Input() name?: string;
   @Input() rendering: ComponentRendering;
@@ -58,6 +61,7 @@ export class PlaceholderComponent implements OnChanges, DoCheck, OnDestroy {
   @ViewChild('view', { read: ViewContainerRef }) private view: ViewContainerRef;
   @ContentChild(RenderEachDirective) renderEachTemplate: RenderEachDirective;
   @ContentChild(RenderEmptyDirective) renderEmptyTemplate: RenderEmptyDirective;
+  @ContentChild(PlaceholderLoadingDirective) placeholderLoading?: PlaceholderLoadingDirective;
 
   @Input()
   set inputs(value: { [key: string]: any }) {
@@ -127,13 +131,15 @@ export class PlaceholderComponent implements OnChanges, DoCheck, OnDestroy {
     if (!this.name && !this.renderings) {
       // tslint:disable-next-line:max-line-length
       console.warn(`Placeholder name was not specified, and explicit renderings array was not passed. Placeholder requires either name and rendering, or renderings.`);
+      this.isLoading = false;
       return;
     }
 
     const placeholder = this.renderings || getPlaceholder(this.rendering, this.name || '');
 
     if (!placeholder) {
       console.warn(`Placeholder '${this.name}' was not found in the current rendering data`, JSON.stringify(this.rendering, null, 2));
+      this.isLoading = false;
       return;
     }
 
@@ -145,6 +151,7 @@ export class PlaceholderComponent implements OnChanges, DoCheck, OnDestroy {
         {
           renderings: placeholder,
         });
+      this.isLoading = false;
     } else {
       this.componentFactory.getComponents(placeholder)
         .then((components) => components.forEach((rendering, index) => {
@@ -153,6 +160,7 @@ export class PlaceholderComponent implements OnChanges, DoCheck, OnDestroy {
           } else {
             this._renderEmbeddedComponent(rendering, index);
           }
+          this.isLoading = false;
         })).then(() => {
           this.changeDetectorRef.markForCheck();
           this.loaded.emit(this.name);

packages/sitecore-jss-angular/src/lib.module.ts

@@ -8,9 +8,11 @@ import {
 import { ROUTES } from '@angular/router';
 import { DateDirective } from './components/date.directive';
 import { FileDirective } from './components/file.directive';
+import { GenericLinkDirective } from './components/generic-link.directive';
 import { ImageDirective } from './components/image.directive';
 import { LinkDirective } from './components/link.directive';
 import { MissingComponentComponent } from './components/missing-component.component';
+import { PlaceholderLoadingDirective } from './components/placeholder-loading.directive';
 import { PlaceholderComponent } from './components/placeholder.component';
 import {
   ComponentNameAndModule,
@@ -29,7 +31,6 @@ import { RouterLinkDirective } from './components/router-link.directive';
 import { TextDirective } from './components/text.directive';
 import { JssComponentFactoryService } from './jss-component-factory.service';
 import { LayoutService } from './layout.service';
-import { GenericLinkDirective } from './components/generic-link.directive';
 
 @NgModule({
   imports: [
@@ -44,6 +45,7 @@ import { GenericLinkDirective } from './components/generic-link.directive';
     DateDirective,
     RenderEachDirective,
     RenderEmptyDirective,
+    PlaceholderLoadingDirective,
     RenderComponentComponent,
     PlaceholderComponent,
     RawComponent,
@@ -62,6 +64,7 @@ import { GenericLinkDirective } from './components/generic-link.directive';
     RenderEmptyDirective,
     RenderComponentComponent,
     PlaceholderComponent,
+    PlaceholderLoadingDirective,
     RichTextDirective,
     TextDirective,
   ],

packages/sitecore-jss-angular/src/public_api.ts

@@ -4,6 +4,7 @@ export { LinkDirective } from './components/link.directive';
 export { RouterLinkDirective } from './components/router-link.directive';
 export { GenericLinkDirective } from './components/generic-link.directive';
 export { PlaceholderComponent } from './components/placeholder.component';
+export { PlaceholderLoadingDirective } from './components/placeholder-loading.directive';
 export { ComponentNameAndType, DYNAMIC_COMPONENT } from './components/placeholder.token';
 export { isRawRendering } from './components/rendering';
 export { FileField, ImageField, LinkField, RenderingField, RichTextField, TextField } from './components/rendering-field';