HTML und JavaScript

Das Element HTML/JS ermöglicht das Einbetten eigenen HTML-Codes in ein Dashboard. Der Code im Element wird ausgeführt, wenn das Dashboard in die Anzeige kommt. Ein Dashboard besteht aus einer einzigen HTML-Seite. Im Fall von mehreren Kontakt-Treffern enthält diese Seite pro Kontakt ein <div>-Element. Nur eines dieser <div>-Elemente ist zu einem Zeitpunkt sichtbar. Dies ist entweder das erste <div>-Element, das dann den Kontakttreffer mit der höchsten Datenquellenpriorität anzeigt oder das <div>-Element, das zu dem Kontakt gehört, der im Kontakt-Selektor ausgewählt ist. Das Dashboard-Framework versteckt diesen Seitenaufbau vor dem Programmierer. Der Code jedes HTML/JS-Element befindet sich in einem gekapselten Namespace, der zum angezeigten Kontakt gehört, um die Programmierung einfach und übersichtlich zu machen. Ein HMTL/JS-Element besteht üblicherweise aus einer <skript> und einer HTML-Sektion. Alles außerhalb der Skript-Sektion wird als HTML interpretiert. Code-Beispiel:

<!-- Conditional formatting -->
<div id='MyPrio'>{Contact.NAME}</div>

<script>
    if('{Contact.PRIORITY}' > 350)
        document.getElementById('MyPrio').style.color = 'red';
</script>

Die erste Zeile definiert ein Anzeigeelement (<div>), das den Namen eines Kontakts enthält. Dieses Anzeigeelement bekommt eine innerhalb des Dashboards eindeutige ID, unter der es per Java-Script angesprochen werden kann. Das Java-Skript formatiert die Textanzeige in roter Farbe, wenn die Priorität der Datenquelle den Wert von 350 überschreitet. Dazu holt sich das Script unter seiner ID eine Referenz auf das Element und verändert dessen color-style auf rot.

Es ist guter Stil, die erste Zeile eines HTML/JS-Elements als aussagekräftigen Kommentar festzulegen, damit die einzeilige Anzeige in den Eigenschaften des Elements einen leicht zu erfassenden Inhalt anzeigt.

Hinweis

Weitere Informationen finden Sie unter HTML/JS Beispiele.

JavaScript-Library und Datenobjekte

JS-Library-Funktionen

Im JavaScript eines HTML/JS-Elements stehen folgende Funktionen des Dashboard-Frameworks zur Verfügung:

XP.OnLoad(function() { <JS-code> })

Es handelt sich dabei um einen Event-Handler. Er wird vom Framework aufgerufen, wenn das Dashboard zur Anzeige kommt. Diese Funktion darf nicht im eigenen Code aufgerufen werden. Sie wird in der Regel verwendet, um den Inhalt von HTML-Controls zu initialisieren. Siehe HTML-Control initialisieren.

XP.ExecAction( '<Application-ID>', '<Action-ID>', '<command>' )

Führt die Aktion eines ActionExecutors aus und ist damit äquivalent zur Ausführung eine Action aus der Oberfläche. Die Parameter entsprechen denen eines Actions, <command> enthält die Daten des Felds Link-URL.

XP.FormToObject('<form-id>')

Gibt ein Javakskript-Objekt zurück, das die Daten eines HTML-Formulars enthält. Das Objekt kann direkt zum Datenkontext des Dashboards hinzugefügt werden und ist damit in den ActionExecutor-Modulen verfügbar. Siehe Beispiel HTML Formulare.

XP.SerializeForm('<form-id>')

Serialisiert eine HTML-Form in einen JSON-String.

XP.SerializeFormToUrlParams('<form-id>');

Serialisiert eine HTML-Form in einen URL-Parameterstring (z.B. für den Aufruf einer PHP-Seite).

window.external.PreventClose()

Verhindert im XPhone Connect-Client, dass eine Konversation bei Gesprächsende geschlossen wird und Dashboard-Daten verloren gehen. Siehe Beispiel Schließen einer Konversation verhindern.

Funktionen des Document Object Model

document.getElementById('<html-id>').value = '<value>'

Gibt eine Referenz auf ein HTML-Element zurück und ermöglicht den Zugriff auf die Attribute dieses Elements (hier value).

Datenkontext in Dashboard-Variablen

Der Datenkontext eines Dashboards ist unter derselben Syntax wie an anderen Stellen auch im JavaScript verfügbar. Die Bezeichnungen sind unter Variablenbezeichnungen der Datenfelder ersichtlich. Eine Ersetzung findet bei der Erzeugung des Dashboards statt, die Werte sind zur Laufzeit nicht mehr änderbar. Eine Dashboard-Variable ist wie ein konstanter Text zu behandeln, er muss im Skript-Code und in HTML in der Regel in Quote-Zeichen eingeschlossen sein.

Beispiel: {Contact.NAME}

Datenkontext in JavaScript-Objekten

Der komplette Datenkontext wird bei der Erzeugung in JavaScript-Objekte kopiert. Diese Objekte können gelesen, geschrieben und mit eigenen Daten erweitert werden. Die Nomenklatur ist identisch zu den Dashboard-Variablen, die Objekte haben lediglich den Präfix XP.. Der Kontaktname ist beispielweise gespeichert in XP.Contact.NAME.

Zusätzlich zu den Daten-Objekten für XP.Contact, XP.User und XP.Call gibt es die Objekte:

  • XP.Data

  • XP.Action

In das XP.Data-Objekt können alle Daten abgelegt werden, die nicht zu den anderen Kontext-Typen passen (z.B. Daten von Formularen).

In XP.Action ist der Params-Parameter des Link-URL aus Action-Aufrufen hinterlegt. Dies ermöglicht z.B. die einfache Übergabe von Parametern an clientseitige Skripts. Siehe Beispiel Neues Word-Dokument erzeugen.

HTML Formulare

In HTML/JS-Elementen lassen sich HTML-Formulare hinterlegen, deren Daten beim Drücken einer Submit-Schaltfläche automatisch an angeschlossene Anwendungen übergeben werden können. Minimalbeispiel für eine HTML-Form mit Parameterausgabe auf dem Bildschirm:

<!-- 2 forms with 2 text inputs serialize their data and call a skript -->

<script>
    function button_click()
    {
        var form1= XP.FormToObject( '#form1'); // get form data object
        XP.Data.Form1 = form1; // add form data to context XP.Data.Form1
        XP.ExecAction( "BATCH", "RUN", "Name=SkriptDumpAll.bat" );
    }
</script>

<form id="form1">
    <input type="text" name ="EDITCONTROL_1" />
</form>

<input type="button" value="Submit" onclick="button_click()">

Tipp

Hier finden Sie ein weiteres Beispiel: Einfaches HTML-Formular

HTML/JS Beispiele

Bitmaps anzeigen

Sollen HTML/JS-Elemente z.B. Bilder anzeigen, muss dazu eine Ressource auf dem Dashboard-Web-Server referenziert werden. Zu diesem Zweck gibt es auf dem XPhone Server das Verzeichnis Resources im Pfad <Program Files>\C4B\XPhone Connect Server\AppLink\Content. Auf Systemen, die von XPhone V5 aktualisiert wurden, existiert dieses nicht, es kann aber von Hand angelegt werden. Kopieren Sie hier die Dateien hinein, die Sie in Ihrem HTML/JS-Elementen verwenden möchten. Ein Element aus diesem Verzeichnis referenzieren Sie in Ihrem HTML-Code z.B. so:

<img src="content/Resources/contact.png">

Datenfelder bedingt formatieren

Das gezeigte Skript zeigt einen negativen Wert eines Datenfelds in roter Farbe an. Der Ablauf ist wie folgt:

  • Das Anzeigefeld ist als <div> gestaltet, die Ausrichtung des Inhalts ist rechtsbündig. Das <div>-Element erhält eine eindeutige ID, die durch den ausgewählten Kontakt mitbestimmt wird. Als innerHTML wird der Wert des Kontakt-Felds USERDEF_2 festgelegt.

  • Der Wert der Felds USERDEF_2 wird in die Variable balance übertragen, um lesbaren Code zu bekommen. Eine Referenz auf das <div>-Element wird in die Variable element übertragen, ebenfalls um den Code lesbarer zu gestalten.

  • Der Text-Wert für den Wert in USERDEF_2, der im Beispiel einen Währungswert in Textform enthält (z.B. -2.438,78 €) wird über verschiedene Ersetzungs-Operationen in einen rein numerischen Wert umgewandelt.

  • Abschließend wird der Wert auf kleiner 0 geprüft und die Farbe des <div> Elements entsprechend gesetzt.

<!-- Show negative debit balance in red -->
<div align="right" id="debitbalance">{Contact.USERDEF_2}</div>
<script>
    var balance = '{Contact.USERDEF_2}';
    var element = document.getElementById("debitbalance");
    balance = balance.replace("€", "");
    balance = balance.replace(".", "");
    balance = balance.replace(",", ".");
    balance = Number( balance.trim() );
    if( balance < 0 )
        element.style.color = 'red';
</script>

HTML-Control initialisieren

Der Code zeigt ein Formular mit zwei Edit-Controls. Das erste Control wird dynamisch zur Laufzeit initialisiert. In diesem Fall können „errechnete“ Werte für die Initialisierung verwendet werden. Das zweite Control wird statisch bei der Erzeugung der Dashboardseite initialisiert. Falls Controls nicht mit errechneten Werte initialisiert werden sollen, ist die statische Methode des zweiten Controls ressourcenschonender:

<!-- form initialized in 2 ways -->
<script>
    // OnLoad
    XP.OnLoad(function()
    {
        document.getElementById('Firstname_A').value = '{Contact.FIRSTNAME}';
        // alternat.: document.getElementById('Firstname_A').value = XP.Contact.NAME;
    })
</script>
<form id="form1">
    <input type="text" name ="EDITCONTROL_A" id='Firstname_A' />
    <input type="text" name ="EDITCONTROL_B" value= "{Contact.NAME}" />
</form>

Eigene Daten zum Datenkontext hinzufügen

Das Beispiel fügt dem Dashboard-Datenkontext eine Reihe von Parametern hinzu und gibt beim Drücken des „Dump-Buttons den kompletten Kontext auf dem Bildschirm aus:

 <!-- Dump context with custom data -->
<script>
    function MyCustomDump()
    {
        XP.Call.MyNewCallParam1="NewCallParam1";
        XP.Data.MyNewDataParam1 = "NewDataParam1";
        XP.Contact.MyNewContactParam1 = "NewContactParam1";
        XP.User.MyNewUserParam1 = "NewUserParam1";
        XP.ExecAction('BATCH', 'RUN', "Name=SkriptDumpAll.bat");
    }
</script>
<div>
    <a id="myLink" href="#" onclick="MyCustomDump();">Dump custom data</a>
</div>

Wählen aus der Dashboardanzeige

Das Beispiel zeigt einen Hyperlink, der beim Anklicken die Wahl mit der Büronummer des angezeigten Kontakts startet. Damit dies funktioniert, muss auf dem Client eine Anwendung installiert sein, die das URL-Protokoll tel: behandelt (z.B. XPhone Connect):

<!-- Dial contact's office call -->
<script>
    function MyDialFunction()
    {
        document.location.href = "tel:{Contact.CNOCOMPANY}";
    }
</script>
<div>
    <a id="myLink" href="#" onclick=" MyDialFunction();">Dial office number</a>
</div>

Anzeigenamen in Konversationsfenster setzen

Diese Funktion kann verwendet werden, um den Anzeigenamen in einer Konversation zu setzen, wenn z.B. eine Anruferidentifizierung durch JavaScript-Code im Dashboard durchgeführt werden soll. Das Code-Beispiel zeigt den Schnittstellenaufruf in den Windows-Client. Beachten Sie, dass Konflikte und Inkonsistenzen in der Anzeige durch die in XPhone integrierte Anrufersuche entstehen können. Setzen Sie diese Funktion nur ein, wenn das System so konfiguriert ist, dass keine Kontakte in den XPhone-Adressbüchern gefunden werden:

<!--   Set display name in conversation window      -->
<script>
    XP.OnLoad(function()
    {
        var msg = { command: 'PartnerNumberSearch',
                    type: 'event',
                    state: 'new',
                    data: { found: true, displayName: ''} };
        msg.data.displayName='Christopher Perry';
        XP.ClientMessage(JSON.stringify(msg));
        document.getElementById("ToastText").innerText="Name ist: "+ msg.data.displayName;
    })
</script>
<p id="ToastText">
    Displaynamen setzen
</p>

Neue E-Mail erzeugen

Beim Klicken des Hyperlinks wird ein E-Mail-Formular geöffnet, das mit der E-Mail-Adresse des angezeigten Kontakts vorbelegt ist. Damit dies funktioniert, muss der E-Mail-Client das URL-Protokoll mailto: behandeln:

<!-- My HTML (replace with your code) -->
<script>
    function MyMailFunction()
    {
        document.location.href = "mailto:{Contact.EMAIL1}";
        // alert("test");
    }
</script>
<div>
    <a id="myLink" href="#" onclick="MyMailFunction();">Mailto contact</a>
</div>

Einfaches HTML-Formular

<!-- 2 forms with 2 text inputs serialize their data and call a script -->
<script>
    function button_click()
    {
        var form1= XP.FormToObject( '#form1');
        var form2= XP.FormToObject( '#form2');
        XP.Data.Form_A = form1;
        XP.Data.Form_B = form2;
        XP.ExecAction( "BATCH", "RUN", "Name=Dump.bat" );
    }
</script>
<form id="form1">
    <input type="text" name ="EDITCONTROL_A" />
    <input type="text" name ="EDITCONTROL_B" />
</form>
<form id="form2">
    <input type="text" name ="EDITCONTROL_C" />
    <input type="text" name ="EDITCONTROL_D" />
</form>
<input type="button" value="Add Data" onclick="button_click()">

Erweitertes HTML-Formular

Das Beispiel zeigt ein Formular mit diversen Controls. For Form-class xpc zeichnet die Controls in einem zum XPhone Connect-Client passenden Style:

<!-- Extended form -->
<script>
    XP.OnLoad(function() {
        document.getElementById('email').value=XP.Contact.EMAIL1;
        document.getElementById('name').value=XP.Contact.NAME;
        document.getElementById('country').value=XP.Contact.COUNTRY1;
        triggerPreventClose();
    })
    function Form1_onSubmit() {
        event.preventDefault();
        //alert(XP.SerializeForm('#form1'));
        var frm1 = XP.FormToObject('#form1');
        XP.Data.form1 = frm1;
        XP.Data.additionalData = 'MyAdditionalData';
        XP.ExecAction('BATCH', 'RUN', 'Name=SkriptDumpAll.bat|Params=MyTestParam')
    }

    function triggerPreventClose() {
        if (typeof (window.external.PreventClose) != "undefined")
            window.external.PreventClose()
    }

</script>
<form id="form1" class="xpc" onsubmit=" Form1_onSubmit()">
    <header>
        <h2>Example Responsive Form</h2>
        <div>This form breaks at 200px and goes from a left-label form to a top-label form.</div>
    </header>
    <div>
        <label for="name">Name</label>
        <div>
            <input id="name" name="name" placeholder="Full Name" type="text">
        </div>
    </div>
    <div>
        <label for="email">Email</label>
        <div>
            <input id="email" name="email" type="email">
        </div>
    </div>
    <div>
        <label for="country">Country</label>
        <div>
            <input id="country" name="country" type="text">
        </div>
    </div>
    <div>
        <label for="message">Message</label>
        <div>
            <textarea id="message" name="message" spellcheck="true" rows="5" cols="50"></textarea>
        </div>
    </div>
    <div>
        <fieldset>
            <legend>Select a Choice</legend>
            <div>
                <div>
                    <input id="radio1" name="radiochoice" type="radio" value="First Choice" checked="checked">
                    <label for="radio1">First Choice</label>
                </div>
                <div>
                    <input id="radio2" name="radiochoice" type="radio" value="Second Choice">
                    <label for="radio2">Second Choice</label>
                </div>
                <div>
                    <input id="radio3" name="radiochoice" type="radio" value="Third Choice">
                    <label for="radio3">Third Choice</label>
                </div>
            </div>
        </fieldset>
    </div>
    <div>
        <fieldset>
            <legend>Check All That Apply</legend>
            <div>
                <div>
                    <input id="check1" name="check1" type="checkbox" value="First Choice">
                    <label for="check1">First Choice</label>
                </div>
                <div>
                    <input id="check2" name="check2" type="checkbox" value="Second Choice">
                    <label for="check2">Second Choice</label>
                </div>
                <div>
                    <input id="check3" name="check3" type="checkbox" value="Third Choice">
                    <label for="check3">Third Choice</label>
                </div>
            </div>
        </fieldset>
    </div>
    <div>
        <label for="select1">Select a Choice</label>
        <div>
            <select id="select1" name="select1">
                <option value="First Choice">First Choice</option>
                <option value="Second Choice">Second Choice</option>
                <option value="Third Choice">Third Choice</option>
            </select>
        </div>
    </div>
    <div>
        <input id="saveForm" name="saveForm" type="submit" value="Submit">
    </div>
</form>

Schließen einer Konversation verhindern

Diese Funktion verhindert, dass eine Konversation nach Gesprächsende automatisch geschlossen wird und ermöglicht eine Nachbearbeitung des Geschäftsprozesses nach beendetem Anruf. Fügen Sie den Code einem bestehenden HTML/JS-Element hinzu oder erzeugen Sie bei Bedarf ein neues Element:

<!-- Prevent close of conversation window ->
<script>
    // OnLoad
    XP.OnLoad(function()
    {
        if (typeof (window.external.PreventClose) != "undefined")
            window.external.PreventClose();
    })

...

Beispiel JavaScript Anwendung mit allen CSS gestylten Elementen

Das Beispiel zeigt ein Formular mit allen HTML Elementen, die anhand des internen CSS definiert werden:

<script>
    XP.OnLoad(function() {
        var data = ['First Data Row', 'Second Data Row']
        var output = document.getElementById('table-output')
        var title = 'Simple Table (scripted)'

        var data2 = [
            {"firstname": "Anna", "lastname": "Amberg with long text in subject ", "ID": 1, "detail": "Kümmert sich um den Westen" },
            {"firstname": "Felix", "lastname": "Felber", "ID": 2, "detail": "Kümmert sich um den Osten. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum." },
            {"firstname": "Chris", "lastname": "Perry", "ID": 3, "detail": "Kümmert sich um den Norden" }
        ]
        var title2 = 'Accordion Table'
        var output2 = document.getElementById('accordion-table-output')

        XP.BuildSimpleTable(output, data, title)
        XP.BuildAccordionTable(output2, data2, title2, OnSubject, OnDetail);
    })

    function OnSubject(row) {
        return row.lastname;
    }

    function OnDetail(row) {
        return row.detail;
    }
</script>

<!-- Form -->
<form class="xpc">
    <fieldset>
        <header>
            <h2>Questionnaire</h2>
            <div>Please enter information</div>
        </header>
        <label>Name <input type="text" placeholder="please enter"></label>
        <button>Submit</button>
    </fieldset>
</form>
<br>

<!-- Simple Table -->
<div class="xpc-simple-table-title">Simple Table</div>
<div class="xpc-simple-table-row">First Data Row</div>
<div class="xpc-simple-table-row">Second Data Row</div>
<br>

<div id="table-output"></div>
<br>

<div id="accordion-table-output"></div>
<br>

<!-- Custom Action -->
<a href="#" style="background-image:url(https://img.icons8.com/small/2x/download-2.png);" class="dashboard-action">Custom Action</a>
<br>
<a href="#" class="dashboard-action dashboard-action-no-image">Custom Action without an image</a>

Das Ergebnis in der Vorschau sieht dann so aus:

css-example

Haben Sie einen Fehler auf dieser Seite gefunden?

Oder ist etwas nicht gut oder zu ungenau formuliert? Dann freuen wir uns über eine E-Mail, am besten mit einem Verbesserungsvorschlag, an doku@c4b.de. Vielen Dank!