Technische Dokumentation des Documents-Link-Widget (Technical documentation of the Documents Link widget)

This page contains the technical documentation of the Documents Link widget. With the integration, a parameter, e.g. the factory article number, can be searched for in the library in order to map the relevant individual page with the parameter found. In this way, relevant pages can be automatically output for the corresponding article. The contents of this page are listed below:

All widgets are integrated via the “xs-loader”.

This widget starts a search with the passed parameters and displays the hits in sales documents as single pages. Only PDF documents are taken into account.

Input
Main parameter	Sub-parameter	Mandatory	Description	Example value
filter		Yes	Die Grundlage des Widgets. Hier wird festgelegt welche Dokumente angezeigt werden sollen.
	searchterms	Yes, if documents is not set	The parameters consist of parameters that accept an array of strings to display multiple suppliers, for example supplierids infopackagenames documentlanguages tags and parameters that take a single value archived true returns all documents. Archived and unarchived documentcount the number of displayed documents to be returned language the language used. Default is set to ‘DE’ All parameters can be combined as desired to display the desired result.	"filter": { "searchterms": { "supplierids": ["adminlfr1"], "infopackagenames": ["Suchtest"], "documentcountries": ["de"], "documentlanguages": ["de"], "tags": ["Querformat"], "archived": false, "documentcount": 25, "language": "de" } }
	documents	Yes, if parameters is not set	A combination of document ID and page of the document to be used as a thumbnail. IMPORTANT: The document links only work if the external link is created and active The parameter consists of: documentid the ID of the document. Can be thumbnailpage set to 1 by default if nothing else is passed	"filter": { "documents":[ { "id": "99678681-c7fa-4184-83aa-d9694e9ef790", "thumbnailpage": 4 }, { "id": "76d38ef0-bdcb-4237-bb2c-ff85d073db46", "thumbnailpage": 2 } ] }
pdfviewer		No	Object with configurations for the PDF viewer
	position	No	Specifies the position of the PDF viewer. The viewer can be moved so that, for example, a header from the background is not covered. The attribute consists of: top Offset from top in pixels right Offset from right in pixels down Offset from bottom in pixels left Offset of link in pixels All numbers are converted into pixel values and interpreted as such.	"pdfviewer":{ "position":{ "top": "150px", "right": "20px", "bottom": "50px", "left": "20px" } }
showdocumentdescription		No	Parameter that specifies whether the document description is displayed below the image. Defaultwert: false	"showdocumentdescription": true
showinfopackagename		No	Parameter that specifies whether the info package in which the document is located is displayed below the image Defaultwert: false	"showinfopackagename": true
style		No	JSON object to define the primary and secondary color of the widget. The object has two fields: `primarycolor`: Primary color. A hexadecimal string is expected as the value (Example: `"#616161"`). `secondarycolor`: Secondary color. A hexadecimal string is expected as the value(Example: `"#D3D3D3"`).	"style":{ "primarycolor": "#10325C", "secondarycolor": "#F68106" }
downloadinnewtab		No	If the parameter is set to true, a new tab will open when you click on the download button and the file will be downloaded	{ ... "downloadinnewtab": true }
Ausgang
Eingangsevents
closeAlldialogs			This event can be emitted to the widget. The widget catches the event and then closes all currently open dialog windows.	Example call: document.querySelector("xs-documents-link").dispatchEvent(new Event("closeAllDialogs"))

A single document with default settings

image-20221116-094137 (1).png

Multiple documents with default settings

image-20221116-094910 (1).png

If the parameter “showdocumentdescription” is set to “true”

image-20221116-095515 (1).png

If the parameters “showdocumentdescription” and “showinfopackagename” are set to “true”

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
}

Embed the following code snippet into the HTML DOM.

<!-- 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>

The following code example waits for the return event “status” from the 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>

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>

Description

Contents

Integration via “xs-loader” widget

Parameter “xs-documents-link”

Example image

Example parameters

Example integration

Widget-Loader V1.x.x

Widget-Loader V2.x.x

Example event “status”

Sample code (PHP)