SharePoint Framework Extensions (preview) – ApplicationCustomizers

Kot sem pisal v enem izmed predhodnjih blog postov, je Microsoft na konferenci Build 2017 napovedal nadaljevanje SharePoint Framework zgodbe na t.i. dodatke oz. Extensions.

SharePoint Framework Extensions omogoča razširitev in prilagoditev uporabniške izkušnje na SharePointu v nove dimenzije s pomočjo notification areas, toolbars ter views oz. pogledi seznamov.
Trenutno je še v Preview verziji in je na voljo za testiranje zgolj preko Office 365 Developer Tenants.

SharePoint Framework Extensions so client-side komponente, ki tečejo znotraj konteksta SharePointove strani. SharePoint Framework Extensions vsebujejo tri nove tipe:

  • ApplicationCustomizers omogoča programerju vstaviti skripto kjerkoli na stran, dostop do HTML placeholderjev ter njihova razširitev s custom renderingom.
  • FieldCustomizers omogoča modificiranje pogledov seznamov na nivoju fieldov
  • CommandSets omogoča razširitev menijev z dodatnimi actionsi, na katere je pripeta client-side koda

Da pa ne bomo samo govorili, pojdimo na prvi SharePoint Framework Extensions primer, kjer bom tokrat vzel ApplicationCustomizers tip razširitve in jo poimenoval Xnet Hello World Extension.

Če še nimate pripravljenega svojega SharePoint Framework razvojnega okolja kot sem opisal v enem izmed prejšnjih blog postov, si lahko postopek priprave ogledate na naslednji povezavi: https://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment
Če pa imate razvojno orodje že pri sebi, poženite spodnji ukaz, s katerim posodobite Yeoman template za SPFx:

npm install -g @microsoft/generator-sharepoint

Nato na poljubni lokaciji na disku ustvarimo prazno mapo za naš projekt:

mkdir xnet-helloworld-extension 

ter se premaknemo vanj:

cd xnet-helloworld-extension

Kreiramo nov Xnet HelloWorld extension project template s naslednjim ukazom:

yo @microsoft/sharepoint

Pri izbiri tipa client-side componente izberite opcijo Extension (Preview) (če nimate na voljo te opcije, potem niste posodobili Yeoman template za SPFx, kot sem opisal zgoraj).
Pri izbiri tipa client-side exntension izberite opcijo Application Customizer (Preview).

Projekt odprite v Visual Studio Code editorju s ukazom:

code .

Odprite datoteko HelloWorldApplicationCustomizer.manifest.json v mapi src\extensions\helloWorld.
V njej je definiran extension type in unikaten identifikator »id« vašega extension-a. Ta ID se uporablja kot identifikator pri debugging-u in deploy-u.

Odprite datoteko HelloWorldApplicationCustomizer.ts v isti mapi. Opazite lahko, da je bazni razred importiran iz sp-application-base paketa in vsebuje dve metodi:

  • onInit() je metoda, kjer lahko izvedeš kakršnokoli nastavitev, ki je potrebna za tvoj extension. Ta event se izvede po temu, ko sta context in this.properties nastavljena in hkrati pred tem, ko je page DOM pripravljen. onInit() vrne promise, torej lahko tu izvajaš async operacije. onRender() se ne izvede, dokler se promise ne izvede. Če tega ne potrebuješ, enostavno vrneš super.onInit()
  • onRender() je metoda, kjer lahko tvoj extension komunicira z UI. Event se izvede po temu, ko se DOM struktura že kreira.

SharePoint Framework Extensions trenutno ni mogoče testirati z uporabo lokalnega workbench-a, zato je potrebno testirati in razvijati direktno na SharePoint Online.

Najprej je potrebno compajlat kodo in jo hostat preko lokalne mašine z uporabno naslednjega ukaza:

gulp serve –nobrowser

Če nimate nameščenega SPFx developer cerifikata to predhodno storite z ukazom

gulp trust-dev-cert

Za testiranje vašega extensiona pojdite na svoj Office 365 developer tenants site, kjer izberete eno izmed obstoječih knjižnic ali seznamov, ker le te že uporabljajo modern design in na konec url-ja dodate naslednje querystring parametre:

  • loadSPFX=true: zagotovimo, da se SharePoint Framework naloži na stran. Zaradi performanc je normalno, da se SPFx ne naloži dokler ni na strani registriran vsaj en extension.
  • debugManifestsFile: specificiramo, da želimo naložiti SPFx komponento, ki je servirana lokalno. Normalno loader gleda samo za komponentami, ki so nameščene v App Catalog-u.
  • customActions: simuliramo custom action tako, da povemo:
    • Key: Guid našega extensiona (v manifest.json fajlu)
    • Location: tip custom action (v našem primeru bomo uporabili “ClientSideExtension.ApplicationCustomizer”)
    • Properties: opcijski JSON object, ki bvsebuje dodatne nastavitve za naš extension, ki so dosegljivi preko properties nastavitve (v našem primeru bomo uporabili nastavitev “testMessage”)

Končni link za testiranje našega SPFx extension-a bo izgledal takole (odebeljene stvari spodaj se za vaš primer razlikujejo): https://{PotDoO365DevSite}/Shared%20Documents/Forms/AllItems.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={“d41adcdb-56ca-41c6-832f-6ac233a8ddfe“:{“location”:”ClientSideExtension.ApplicationCustomizer”,”properties”:{“testMessage”:”Pozdravljen iz Xnet sveta!“}}}

Ob odpiranju linka se vam v alert oknu izpiše besedilo, ki je v zgornji povezavi podčrtano. Ta tekst smo podali v našem primeru kot debug query parameter. Seveda bi lahko v onInit() metodi brali tekst iz nekega SharePointovega seznama ali vzeli neko drugo client component nastavitev.

sl1

Application Customizers omogočajo tudi dostop do delov strani, ki jih lahko prilagodiš glede na poslovne in funkcionalne potrebe. Tipični primer je npr. glava in noga po meri.

Scope dostopa je lahko Site, Web in List. Dostopaš pa lahko do nekega obstoječega placeholder-ja na strani.

Posodobimo našo kodo primera tako, da iz @microsoft/sp-application-base importiramo še Placeholder class.

import {
  BaseApplicationCustomizer,
  Placeholder
} from '@microsoft/sp-application-base';

Ustvarimo nov AppCustomizer.module.scss fajl znotraj mape src\extensions\helloWorld, v katerem bomo definirali naslednje oblikovanje:

.app {
  .header {
    height:60px;
    text-align:center;
    line-height:2.5;
    font-weight:bold;
    display: flex;
    align-items: center;
    justify-content: center;
  }

  .footer {
    height:40px;
    text-align:center;
    line-height:2.5;
    font-weight:bold;
    display: flex;
    align-items: center;
    justify-content: center;
  }
}

HelloWorldApplicationCustomizer.ts fajlu importiramo še novo-ustvarjeni scss fajl ter escape oblikovanje Application Customizer property-ev:

import styles from './AppCustomizer.module.scss';
import { escape } from '@microsoft/sp-lodash-subset';

Poupdatamo interface IHelloWorldApplicationCustomizerProperties tako, da imamo v njemu definirano polje za tekst v glavi in v nogi:

export interface IHelloWorldApplicationCustomizerProperties {
  Header: string;
  Footer: string;
}

Znotraj HelloWorldApplicationCustomizer razreda dodamo lokalni spremenljivki, ki bosta povezani na naša placeholder-ja v glavi in nogi:

private _headerPlaceholder: Placeholder;
private _footerPlaceholder: Placeholder;

Zadnja stvar in hkrati tudi najpomembnejša, pa je posodobitev onRender() metode, v kateri bomo poiskali oba placeholderja in v njiju izpisali Header in Footer tekst:

@override
public onRender(): void {
    // poiščemo header placeholder
    if (!this._headerPlaceholder) {
      this._headerPlaceholder = this.context.placeholders.tryAttach(
        'PageHeader',
        {
          onDispose: () => {}
        });

      // če header placeholderja ne najdemo
      if (!this._headerPlaceholder) {
        console.error('Ni mogoče najti PageHeader.');
        return;
      }

      if (this.properties) {
        let headerString: string = this.properties.Header;
        if (!headerString) {
          headerString = 'Header tekst ni definiran.';
        }

        if (this._headerPlaceholder.domElement) {
          this._headerPlaceholder.domElement.innerHTML = `
                
                 
                    ${escape(headerString)}                  
                </div>`;         }       }     }     // poiščemo footer placeholder     if (!this._footerPlaceholder) {       this._footerPlaceholder = this.context.placeholders.tryAttach(         'PageFooter',         {           onDispose: () => {}         });       // če footer placeholderja ne najdemo       if (!this._footerPlaceholder) {         console.error('Ni mogoče najti PageFooter.');         return;       }       if (this.properties) {         let footerString: string = this.properties.Footer;         if (!footerString) {           footerString = 'Footer tekst ni definiran.';         }         if (this._footerPlaceholder.domElement) {           this._footerPlaceholder.domElement.innerHTML = `                
                 
                    ${escape(footerString)}                  
                </div>`;         }       }     }   }

Zadevo potestiramo na enak način kot smo to storili prej.

sl2

Izpis vseh možnih placeholder-jev, ki jih lahko uporabite, dobite z naslednjo kodo:

console.log(this.context.placeholders.placeholderNames.join(', '));

 

Lep pozdrav!
Gašper Rupnik

{End.}

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Powered by WordPress.com.

Up ↑

%d bloggers like this: