Survalyzer Portal SDK

The Survalyzer Portal SDK provides an entry point for developers and demonstrate how to use the public API in conjunction with the survey and report widgets.

Environment Setup
Get the Survalyzers Portal SDK by sending a request to sales@survalyzer.com.

We recommend Visual Studio Code as a development environment:
https://code.visualstudio.com/

To test the implementation we recommend the Live Server plugin for Visual Studio Code.

To start the server simply click right on the HTML File and select “Open with Live Server”.

A new browser window opens and shows the entry page.
Project Structure
After opening the Solution Folder in Visual Studio Code the following file structure appears:

i18n:
The portal is fully multilingual with translations in German and English. The folder i18n contains the translation files as well as the necessary java scripts to support multiple languages.

images:
This folder contains all images which are used across the demo portal.

login:
Contains all necessary code artifacts for the username / password logon and password reset page.

loginsso:
Contains all necessary code if the portal is used with single sign on.

views:
Contains all view templates which are used in the demo portal.
Dependencies
The demo portal uses the following external dependencies to ensure the functionality:

JQuery Version 3.6
– JQuery I18N
Bootstrap Version 4.4
Font awesome 5.11.2

Additional to this the portal is dependent to Survalyzer’s libraries of the core product which are bundled into survalyzer-survey.js and survalyzer-report.js.

Survalyzer uses internally DevExtreme for complex controls like grids: https://js.devexpress.com/

The Survalyzer components contain this library and within the survey and report it could be used by anyone but for adding an own Grid for example each developer needs an own license to be compliant.
Core Concepts
The demo portal is implemented as Single Page Application following modern design patterns. The login page isolated and not part of the portal itself. It is in itself an enclosed application which takes care about getting the Java Web Token (JWT) which is afterwards used within the portal.

The demo portal aims to provide a low code approach to create custom portals by mainly adapting the given concepts and leverage the frameworks code to implement own functionality.

The strategy of the portal is to use the least dependencies possible to keep the footprint low and the learning curve high without the necessity of learning large frameworks like Angular or React. For this sake Survalyzer provides a style guide to make it easy to create decent portals with a similar UX as the core application.

The style guide could be found here: https://styleguide.survalyzer.org/
Navigation & Page Templates
The demo portal provides an easy to use bootstrap based navigation. The navigation is implemented in the root folders index.html:


The related JavaScript handlers are located in the portal.js

In this file on the top there is a mapping between the link name attached by the CSS class and the HTML file which should be loaded by using clicking on the item.

var menuMapping = {
    "menuitem1_link": "topic1.html",
    "menuitem2_link": "topic2.html",
    "menuitem3_link": "topic3.html"
}


Additionally in the document ready handler the click event needs to be attached:

$(".menuitem1_link").click(() => navigate_click("menuitem1_link", content => {
        return content;
}));


The navigate_click handler acts as a templating engine loading the HTML content of the file (view) and injects it into the DOM. The callback provides the possibility to manipulate the HTML and replace placeholders. As a coding convention Survalyzer suggests to use the following syntax for placeholders:

{{placeholderName}}

The views needs to be located in the views folder to be found automatically by the templating function. The navigation request replaces the content of the content section present in the index.html:

<!-- Content Area -->
 <div id="content"></div>


This means that each time the old html is entirely removed from the DOM. This implies that all variables which should be persistent, need to be stored either in the portal.js or settings.js file. Survalyzer’s recommendation is to create a viewModelState variable to bundle all state variables together. The system implementation of this concept could be found in the settings.js file where all portal settings are present.
Multilanguage support
The demo portal is already fully supporting any ISO language. To make it work, several parts needs to play together.

1. The language files.
2. The settings.supportedLanguages variable
3. The settings.language variable
4. The html data attribute or the code translation

The language files are located in the i18n folder and named with the two-letter-iso-code and the suffix .json.


These files need to be wired using the settings.supportedLanguages variable to tell the system which file contains the translations for the given ISO language. The mapping looks like this:

supportedLanguages: {
    "en": "/i18n/en.json",
    "de": "/i18n/de.json"
},


The files itself contains key-value pairs to describe for each identifier the text. The identifiers need to be the same in each file. The translations are used in the HTML by using the following data attribute:

<h2 class="h2 sv-flex-auto" data-i18n="topic3-header"></h2>

The HTML itself shall not contain any static text to avoid flickering effects loading the HTML with the static text and then getting overwritten with the correct translation.

The second use case is messages within the JavaScript code. To get a translated message the following command could be used:

$.i18n( 'topic3-wizard-step3' );

For more advanced use cases please review the vendors documentation which can be found here: https://github.com/wikimedia/jquery.i18n
Survalyzer Widgets
Survalyzer provides three widgets:

1. Survey widget
2. Report widget
3. Wizard widget

Survey widget
https://education.survalyzer.com/knowledge-base/embed-survey-into-your-website/

Report widget
https://education.survalyzer.com/knowledge-base/how-to-embed-a-survalyzer-report-in-my-website/

Wizard widget
All files for the wizard are located in the folder views/wizard. Each wizard needs to have the following files:

– {workflow-name}.html (wizard area)
– {workflow-name}.js (wizard initialization logic)
– {workflow-name}-page{1}.html (wizard page)
– {workflow-name}-page{1}.js (wizard page logic – optional)

Finally the structure looks like this:


Each wizard workflow needs to have this set of files. The {workflow-name}.js contains the initialization for the pages as well as the validation for the next button.

The key part is the pages collection:

pages: [{
index: 1,
title: "",
html: "",
footerHtml: "",
valid(state, html, index) { return true|false; },
onBeforeBack(state, html, prevIndex, newIndex) {},
onAfterBack(state, html, prevIndex, newIndex) {},
onBeforeNext(state, html, prevIndex, newIndex) {},
onAfterNext(state, html, prevIndex, newIndex) {},
afterViewInit(html) {}
}]


The title specifies the caption of the the wizard step and the index the order of the steps. The html property and the footerHtml shall only be used for static html which has no dynamics. For dynamic html use the afterViewInit callback and insert the html into the wizards content area:

var content = $(".js-wizard-content");
content.html("Something dynamic");


This leverages the same mechanic as the navigation request and allows to load / unload each page of the wizard separately. To support this scenario the portal code provides the possibility to bulk load all pages into an array:

wizardContext.pages = [
    { pageUrl: "create-survey-page1.html", pageContent: null },
    { pageUrl: "create-survey-page2.html", pageContent: null },
    { pageUrl: "create-survey-page3.html", pageContent: null },
    { pageUrl: "create-survey-page4.html", pageContent: null },
    { pageUrl: "create-survey-page5.html", pageContent: null }
];


After the content is loaded the pageContent variable could be manipulated in every possible way. The main use case is again placeholder resolvement as shown in the navigation section.

To summarize: The concept of the individual report pages is the same as for the navigation requests with the difference that the content is added to different <div> containers.

For the validation the wizard offers the methods enableNext and enablePrevious with a boolean parameter to goggle the next and previous buttons.

Other wizard related helper methods are:

– loadWizardPages => loads all html files into the wizardContext.pages variable
– closeWizard => closes the wizard dialog
Predefined API calls
The portal template already contains the following helper methods to make the implementation of custom logic as easy as possible:

– readInterview => Reads the Interview for the given surveyId and interviewId
– deleteInterview => Deletes the Interview for the given surveyId and interviewId
– readPanel => Reads the panel for a given Id
– createMembers => Adds members to a given panel
– readMembers => Reads members of a given panel, either with or without interviews
– deleteMembers => Deletes members of a given panel
– inviteMembers => Creates a distributor for a survey and a panel for a given channel
– makeApiCall => Is the base for the previous methods and allows to call all other public APIs
Updated on januari 18, 2022

Was this article helpful?

Related Articles

Need Support?
Please login to your Survalyzer account and use the "Create Support Request" form.
Login to Survalyzer