Tutorial: Erstellen Sie ein benutzerdefiniertes Widget

  • Freigeben Version: Xanadu
  • Aktualisiert 1. August 2024
  • 9 Minuten Lesedauer

    • Folgen Sie diesem Tutorial, um ein benutzerdefiniertes Widget zu erstellen, das Servicekatalog-Elemente anzeigt. Verwenden Sie dieses Tutorial als Modell, um die fortgeschrittenen Skriptfunktionen von Serviceportal zu verstehen.

    In diesem Lernprogramm erstellen Sie das Schnellbestellungs-Widget. Dieses Widget:
    • zeigt dem Benutzer beliebte Elemente vor einer Suche an.
    • Fragt Servicekatalog ab, und zeigt dem Benutzer die verfügbaren Optionen an.
    • Enthält ein Widget für eingebettetes SC-Katalogelement, mit dem der Benutzer Elemente im Schnellbestellungs-Widget anzeigen und bestellen kann.
    • Verwendet einen Angular Provider, um ein Kategoriesymbol neben jedem abgefragten Element anzuzeigen.

    Erstellen Sie ein Widget, und richten Sie eine Vorlage ein

    Erstellen Sie das Schnellbestellungs-Widget zum Abfragen von Elementen in Servicekatalog.

    Vorbereitungen

    Erforderliche Rolle: admin oder sp_admin

    Prozedur

    1. Navigieren zu Alle > Service Portal > Serviceportal-Konfiguration und klicken Sie auf Widget-Editor.
    2. Klicken Sie auf Erstellen eines neuen Widgets.
    3. Definieren Sie die folgenden Werte.
      • Widget-Name: Schnelle Bestellung
      • Widget-ID: quick_order
      • Erstellen Sie eine Testseite: Aktiv
      • Seiten-ID: quick_order

      Durch das Hinzufügen eines Widget zu einer Testseite wird in jeder der folgenden Tabellen ein Datensatz erstellt:

      • sp_page
      • sp_container
      • sp_row
      • sp_column
      • sp_instance
      • sp_widget
      Hinweis:
      Sie können den Seiteneditor in Service Portal Configuration verwenden, um die Hierarchie der Elemente auf Ihrer Testseite anzuzeigen.
    4. Klicken Sie auf Senden.
    5. Im Widget-Editor öffnen Sie das Schnellbestellungs-Widget.
    6. Fügen Sie dem HTML-Feld die folgende einfache Vorlage hinzu. 
      <div class="panel panel-primary">
 <div class="panel-heading">Request an item from the catalog</div>
 <div class="panel-body">
   My catalog results
 </div>
</div>
    7. Klicken Sie auf Speichern.
    8. Zeigen Sie Ihre Testseite in einer neuen Registerkarte mit der folgenden URL an: <yourInstanceUrl>/sp?id=quick_order.

      Ihre Widget-Vorlage wird auf der Testseite angezeigt.

      Widget-Rendering auf einer Seite

    Hinzufügen eines Serverskripts zu zum Abfragen einer Instanztabelle

    Nachdem Sie Ihr Widget hinzugefügt und eine Basisvorlage erstellt haben, können Sie erweiterte Client- und Serverskripts definieren, mit denen Benutzer Daten aus einer Instanztabelle abfragen können. Sie können das Datenmodell zwischen Client und Server übergeben, indem Sie Daten aus der Datenbank abfragen, dem Benutzer anzeigen und etwaige Aktualisierungen an den Server zurücksenden.

    Vorbereitungen

    Erforderliche Rolle: admin oder sp_admin

    Prozedur

    1. Im Widget-Editor öffnen Sie das Schnellbestellungs-Widget.
    2. Wählen Sie Serverskript um das Serverskriptfeld zu öffnen.
    3. Ersetzen Sie das Standard-Serverskript durch das folgende benutzerdefinierte Skript. 
      (function() {
	if (input.keywords != null && input.keywords != '')
		data.items = getCatalogItems(input.keywords);
	
	function getCatalogItems(keywords) {
		var sc = new GlideRecord('sc_cat_item');
		sc.addActiveQuery();
		sc.addQuery('123TEXTQUERY321', keywords);
		sc.addQuery('sys_class_name', 'NOT IN', 'sc_cat_item_wizard,sc_cat_item_content');
		sc.addQuery('sc_catalogs', 'e0d08b13c3330100c8b837659bba8fb4');
		sc.setLimit(100);
		sc.orderByDesc("ir_query_score");
		sc.query();
		var results = [];
		while (sc.next()) {
			if (!$sp.canReadRecord(sc))
				continue;

			var item = {};
			$sp.getRecordDisplayValues(item, sc, 'name,price,sys_id');
			item.category = sc.getValue('category');
			results.push(item);
		}
		return results;
	}
})();

      Dieses Skript führt eine Schlüsselwortsuche für die Tabelle sc_cat_item mithilfe der Abfragemethode 123TEXTQUERY321 durch.

    4. Ersetzen Sie die HTML-Vorlage durch das folgende Skript: 
      <div class="panel panel-primary">
 <div class="panel-heading">Request an item from the catalog</div>
 <div class="panel-body">
   <input class="form-control" type="search" placeholder="Start typing here to search the list of catalog items" ng-model="c.data.keywords" ng-change="c.server.update()" ng-model-options="{debounce: 250}" />
   <ul class="list-group result-container">
     <li class="list-group-item" ng-repeat="item in c.data.items">
       <a href>{{item.name}}</a><span class="pull-right">{{item.price}}</span>
     </li>
   </ul>
 </div>
</div>

      Diese Vorlage fügt ein Suchfeld hinzu und zeigt die Ergebnisse der im Serverskript durchgeführten Abfrage mithilfe der folgenden Angular-Anweisungen an. Weitere Informationen zu diesen Richtlinien finden Sie in der Angular API-Referenz.

      Tabelle : 1. In der Vorlage verwendete Angular-Richtlinien
      Angular-Richtlinie Beschreibung
      ng-model Liest und schreibt Wertänderungen automatisch in die Modellvariable c.data.keywords.
      ng-model-Optionen Konfiguriert das Verhalten von ng-Modellen. In dieser Vorlage aktualisiert ng-model das Modell, nachdem ein Benutzer die Eingabe für 250 Millisekunden abgebrochen hat.
      ng-change Führt c.server.update() aus, nachdem sich der Modellwert ändert. Diese Funktion postet das Datenobjekt in das Serverskript. Nachdem das Skript ausgeführt wurde, wird das Datenobjekt automatisch mit den neuen Werten des vom Server generierten Datenobjekts aktualisiert.
      ng-repeat Erstellt eine Vorlage aus dem übergeordneten Element und den untergeordneten Elementen. Für jede Instanz von item in c.data.items wird eine Instanz der Vorlage erstellt und die Ausdrücke {{item.name}} und {{item.price}} werden durch die Werte jedes Elements ersetzt.
    5. Fügen Sie das folgende Skript dem Feld CSS - SCSS hinzu: 
      .result-container {
 margin-top: 10px;
}
    6. Aktualisieren Sie die Testseitenvorschau, um die Änderungen anzuzeigen.

      Wenn Sie im Suchfeld tippen, werden übereinstimmende Katalogelemente angezeigt. Suchen Sie nach ipad.

      Suche zeigt Ergebnisse für iPad an.

    Verwalten Sie den leeren Status eines Widgets

    Zeigen Sie dem Benutzer eine Liste der beliebtesten Elemente an, bevor Sie Suchbegriffe eingeben.

    Vorbereitungen

    Erforderliche Rolle: admin oder sp_admin

    Warum und wann dieser Vorgang ausgeführt wird

    Da bei der Initialisierung des Widgets keine Suche ausgeführt wurde, bleibt die Server-Eingabe-Variable undefiniert. Dieser leere Status kann zu Verwirrung führen, wenn ein Benutzer zum ersten Mal mit dem Widget interagiert. Um dieses Problem zu lösen, geben Sie Ihrem Widget etwas zum Anzeigen, wenn die Eingabe-Variable leer ist Diese Anfangsdaten können Ihre Benutzer bei der anfänglichen Interaktion mit Ihrem Widget führen.

    Prozedur

    1. Im Widget-Editor öffnen Sie das Schnellbestellungs-Widget.
    2. Ersetzen Sie das vorhandene Serverskript durch das folgende Skript: 
      (function() {
	if (input.keywords != null && input.keywords != '')
		data.items = getCatalogItems(input.keywords);
	else data.items = getPopularItems();

	function getCatalogItems(keywords) {
		var sc = new GlideRecord('sc_cat_item');
		sc.addActiveQuery();
		sc.addQuery('123TEXTQUERY321', keywords);
		sc.addQuery('sys_class_name', 'NOT IN', 'sc_cat_item_wizard,sc_cat_item_content');
		sc.addQuery('sc_catalogs', 'e0d08b13c3330100c8b837659bba8fb4');
		sc.setLimit(100);
		sc.orderByDesc("ir_query_score");
		sc.query();
		var results = [];
		while (sc.next()) {
			if (!$sp.canReadRecord(sc))
				continue;

			var item = {};
			$sp.getRecordDisplayValues(item, sc, 'name,price,sys_id');
			item.category = sc.getValue('category');
			results.push(item);
		}
		return results;
	}
	
	function getPopularItems() {
		var items = [];
		var count = new GlideAggregate('sc_req_item');
		count.addAggregate('COUNT','cat_item');
		count.groupBy('cat_item');
		count.addQuery('cat_item.sys_class_name', 'NOT IN', 'sc_cat_item_guide,sc_cat_item_wizard,sc_cat_item_content');
		count.addQuery('cat_item.sc_catalogs', 'e0d08b13c3330100c8b837659bba8fb4');
		count.orderByAggregate('COUNT', 'cat_item');
		count.query();
		while (count.next() && items.length < 9) {
			if (!$sp.canReadRecord("sc_cat_item", count.cat_item.sys_id.getDisplayValue()))
				continue; // user does not have permission to see this item

			var item = {};
			item.name = count.cat_item.name.getDisplayValue();
			item.category = count.cat_item.category.toString();
			item.price = count.cat_item.price.getDisplayValue();
			item.sys_id = count.cat_item.sys_id.getDisplayValue();
			items.push(item);
		}
		return items;
	}
})();

      Dieses Skript führt eine neue Funktion getPopularItems() ein, um die Datenbank abzufragen und beliebte Elemente auszugeben, wenn die Eingabe-Variable leer ist.

    3. Ersetzen Sie die HTML-Vorlage durch das folgende Skript: 
      <div class="panel panel-primary">
  <div class="panel-heading">Request an item from the catalog</div>
  <div class="panel-body">
    <input class="form-control" type="search" placeholder="Start typing here to search the list of catalog items" ng-model="c.data.keywords" ng-change="c.server.update()" ng-model-options="{debounce: 250}" />
    <h5 ng-if="!c.data.keywords">Showing the most popular items</h5>
    <ul class="list-group result-container">
      <li class="list-group-item" ng-repeat="item in c.data.items">
        <a href>{{item.name}}</a><span class="pull-right">{{item.price}}</span>
      </li>
    </ul>
  </div>
  <div class="panel-footer" ng-if="c.data.keywords">
    <ng-pluralize count="c.data.items.length"
                 when="{'0': 'No items found for ',
                     '1': 'One item matching ',
                     'other': 'Found {} items matching '}">
    </ng-pluralize>
    {{c.data.keywords}}
  </div>
</div>

      Dieses Skript enthält eine Vorlage zum Anzeigen der vom Serverskript ausgegebenen häufig verwendeten Elemente.

    4. Aktualisieren Sie die Testseitenvorschau, um die Änderungen anzuzeigen.

      Das Widget zeigt dem Benutzer vor jeder Sucheingabe beliebte Elemente an.

      Ein Suchfeld mit dem Text „Geben Sie hier Zeichen ein, um die Liste der Katalogelemente zu durchsuchen“.

    Ein bestehendes Widget einbetten

    Ermöglichen Sie dem Benutzer das Anzeigen und Kaufen von Servicekatalog-Elementen im Schnellbestellungs-Widget durch Einbetten des Widget „SC Catalog Item.“

    Vorbereitungen

    Erforderliche Rolle: admin oder sp_admin

    Warum und wann dieser Vorgang ausgeführt wird

    Anstatt Code zu duplizieren, können Sie Widgets einbetten, um vorhandene Funktionen zu nutzen. Das Widget „SC Catalog Item“ ist ein Basissystem-Widget, mit dem der Benutzer Servicekatalog-Elemente anzeigen und kaufen kann.

    Prozedur

    1. Überprüfen Sie das Widget „SC Catalog Item.“
      Überprüfen Sie vor dem Einbetten das SC Catalog Item-Widgets das Widget, um festzustellen, auf welche Daten es zugreifen muss. Möglicherweise müssen Sie Ihren Quick Order Widget-Client oder Ihr Serverskript aktualisieren, um sicherzustellen, dass die korrekten Daten an das eingebettete Widget übergeben werden.
      1. Navigieren Sie zu<yourInstanceURL> /sp_config?id=widget_editor
      2. Öffnen Sie das Widget „SC Catalog.“
      3. Beachten Sie, dass die Widget-ID widget-sc-cat-item lautet.
        Mit dieser ID können Sie das Widget-Modell in das Clientskript einbetten.
      4. Prüfen Sie das Serverskript.

        Beachten Sie, dass das Daten-Objekt eine sys_id-Eigenschaft enthält, die entweder mit den Eingabe- oder Optionen-Objekten ausgefüllt wird. Wenn weder die Eingabe noch die Optionen eine sys_id enthalten, ruft die Methode $sp.getParameter() die sys_id aus der Zeichenfolge der Anforderungsabfrage ab.

        Beispiel eines Serverskripts, das eine „If Else“-Anweisung verwendet, um die sys_id abzurufen.

        Zum Ausfüllen des Eingabe-Objekts können Sie eine Katalogelement-sys_id aus dem Quick Order Widget-Clientskript übergeben.

    2. Im Widget-Editor öffnen Sie das Schnellbestellungs-Widget.
    3. Ersetzen Sie das Quick Order Widget-Clientskript durch das folgende Skript. 
      function($location, spUtil) {
  var c = this;
	
	c.select = function(item_id) {
		if (c.openItem == item_id) {
			c.openItem = null;
			return;
		}
		
		renderCatalogItemWidget(item_id);
	}
	
	function renderCatalogItemWidget(item_id) {
		c.catalogItemWidget = null;
		spUtil.get("widget-sc-cat-item", {sys_id: item_id}).then(function(response){
			c.catalogItemWidget = response;
			c.openItem = item_id;
		});
	}
}

      Dieses Skript verwendet spUtil.get() zum Abrufen des Widget-Modells nach ID (widget-sc-cat-item) und definieren des {sys_id: item_id}-Objekts. Dieses Objekt wird in das Serverskript als Eingabe geschrieben.

    4. Ersetzen Sie die HTML-Vorlage durch das folgende Skript: 
      <div class="panel panel-primary">
  <div class="panel-heading">Request an item from the catalog</div>
  <div class="panel-body">
    <input class="form-control" type="search" placeholder="Start typing here to search the list of catalog items" ng-model="c.data.keywords" ng-change="c.server.update()" ng-model-options="{debounce: 250}" />
    <h5 ng-if="!c.data.keywords">Showing the most popular items</h5>
    <ul class="list-group result-container">
      <li class="list-group-item" ng-repeat="item in c.data.items">
        <a href ng-click="c.select(item.sys_id)">{{item.name}}</a><span class="pull-right">{{item.price}}</span>
        <div class="catalog-item" ng-if="item.sys_id == c.openItem">
            <sp-widget ng-if="c.catalogItemWidget" widget="c.catalogItemWidget" />
        </div>
      </li>
    </ul>
  </div>
  <div class="panel-footer" ng-if="c.data.keywords">
    <ng-pluralize count="c.data.items.length"
                 when="{'0': 'No items found for ',
                     '1': 'One item matching ',
                     'other': 'Found {} items matching '}">
    </ng-pluralize>
    {{c.data.keywords}}
  </div>
</div>

      Diese Vorlage:

      • fügt das On-Click-Verhalten mithilfe der Direktaufruf-Direktive hinzu.
      • zeigt das Widget für eingebettetes SC-Katalogelement mithilfe der Direktive sp-widget an.
    5. ersetzt das CSS durch das folgende Skript: 
      .result-container {
  margin-top: 10px;
}

.catalog-item {
  background-color: #f5f5f5;
  padding: 10px;
  @include border-top-radius($panel-border-radius);
  @include border-bottom-radius($panel-border-radius);
}
    6. Aktualisieren Sie die Testseitenvorschau, um die Änderungen anzuzeigen.

      Wenn Sie ein Suchergebnis auswählen, wird das Element im eingebetteten SC Catalog Item-Widget geöffnet.

      Testseite, auf der ein ausgewähltes Element in einem eingebetteten Widget angezeigt wird.

    Erstellen Sie eine wiederverwendbare Anweisung und fügen Sie sie einem Widget hinzu

    Angular Providers sind wiederverwendbare Komponenten, die mehreren Widgets hinzugefügt werden können. Erstellen Sie mithilfe der Tabelle Widget Angular Providers eine Anweisung, die neben jedem Ergebnis im Quick Order-Widget ein Kategoriesymbol anzeigt.

    Vorbereitungen

    Erforderliche Rolle: admin oder sp_admin

    Warum und wann dieser Vorgang ausgeführt wird

    Mit Angular Providers können Sie Angular-Anweisungen und -Dienste erstellen, die in Ihren Clientskript-Controller eingefügt werden können. Der Code in einem Provider unterscheidet sich von einer typischen Angular-Anweisung bzw. einem -Dienst, da er anonym sein muss, ohne an ein bestimmtes Modul angehängt zu werden.

    Prozedur

    1. Navigieren zu Alle > Service Portal > Service Portal-Konfiguration > Portal-Tabellen > Widget Angular Provideran.
      Die Tabelle Widget Angular Providers wird geöffnet.
    2. Wählen Sie Neu aus, um einen neuen Datensatz zu erstellen.
    3. Füllen Sie das Formular aus.
      1. Fügen Sie den Typ und den Namen hinzu.
        • Typ: Anweisung
        • Name: categoryIcon
      2. Fügen Sie das Clientskript hinzu. 
        function() {
  return {
    template: '<span class="fa fa-stack fa-lg"><i class="fa fa-circle fa-stack-2x"></i><i class="fa fa-{{::icon}} fa-stack-1x fa-inverse"></i></span>',
    restrict: 'E',
    replace: true,
    scope: {
      category: '='
    },
    link: function(scope, element) {
					
var _iconMap = {
		"b06546f23731300054b6a3549dbe5dd8": "tablet", /* Tablets */
		"15706fc0a0a0aa7007fc21e1ab70c2f": "question", /* Can we help you? */
		"d68eb4d637b1300054b6a3549dbe5db2": "mobile-phone", /* Mobiles */
		"109cdff8c6112276003b17991a09ad65": "print", /* Office and Print */
		"5d643c6a3771300054b6a3549dbe5db0": "print", /* Printers */
		"2c0b59874f7b4200086eeed18110c71f": "plug", /* Peripherals */
		"2809952237b1300054b6a3549dbe5dd4": "desktop" /* Software */
	};
			
	scope.icon = _iconMap[scope.category] || "shopping-cart";
    }
  }
}

        Dieses Skript verknüpft die sys_id des Category-Datensatzes mit dem Servicekatalog-Element. Das angezeigte Symbol ist das Symbol, das im Kategoriedatensatz in Servicekatalog definiert ist .

      3. Wählen Sie Speichern.
    4. Ordnen Sie die neue Angular-Anweisung dem Quick Order Widget zu.
      1. Navigieren zu Alle > Service Portal > Widgetsan.
      2. Öffnen Sie das Schnellbestellungs-Widget.
      3. Unter Verwandte Listen, wählen Sie Angular Providers.
      4. Wählen Sie in der Liste Angular Providers (Angular-Anbieter) Bearbeiten aus, und ordnen Sie die KategorieSymbol Angular Provider dem Schnellbestellungs-Widget zu.
      5. Wählen Sie Speichern.
    5. Fügen Sie der Quick Order-HTML-Vorlage die Anweisung categoryIcon hinzu.
      1. Im Widget-Editor öffnen Sie das Schnellbestellungs-Widget.
      2. Ersetzen Sie die HTML-Vorlage durch das folgende Skript. 
        <div class="panel panel-primary">
  <div class="panel-heading">Request an item from the catalog</div>
  <div class="panel-body">
    <input class="form-control" type="search" placeholder="Start typing here to search the list of catalog items" ng-model="c.data.keywords" ng-change="c.server.update()" ng-model-options="{debounce: 250}" />
    <h5 ng-if="!c.data.keywords">Showing the most popular items</h5>
    <ul class="list-group result-container">
      <li class="list-group-item" ng-repeat="item in c.data.items">
        <a href ng-click="c.select(item.sys_id)"><category-icon category="item.category" style="margin-right: 10px"></category-icon>{{item.name}}</a><span class="pull-right">{{item.price}}</span>
        <div class="catalog-item" ng-if="item.sys_id == c.openItem">
            <sp-widget ng-if="c.catalogItemWidget" widget="c.catalogItemWidget" />
          </div>
      </li>
    </ul>
  </div>
  <div class="panel-footer" ng-if="c.data.keywords">
    <ng-pluralize count="c.data.items.length"
                 when="{'0': 'No items found for ',
                     '1': 'One item matching ',
                     'other': 'Found {} items matching '}">
    </ng-pluralize>
    {{c.data.keywords}}
  </div>
</div>
    6. Aktualisieren Sie die Testseitenvorschau, um die Änderungen anzuzeigen.

      Neben jedem Ergebnis wird ein Kategoriesymbol angezeigt.