Technische Dokumentation des Documents-Link-Widget

Changelog

15.11.2022 → Dokumentationsseite erstellt

Diese Seite enthält die technische Dokumentation des Documents-Link-Widget. Mit der Integration kann ein Parameter z.B. die Werksartikelnummer in der Bibliothek gesucht werden, um die betreffende Einzelseite mit dem gefundenen Parameter abzubilden. So können zutreffende Seiten automatisiert am entsprechenden Artikel ausgegeben werden. Im Folgenden werden die Inhalte dieser Seite aufgeführt:

Alle Widgets werden über den “xs-loader” eingebunden. Bitte machen Sie sich mit der Dokumentation https://itek-wissen.atlassian.net/wiki/spaces/SOF/pages/2841313293 vertraut.

Dieses Widget startet eine Suche mit den übergebenen Parametern und stellt die Treffer in Verkaufsdokumenten als Einzelseiten dar. Es werden nur PDF Dokumente berücksichtigt.

Eingang
Hauptparameter	Teilparameter	Pflicht	Beschreibung	Beispielwert
filter		Ja	Die Grundlage des Widgets. Hier wird festgelegt welche Dokumente angezeigt werden sollen.
	searchterms	ja, wenn documents nicht gesetzt ist	Die Parameter bestehen aus Parametern, die einen Array von Strings annehmen um z.B. mehrere Lieferanten anzeigen zu können supplierids infopackagenames documentlanguages tags und Parametern, die einen einzelnen Wert annehmen archived true gibt alle Dokumente zurück. Archiviert und nicht archiviert documentcount die Anzahl der angezeigten Dokumente, die zurückkommen soll language die verwendete Sprache. Im Default auf ‘DE’ gesetzt Alle Parameter können beliebig kombiniert werden um das gewünschte Ergebnis angezeigt zu bekommen.	"filter": { "searchterms": { "supplierids": ["adminlfr1"], "infopackagenames": ["Suchtest"], "documentcountries": ["de"], "documentlanguages": ["de"], "tags": ["Querformat"], "archived": false, "documentcount": 25, "language": "de" } }
	documents	ja, wenn parameters nicht gesetzt ist	Eine Kombination aus Dokumenten-ID und Seite des Dokumentes, das als Thumbnail verwendet werden soll. WICHTIG: Die Dokumenten-Links funktionieren nur wenn der externe Link angelegt und aktiv ist Der Parameter besteht aus: documentid die ID des Dokumentes. Kann z.B. thumbnailpage im default auf 1 gesetzt wenn nichts anderes übergeben wird	"filter": { "documents":[ { "id": "99678681-c7fa-4184-83aa-d9694e9ef790", "thumbnailpage": 4 }, { "id": "76d38ef0-bdcb-4237-bb2c-ff85d073db46", "thumbnailpage": 2 } ] }
pdfviewer		Nein	Objekt mit Konfigurationen für den PDF-Viewer
	position	Nein	Gibt die Position des PDF-Viewers an. Der Viewer kann dadurch verschoben werden um z.B. einen Header aus dem Hintergrund nicht zu überdecken. Das Attribut besteht dabei aus: top Versatz von oben in Pixeln right Versatz von rechts in Pixeln down Versatz von unten in Pixeln left Versatz von link in Pixeln Alle Zahlen werden dabei in Pixel-Werte umgewandelt und als solche interpretiert.	"pdfviewer":{ "position":{ "top": "150px", "right": "20px", "bottom": "50px", "left": "20px" } }
showdocumentdescription		Nein	Parameter, der angibt ob die Beschreibung des Dokumentes unter dem Bild angezeigt wird. Defaultwert: false	"showdocumentdescription": true
showinfopackagename		Nein	Parameter, der angibt ob das Infopaket, in dem sich das Dokument befindet, unter dem Bild angezeigt wird Defaultwert: false	"showinfopackagename": true
style		Nein	JSON-Objekt zur Definition der Primär- und Sekundär-Farbe des Widgets. Das Objekt hat zwei Felder: `primarycolor`: Primärfarbe. Als Wert wird ein Hexadezimal-String erwartet (Beispiel: `"#616161"`). `secondarycolor`: Sekundärfarbe. Als Wert wird ein Hexadezimal-String erwartet (Beispiel: `"#D3D3D3"`).	"style":{ "primarycolor": "#10325C", "secondarycolor": "#F68106" }
downloadinnewtab		Nein	Wird der Parameter auf true gesetzt, so öffnet sich beim klick auf den Downloadbutton ein neuer Tab und die Datei wird heruntergeladen	{ ... "downloadinnewtab": true }
Ausgang
Eingangsevents
closeAlldialogs			Dieses Event kann an das Widget emittet werden. Das Widget fängt das Event und schließt daraufhin alle zu Zeit geöffneten Dialogfenster.	Beispielaufruf: document.querySelector("xs-documents-link").dispatchEvent(new Event("closeAllDialogs"))

Ein einzelnes Dokument mit Default-Einstellungen

image-20221116-094137 (1).png

Mehrere Dokumente mit Default-Einstellungen

image-20221116-094910 (1).png

Wenn der Parameter “showdocumentdescription” auf “true” gesetzt ist

image-20221116-095515 (1).png

Wenn die Parameter “showdocumentdescription” und “showinfopackagename” auf “true” gesetzt sind

image-20221116-101417 (1).png

{
	"filter": {
		"parameters": {
			"supplierids": ["adminlfr1"],
			"infopackagenames": ["Suchtest"],
			"documentcountries": ["de"],
			"documentlanguages": ["de"],
			"tags": ["Querformat"],
			"archived": false,
			"documentcount": 25,
			"language": "de"
		}
	},
        "pdfviewer":{
                        "position":{
                                     "top": 100,
                                     "right": 50,
                                     "down": 0,
                                     "left": 50
                        }
         },
         "style":{
                   "secondarycolor": "#F68106",
                   "primarycolor": "#10325C"
         },
	"maxsize": 50,
    "showdocumentdescription": true,
    "showinfopackagename": true,
	"maxpagesperdocument": 5,
	"downloadinnewtab": true
}

Folgendes Codesnippet in den HTML DOM einbetten.

<!-- Widget -->
<xs-loader 
    accesstoken="[acccesstoken]" 
    refreshtoken="[acccesstoken]" 
    targeturl="https://2.0.open-datacheck.de" 
    widget="xs-documents-link" 
    widgetmode="true" 
    language="de" 
    parameter="ewoJImZpbHRlciI6IHsKCQkiZG9jdW1lbnRzIjogW3sKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpZCI6ICI5OTY3ODY4MS1jN2ZhLTQxODQtODNhYS1kOTY5NGU5ZWY3OTAiLAogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAidGh1bWJuYWlscGFnZSI6IDMwMQogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgewogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgImlkIjogIjc2ZDM4ZWYwLWJkY2ItNDIzNy1iYjJjLWZmODVkMDczZGI0NiIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0aHVtYm5haWxwYWdlIjogMgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIH0KCQldCgl9LAoJIm1heHNpemUiOiA1MCwKCSJtYXhwYWdlc3BlcmRvY3VtZW50IjogNSwKCSJkb3dubG9hZGlubmV3dGFiIjogdHJ1ZQp9">
</xs-loader>

<!-- Widget Resourcen -->
<script src="https://widget.itek.de/xs-loader/1.0.1/runtime.js" defer></script>
<script src="https://widget.itek.de/xs-loader/1.0.1/polyfills.js" defer></script>
<script src="https://widget.itek.de/xs-loader/1.0.1/main.js" defer></script>

<!-- Widget -->
<xs-loader 
    accesstoken="[acccesstoken]" 
    refreshtoken="[acccesstoken]" 
    targeturl="https://2.0.open-datacheck.de" 
    widget="xs-documents-link" 
    widgetmode="true" 
    language="de" 
    parameter="ewoJImZpbHRlciI6IHsKCQkiZG9jdW1lbnRzIjogW3sKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpZCI6ICI5OTY3ODY4MS1jN2ZhLTQxODQtODNhYS1kOTY5NGU5ZWY3OTAiLAogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAidGh1bWJuYWlscGFnZSI6IDMwMQogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIH0sCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgewogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgImlkIjogIjc2ZDM4ZWYwLWJkY2ItNDIzNy1iYjJjLWZmODVkMDczZGI0NiIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0aHVtYm5haWxwYWdlIjogMgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIH0KCQldCgl9LAoJIm1heHNpemUiOiA1MCwKCSJtYXhwYWdlc3BlcmRvY3VtZW50IjogNSwKCSJkb3dubG9hZGlubmV3dGFiIjogdHJ1ZQp9">
</xs-loader>

<!-- Widget Resourcen -->
<link rel="stylesheet" href="https://widget.itek.de/xs-loader/2.0.0/styles.css">
<noscript><link rel="stylesheet" href="https://widget.itek.de/xs-loader/2.0.0/styles.css"></noscript>
<script src="https://widget.itek.de/xs-loader/2.0.0/xs-loader.js" defer></script>

Folgendes Codebeispiel wartet auf das Rückgabevent “status” von dem Documents Widget.

<script defer>
      // Auf ein Event vom Widget "xs-loader" warten. 
      //Wenn das Event "true" ist, kann ein Eventlistener für die DeepSearch registriert werden
      const loader_element = document.querySelector('xs-loader');
      loader_element.addEventListener('loadfinished', (loadEvent) => {
        console.log("Load finished: " +  loadEvent.detail);
        
        // Auf ein Event vom Widget warten.
        const widget_status = document.querySelector('xs-documents');
        widget_status.addEventListener('status', (statusEvent) => {
          console.log('"status" emitted: ' + statusEvent.detail)
        });
      });
</script>

Beispieleinbindung

Widget-Loader V1.x.x

<?php
    $systemURL = "https://2.0.open-datacheck.de"; // URL der Anlage, von der das Widget eingebunden werden soll
    $systemUsername  = ""; // Benutzer auf der Anlage
    $systemPassword = ""; // Passwort des Anlagen-Benutzeres
    $xsloaderVersion = "1.0.1"; // Version des XS-Loader Widgets
    $phpDebug = true; // Debugmode für den PHP Teil
    $phpDisableSSLVerify = true;

    $params = array(
        'grant_type' => 'password',
        'client_id' => 'article_search_client',
        'username'=> $systemUsername,                
        'password' => $systemPassword,
        'scope' => 'customer_portal_view_article_data_30',
    );
    
    try{
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $systemURL . "/oauth2/token");
        curl_setopt($ch, CURLOPT_POST, TRUE);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        if( $phpDisableSSLVerify) {
            //Disable CURLOPT_SSL_VERIFYHOST and CURLOPT_SSL_VERIFYPEER by
            curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
            curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        }
       
        $result = curl_exec($ch);
        if(curl_exec($ch) === false && $phpDebug) 
        {
            echo 'Curl-Fehler: ' . curl_error($ch);
        }
        $json_deepsearch = json_decode($result, true);

        // Widget Parameter konfigurieren
        $parameters = [
            "documents" => [
                   "id" => "99678681-c7fa-4184-83aa-d9694e9ef790",
                   "thumbnailpath" => 5
            ]
         ];
        $jsonParameters = json_encode($parameters);
        $base64Parameters = base64_encode($jsonParameters);
    }catch (Exception $e) {
        if( $phpDebug)
        {
            echo 'Exception abgefangen: ',  $e->getMessage(), "\n";
        }
    }
    
    curl_close($ch);
?>

<html>
    <head>
        <title>Widget Integration Test</title>
    </head>

    <body>
        <noscript>
            Documents-Link funktioniert nur mit aktiviertem Javascript.
        </noscript>

        <!-- Widgetcontainer an die Stelle kopieren, wo das Widget angezeugt werden soll --> 
        <div id="widget-container" class="widget-container" >
            <!-- vor das widget-->
            <noscript>Documents-Link funktioniert nur mit aktiviertem Javascript.</noscript>
            <link rel="stylesheet" href="https://widget.itek.de/xs-loader/<?php echo $xsloaderVersion ?>/styles.css">
            <noscript><link rel="stylesheet" href="https://widget.itek.de/xs-loader/<?php echo $xsloaderVersion ?>/styles.css"></noscript>
            <script src="https://widget.itek.de/xs-loader/<?php echo $xsloaderVersion ?>/runtime.js" defer></script>
            <script src="https://widget.itek.de/xs-loader/<?php echo $xsloaderVersion ?>/polyfills.js" defer></script>
            <script src="https://widget.itek.de/xs-loader/<?php echo $xsloaderVersion ?>/main.js" defer></script>

            <!-- Widget -->
            <xs-loader widget="xs-documents" accesstoken="<?php echo $json_deepsearch['access_token'];?>" refreshtoken="<?php echo $json_deepsearch['refresh_token'];?>" targeturl="<?php echo $systemURL ?>" language="de" widgetmode=true parameter="<?php echo $base64Parameters; ?>"></xs-loader>

            
            <script defer>
                // Auf ein Event vom Widget "xs-loader" warten. 
                //Wenn das searchTermsEvent "true" ist, kann ein Eventlistener für die DeepSearch registriert werden
                const loader_element = document.querySelector('xs-loader');
                loader_element.addEventListener('loadfinished', (loadEvent) => {
                    console.log("Load finished: " +  loadEvent.detail);
                    
                    // Auf ein Event vom Widget warten.
                    const widget_status = document.querySelector('xs-documents');

                    widget_status.addEventListener('shopsearch', (statusEvent) => {
                        console.log('"shopsearch" emitted: ' + statusEvent.detail)
                    });

                    widget_status.addEventListener('shopcart', (statusEvent) => {
                        console.log('"shopcart" emitted: ' + statusEvent.detail)
                    });
                    
                    widget_status.addEventListener('status', (statusEvent) => {
                        console.log('"status" emitted: ' + statusEvent.detail)
                    });
                });
            </script>
        </div>
    </body> 
</html>

Widget-Loader V2.x.x

<?php
    $systemURL = "https://2.0.open-datacheck.de"; // URL der Anlage, von der das Widget eingebunden werden soll
    $systemUsername  = ""; // Benutzer auf der Anlage
    $systemPassword = ""; // Passwort des Anlagen-Benutzeres
    $xsloaderVersion = "2.0.0"; // Version des XS-Loader Widgets
    $phpDebug = true; // Debugmode für den PHP Teil
    $phpDisableSSLVerify = true;

    $params = array(
        'grant_type' => 'password',
        'client_id' => 'article_search_client',
        'username'=> $systemUsername,                
        'password' => $systemPassword,
        'scope' => 'customer_portal_view_article_data_30',
    );
    
    try{
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $systemURL . "/oauth2/token");
        curl_setopt($ch, CURLOPT_POST, TRUE);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        if( $phpDisableSSLVerify) {
            //Disable CURLOPT_SSL_VERIFYHOST and CURLOPT_SSL_VERIFYPEER by
            curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
            curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        }
       
        $result = curl_exec($ch);
        if(curl_exec($ch) === false && $phpDebug) 
        {
            echo 'Curl-Fehler: ' . curl_error($ch);
        }
        $json_deepsearch = json_decode($result, true);

        // Widget Parameter konfigurieren
        $parameters = [
            "documents" => [
                   "id" => "99678681-c7fa-4184-83aa-d9694e9ef790",
                   "thumbnailpath" => 5
            ]
         ];
        $jsonParameters = json_encode($parameters);
        $base64Parameters = base64_encode($jsonParameters);
    }catch (Exception $e) {
        if( $phpDebug)
        {
            echo 'Exception abgefangen: ',  $e->getMessage(), "\n";
        }
    }
    
    curl_close($ch);
?>

<html>
    <head>
        <title>Widget Integration Test</title>
    </head>

    <body>
        <noscript>
            Documents-Link funktioniert nur mit aktiviertem Javascript.
        </noscript>

        <!-- Widgetcontainer an die Stelle kopieren, wo das Widget angezeugt werden soll --> 
        <div id="widget-container" class="widget-container" >
            <!-- vor das widget-->
            <noscript>Documents-Link funktioniert nur mit aktiviertem Javascript.</noscript>
            <link rel="stylesheet" href="https://widget.itek.de/xs-loader/<?php echo $xsloaderVersion;?>/styles.css">
            <script src="https://widget.itek.de/xs-loader/<?php echo $xsloaderVersion ?>/xs-loader.js" defer></script>

            <!-- Widget -->
            <xs-loader widget="xs-documents-link" accesstoken="<?php echo $json_deepsearch['access_token'];?>" refreshtoken="<?php echo $json_deepsearch['refresh_token'];?>" targeturl="<?php echo $systemURL ?>" language="de" widgetmode=true parameter="<?php echo $base64Parameters; ?>"></xs-loader>

            
            <script defer>
                // Auf ein Event vom Widget "xs-loader" warten. 
                //Wenn das Event "true" ist, kann ein Eventlistener für die DeepSearch registriert werden
                const loader_element = document.querySelector('xs-loader');
                loader_element.addEventListener('loadfinished', (loadEvent) => {
                    console.log("Load finished: " +  loadEvent.detail);
                    
                    // Auf ein Event vom Widget warten.
                    const widget_status = document.querySelector('xs-documents');

                    widget_status.addEventListener('shopsearch', (statusEvent) => {
                        console.log('"shopsearch" emitted: ' + statusEvent.detail)
                    });

                    widget_status.addEventListener('shopcart', (statusEvent) => {
                        console.log('"shopcart" emitted: ' + statusEvent.detail)
                    });
                    
                    widget_status.addEventListener('status', (statusEvent) => {
                        console.log('"status" emitted: ' + statusEvent.detail)
                    });
                });
            </script>
        </div>
    </body> 
</html>

Beschreibung

Inhalt

Integration per “xs-loader” Widget

Parameter “xs-documents-link“

Beispielabbildung

Beispielparameter

Beispielintegration

Widget-Loader V1.x.x

Widget-Loader V2.x.x

Beispielevent “status”

Beispielcode (PHP)