Mengimplementasikan widget di portal pengembang

Artikel
04/27/2022
6 menit untuk membaca

Dalam tutorial ini, Anda menerapkan widget yang menggunakan data dari API eksternal dan menampilkannya di portal pengembang API Management.

Widget akan mengambil deskripsi sesi dari sampel API Konferensi. Pengidentifikasi sesi akan diatur melalui editor widget yang ditunjuk.

Untuk membantu Anda dalam proses pengembangan, lihat widget lengkap yang terletak di folder examples dari portal pengembang API Management Repositori GitHub: /examples/widgets/conference-session.

Prasyarat

Siapkan lingkungan lokal untuk rilis terbaru portal pengembang.
Anda harus memahami anatomi widget Paperbits.

Menyalin rangka

Gunakan sebuah rangka widget dari folder /scaffolds sebagai titik awal untuk membangun widget baru.

Menyalin folder /scaffolds/widget ke /community/widgets.
Ubah nama folder menjadi conference-session.

Mengubah nama kelas modul yang diekspor

Ganti nama kelas modul yang diekspor dengan mengganti Widget awalan dengan ConferenceSession dan ubah nama pengikatan data untuk menghindari tabrakan nama pada file-file berikut:

widget.design.module.ts
widget.publish.module.ts
widget.runtime.module.ts

Misalnya, di file widget.design.module.ts, ubah WidgetDesignModule menjadi ConferenceSessionDesignModule:

export class WidgetDesignModule implements IInjectorModule {
    public register(injector: IInjector): void {
        injector.bind("widget", WidgetViewModel);
        injector.bind("widgetEditor", WidgetEditorViewModel);

export class ConferenceSessionDesignModule implements IInjectorModule {
    public register(injector: IInjector): void {
        injector.bind("conferenceSession", WidgetViewModel);
        injector.bind("conferenceSessionEditor", WidgetEditorViewModel);

Daftarkan modul widget di modul akar portal dengan menambahkan baris berikut di masing-masing file:

src/apim.design.module.ts - sebuah modul yang mendaftarkan dependensi waktu desain.

import { ConferenceSessionDesignModule } from "../community/widgets/conference-session/widget.design.module";

...
injector.bindModule(new ConferenceSessionDesignModule());

src/apim.publish.module.ts - sebuah modul yang mendaftarkan dependensi waktu penerbitan.

import { ConferenceSessionPublishModule } from "../community/widgets/conference-session/widget.publish.module";

 ...

 injector.bindModule(new ConferenceSessionPublishModule());

src/apim.runtime.module.ts - dependensi runtime.

import { ConferenceSessionRuntimeModule } from "../community/widgets/conference-session/widget.runtime.module";

...

injector.bindModule(new ConferenceSessionRuntimeModule());

Sekarang Anda siap untuk mencolokkan rangka duplikat dan menggunakannya di portal pengembang.

Jalankan perintah npm start.
Saat aplikasi dimuat, letakkan widget baru di halaman. Anda dapat menemukannya di nama Your widget dalam kategori Community di bagian pemilih widget.
Simpan halaman dengan menekan Ctrl+S (atau ⌘+S di macOS).

Catatan

Dalam waktu desain, Anda masih dapat berinteraksi dengan situs web dengan menahan tombol Ctrl (atau ⌘).

Menambahkan properti kustom

Agar widget mengambil deskripsi sesi, widget perlu mengetahui pengidentifikasi sesi. Tambahkan properti Session ID ke masing-masing antarmuka dan kelas:

Supaya widget mengambil deskripsi sesi, widget perlu mengetahui pengidentifikasi sesi. Tambahkan properti ID sesi ke masing-masing antarmuka dan kelas:

widgetContract.ts - kontrak data (lapisan data) mendefinisikan bagaimana konfigurasi widget bertahan.
```
export interface WidgetContract extends Contract {
    sessionNumber: string;
}
```
widgetModel.ts - model (lapisan bisnis) - sebuah representasi utama widget di dalam sistem. Ini diperbarui oleh editor dan dirender oleh lapisan presentasi.
```
export class WidgetModel {
    public sessionNumber: string;
}
```
ko/widgetViewModel.ts - viewmodel (lapisan presentasi) - objek khusus kerangka kerja UI yang dirender portal pengembang dengan templat HTML.

Catatan

Anda tidak perlu mengubah apa pun dalam file ini.

Mengonfigurasi pengikat

Aktifkan alur sessionNumber dari sumber data ke presentasi widget. Edit ModelBinder dan entitas ViewModelBinder:

widgetModelBinder.ts membantu mempersiapkan model menggunakan data yang dijelaskan di dalam kontrak.

export class WidgetModelBinder implements IModelBinder<WidgetModel> {
    public async contractToModel(contract: WidgetContract): Promise<WidgetModel> {
        model.sessionNumber = contract.sessionNumber || "107"; // 107 is the default session id
        ...
    }

    public modelToContract(model: WidgetModel): Contract {
        const contract: WidgetContract = {
            sessionNumber: model.sessionNumber
            ...
        };
        ...
    }
}

ko/widgetViewModelBinder.ts tahu bagaimana portal pengembang perlu menyajikan model (sebagai sebuah viewmodel) dalam kerangka kerja UI tertentu.

...
public async updateViewModel(model: WidgetModel, viewModel: WidgetViewModel): Promise<void> {
        viewModel.runtimeConfig(JSON.stringify({
            sessionNumber: model.sessionNumber
        }));
    }
}
...

Komponen dari setiap ruang lingkup berjalan secara independen. Komponen memiliki kontainer injeksi dependensi terpisah, konfigurasinya sendiri, siklus hidup, dll. Komponen bahkan dapat didukung oleh kerangka kerja UI yang berbeda (dalam contoh ini adalah Knockout JS).

Dari perspektif waktu desain, komponen runtime mana pun hanyalah tag HTML dengan atribut dan/atau konten tertentu. Konfigurasi jika perlu dilewatkan dengan markup biasa. Dalam kasus sederhana, seperti dalam contoh ini, parameter diteruskan di dalam atribut. Jika konfigurasi lebih kompleks, Anda dapat menggunakan pengidentifikasi dari pengaturan yang diperlukan yang diambil oleh penyedia konfigurasi yang ditunjuk (misalnya, ISettingsProvider).

Memperbarui file ko/widgetView.html:
```
<widget-runtime data-bind="attr: { params: runtimeConfig }"></widget-runtime>
```
Saat portal pengembang menjalankan pengikatan attr di dalam waktu desain atau waktu penerbitan, HTML yang dihasilkan adalah:
```
<widget-runtime params="{ sessionNumber: 107 }"></widget-runtime>
```
Kemudian, di runtime, komponen widget-runtime akan membaca sessionNumber dan menggunakannya dalam kode inisialisasi (lihat di bawah).

Perbarui file widgetHandlers.ts untuk menetapkan ID sesi pada pembuatan:

...
createModel: async () => {
    var model = new WidgetModel();
    model.sessionNumber = "107";
        return model;
    }
...

Merevisi model tampilan runtime

Komponen runtime adalah kode yang berjalan di situs web itu sendiri. Misalnya, di portal pengembang API Management, semuanya adalah skrip di belakang komponen dinamis (misalnya, detail API, konsol API), menangani operasi seperti pembuatan sampel kode, mengirim permintaan, dll.

Model tampilan komponen runtime Anda harus memiliki metode dan properti berikut:

Properti sessionNumber (ditandai dengan dekorator Param) yang digunakan sebagai parameter input komponen yang diteruskan dari luar (markup yang dihasilkan dalam waktu desain; lihat langkah sebelumnya).
Properti sessionDescription terikat ke templat widget (lihat widget-runtime.htmlnanti di artikel ini).
Metode initialize (dengan dekorator OnMounted) dipanggil setelah widget dibuat dan semua parameternya telah ditetapkan. Ini adalah tempat yang baik untuk membaca sessionNumber dan memanggil API menggunakan HttpClient. HttpClient adalah dependensi yang disuntikkan oleh kontainer IoC (Inversion of Control).

Pertama, portal pengembang membuat widget dan menetapkan semua parameternya. Kemudian memanggil metode initialize.

...
import * as ko from "knockout";
import { Component, RuntimeComponent, OnMounted, OnDestroyed, Param } from "@paperbits/common/ko/decorators";
import { HttpClient, HttpRequest } from "@paperbits/common/http";
...

export class WidgetRuntime {
    public readonly sessionDescription: ko.Observable<string>;

    constructor(private readonly httpClient: HttpClient) {
        ...
        this.sessionNumber = ko.observable();
        this.sessionDescription = ko.observable();
        ...
    }

    @Param()
    public readonly sessionNumber: ko.Observable<string>;

    @OnMounted()
    public async initialize(): Promise<void> {
        ...
        const sessionNumber = this.sessionNumber();

        const request: HttpRequest = {
            url: `https://conferenceapi.azurewebsites.net/session/${sessionNumber}`,
            method: "GET"
        };

        const response = await this.httpClient.send<string>(request);
        const sessionDescription = response.toText();

        this.sessionDescription(sessionDescription);
        ...
    }
    ...
}

Perbarui widget Anda untuk menampilkan deskripsi sesi.

Gunakan tag paragraf dan sebuah markdown (atau text) pengikatan di file ko/runtime/widget-runtime.html untuk merender deskripsi:

<p data-bind="markdown: sessionDescription"></p>

Widget sekarang dikonfigurasi untuk mengambil deskripsi dari sesi 107. Anda menentukan 107 di dalam kode sebagai sesi default. Untuk memeriksa apakah Anda melakukan segalanya dengan benar, jalankan npm start dan konfirmasi bahwa portal pengembang menampilkan deskripsinya di halaman.

Sekarang, lakukan langkah-langkah ini untuk memungkinkan pengguna mengatur ID sesi melalui editor widget:

Memperbarui file ko/widgetEditorViewModel.ts:

export class WidgetEditor implements WidgetEditor<WidgetModel> {
    public readonly sessionNumber: ko.Observable<string>;

    constructor() {
        this.sessionNumber = ko.observable();
    }

    @Param()
    public model: WidgetModel;

    @Event()
    public onChange: (model: WidgetModel) => void;

    @OnMounted()
    public async initialize(): Promise<void> {
        this.sessionNumber(this.model.sessionNumber);
        this.sessionNumber.subscribe(this.applyChanges);
    }

    private applyChanges(): void {
        this.model.sessionNumber = this.sessionNumber();
        this.onChange(this.model);
    }
}

Model tampilan editor menggunakan pendekatan yang sama yang pernah Anda lihat sebelumnya, namun terdapat properti onChange baru, dihiasi dengan @Event(). Ini mengirimkan panggilan balik untuk memberi tahu pendengar (dalam hal ini - editor konten) perubahan pada model.

Memperbarui file ko/widgetEditorView.html:

<input type="text" class="form-control" data-bind="textInput: sessionNumber" />

Jalankan npm start lagi. Anda harus dapat mengubah sessionNumber di editor widget. Ubah ID ke 108, simpan perubahan, dan refresh tab browser. Jika Anda mengalami masalah, Anda mungkin perlu menambahkan widget ke dalam halaman lagi.

Ubah nama widget di dalam file constants.ts:

...
export const widgetName = "conference-session";
export const widgetDisplayName = "Conference session";
...

Catatan

Jika Anda berkontribusi widget ke repositori, maka widgetName harus sama dengan nama foldernya dan perlu berasal dari nama tampilan (huruf kecil dan spasi diganti dengan tanda hubung). Kategori harus tetap Community.

Langkah berikutnya

Pelajari selengkapnya tentang portal pengembang:

Gambaran Umum portal pengembang Manajemen Azure API
Berkontribusi widget - kami menyambut dan mendorong kontribusi dari komunitas.
Lihat Menggunakan widget komunitas untuk mempelajari cara menggunakan widget yang dikontribusikan oleh komunitas.

Mengimplementasikan widget di portal pengembang

Prasyarat

Menyalin rangka

Mengubah nama kelas modul yang diekspor

Daftarkan widget

Tempatkan widget di portal

Menambahkan properti kustom

Mengonfigurasi pengikat

Sesuaikan templat widget waktu desain

Merevisi model tampilan runtime

Sesuaikan templat widget

Tambah editor widget

Mengubah nama widget

Langkah berikutnya

Mengimplementasikan widget di portal pengembang

Apakah halaman ini membantu?

Prasyarat

Menyalin rangka

Mengubah nama kelas modul yang diekspor

Daftarkan widget

Tempatkan widget di portal

Menambahkan properti kustom

Mengonfigurasi pengikat

Sesuaikan templat widget waktu desain

Merevisi model tampilan runtime

Sesuaikan templat widget

Tambah editor widget

Mengubah nama widget

Langkah berikutnya