HTML and JavaScript

The HTML/JS element allows you to embed your own HTML code in a dashboard. The code in the element is executed when the dashboard comes into view. A dashboard consists of a single HTML page. In the case of multiple contact hits, this page contains one <div> element per contact. Only one of these <div> elements is visible at a time. This is either the first <div> element, which then displays the contact hit with the highest data source priority, or the <div> element associated with the contact that is selected in the contact selector. The dashboard framework hides this page layout from the programmer. The code of each HTML/JS element resides in an encapsulated namespace belonging to the displayed contact to make programming easy and clear. An HMTL/JS element usually consists of a <script> and an HTML section. Everything outside the script section is interpreted as HTML. Code example:

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

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

The first line defines a display element (<div>) that contains the name of a contact. This display element gets a unique ID within the dashboard, under which it can be addressed via Java script. The Java script formats the text display in red color if the priority of the data source exceeds the value of 350. To do this, the script gets a reference to the element under its ID and changes its color-style to red.

It is good style to set the first line of an HTML/JS element as a meaningful comment, so that the one-line display in the element’s properties shows content that is easy to grasp.

Hint

For more information, see HTML/JS examples.

JavaScript library and data objects

JS library functions

The following functions of the dashboard framework are available in the Java script of an HTML/JS element:

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

This is an event handler. It is called by the framework when the dashboard comes up for display. This function must not be called in your own code. It is usually used to initialize the contents of HTML controls. See Initialize HTML control.

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

Executes the action of an ActionExecutor and is thus equivalent to executing an action from the interface. The parameters correspond to those of an action, <command> contains the data of the Link-URL field.

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

Returns a Javak script object that contains the data of an HTML form. The object can be added directly to the dashboard data context, making it available in the ActionExecutor modules. See example HTML forms.

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

Serializes an HTML form into a JSON string.

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

Serializes an HTML form into a URL parameter string (e.g. for calling a PHP page).

window.external.PreventClose()

In the XPhone Connect client, prevents a conversation from being closed at the end of the call and dashboard data from being lost. See example Prevent closing a conversation.

Functions of the Document Object Model

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

Returns a reference to an HTML element and allows access to the attributes of this element (here value).

Data context in dashboard variables

The data context of a dashboard is available under the same syntax as elsewhere in the Java script. The names can be seen under variable names of the data fields. Substitution takes place when the dashboard is created, and the values cannot be changed at runtime. A dashboard variable is to be treated like a constant text, it must be enclosed in quote characters in the script code and in HTML as a rule.

Example: {Contact.NAME}

Data Context in Javaskript Objects

The complete data context is copied into Javaskript objects during creation. These objects can be read, written and extended with own data. The nomenclature is identical to the dashboard variables, the objects only have the prefix XP.. For example, the contact name is stored in XP.Contact.NAME.

In addition to the data objects for XP.Contact, XP.User and XP.Call there are the objects:

XP.Data
XP.Action

The XP.Data object can be used to store all data that does not fit the other context types (e.g. data from forms).

XP.Action the params parameter of the link URL from action calls is stored. This allows e.g. easy passing of parameters to client-side scripts. See example Create new Word document.

HTML forms

HTML/JS elements can be used to store HTML forms whose data can be automatically passed to connected applications when a Submit button is pressed. Minimal example of an HTML form with parameter output on the screen:

<!-- 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()">

Tip

Here is another example: Simple HTML form

HTML/JS examples

Show bitmaps

If HTML/JS elements are to display images, for example, a resource on the Dashboard web server must be referenced for this purpose. For this purpose there is the Resources directory on the XPhone server in the path <Program Files>\C4B\XPhone Connect Server\AppLink\Content. This does not exist on systems upgraded from XPhone V5, but it can be created manually. Copy the files you want to use in your HTML/JS elements into here. You reference an element from this directory in your HTML code e.g. like this:

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

Conditionally format data fields

The shown script displays a negative value of a data field in red color. The sequence is as follows:

The display field is designed as a <div>, the alignment of the content is right-aligned. The <div> element is given a unique ID, which is co-determined by the selected contact. As innerHTML the value of the contact field USERDEF_2 is set.
The value of the USERDEF_2 field is transferred to the balance variable to get readable code. A reference to the <div> element is transferred to the variable element, also to make the code more readable.
The text value for the value in USERDEF_2, which in the example contains a currency value in text form (e.g. -2,438.78 €) is converted to a purely numeric value via various replacement operations.
Finally, the value is checked to smaller 0 and the color of the <div> element is set accordingly.

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

Execute hyperlink

The code creates a hyperlink whose color and mouse pointer can be influenced. In the onClick handler the data can be processed before it is used to control other applications:

<!-- Custom hyperlink -->
<script>
    function MyClickFunction()
    {
        document.location.href = "https://www.c4b.com";
    }
</script>
<div>
    <a nohref style="cursor:pointer;color:red;text-decoration:underline"
        onClick="MyClickFunction();">My red custom Hyperlink</a>
</div>

Initialize HTML control

The code shows a form with two edit controls. The first control is initialized dynamically at runtime. In this case, “calculated” values can be used for initialization. The second control is initialized statically when the dashboard page is created. If controls are not to be initialized with calculated values, the static method of the second control is more resource efficient:

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

Add your own data to the data context

The example adds a number of parameters to the dashboard data context and outputs the complete context on the screen when the “Dump button is pressed:

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

Select from the dashboard display

The example shows a hyperlink which, when clicked, starts dialing with the office number of the displayed contact. For this to work, an application that handles the URL protocol tel: must be installed on the client (e.g. 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>

Set display name in conversation window

This function can be used to set the display name in a conversation when, for example, caller identification is to be performed by javascript code in the dashboard. The code example shows the interface call into the Windows client. Note that conflicts and inconsistencies in the display may arise due to the caller search integrated in XPhone. Only use this function if the system is configured so that no contacts are found in the XPhone address books:

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

Create new email

Clicking the hyperlink opens an email form pre-populated with the email address of the displayed contact. For this to work, the email client must handle the mailto: URL protocol:

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

Simple HTML form

<!-- 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()">

Advanced HTML form

The example shows a form with various controls. Form class xpc draws the controls in a style that matches the XPhone Connect client:

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

Prevent closing a conversation

This feature prevents a conversation from being automatically closed after the call ends and enables post-processing of the business process after the call has ended. Add the code to an existing HTML/JS element or create a new element if needed:

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

...

Example JavaScript application with all CSS styled elements.

The example shows a form with all HTML elements defined using the internal CSS:

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

The result in the preview will look like this:

css-example

Have you found a mistake on this page?

Or is something not formulated well or too vague? Then we look forward to receiving an e-mail, preferably with a suggestion for improvement, to doku@c4b.de. Thank you very much!