Web Interface: Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 67: Line 67:
Note that custom panels will periodically refresh, as data in the Engine is updated. This is so that the panel will always display the latest data as made available by the Engine. For some more complex projects, this may need to be taken into account when designing additional interface elements.
Note that custom panels will periodically refresh, as data in the Engine is updated. This is so that the panel will always display the latest data as made available by the Engine. For some more complex projects, this may need to be taken into account when designing additional interface elements.


Also note that this is in contrast to indicator panels and popups opened explicitly by the user. These are opened in an <code>&lt;iframe&gt;</code> and do not automatically refresh when the Engine has new data available. This allows for more complex interfaces in these panels.
Also note that this is in contrast to indicator panels and popups opened explicitly by the user. Panels which are explicitly opened in the web interface are opened in an <code>&lt;iframe&gt;</code> and do not automatically refresh when the Engine has new data available. This allows for more complex interfaces in these panels.


===Frontpage===
===Frontpage===
Line 104: Line 104:


Images cannot be unloaded, but they can be overwritten by uploading a new image with the same name.
Images cannot be unloaded, but they can be overwritten by uploading a new image with the same name.


==Authentication==
==Authentication==
Line 125: Line 122:


===Using tokens in panels===
===Using tokens in panels===
When using images uploaded to the Tygron Engine, they need to be referred to using an url with an authentication token. Because the authentication token will differ between stakeholders and between sessions, it's not recommended to literally place a token in those urls when creating panels. Instead, you can use the notation <code>$TOKEN</code>. When content, such as de CSS file or a panel is served by the Tygron Engine, every instance of <code>$TOKEN</code> is automatically replaced by the appropriate token.

Revision as of 13:30, 5 January 2018

This article is a stub.

Web interface

Web interface for Tygron Engine projects

Besides the regular user interface provided by the Tygron Engine, there is also web interface available for the participants in a session. This interface can be accessed using most modern web browsers. It is completely composed of HTML, CSS, and javascript, functioning like a common web page. The CSS file can be changed, and HTML and javascript can be injected into the interface, as part of a panel which can be selected via the editor. This allows the web interface to be fully customized in both function and appearance.

The web interface can be found at the url https://preview.tygron.com/web/. A correct session token must be provided as a parameter.

Limitations

The web interface does not function as a perfect replacement for the regular, 3D user interface. Contrary to the regular user interface, the 3D world is displayed in 2D. It's not possible to draw selections in the 2D map, which means that users will be unable to take conventional actions such as placing constructions or purchasing land. Visuals, such as cinematics, special effects, weather effects, and visible traffic are not yet available for the 2D map. The web interface also remains available while a (multi-user) session is paused.

Accessing the Web Interface

When running a single or multi-user session, the user can retrieve their own link (and token) for the web interface. They can do this by taking the following steps:

How to get the web interface url as user:
  1. Select the stakeholder name in the Top bar.
  2. Select "Open in browser".

Lastly, the facilitator can also retrieve each (playable) stakeholder's url and token. In the facilitator application, the link can be obtained by taking the following steps:

How to get the web interface url as facilitator:
  1. Select the desired team of which you would like the url.
  2. Select the "Stakeholder" tab.
  3. Select the desired stakeholder.
  4. Select "Show frontpage in browser.

When a session is active in the Tygron Engine, its web interface is accessible via a url. In an editor session, the link can be obtained in this location:

Template:Editor ribbon

The url will have the following form:

https://engine.tygron.com/web/?token=TOKEN

In this url, TOKEN should be replaced by a proper authentication token for that session.

Validity of authentication tokens

Links in the Engine for the web interface are automatically supplied with a valid token. The token will differ between stakeholders. This means that 2 users, who are to control different stakeholders, can be provided with the same link but with a different token.

When a single or multi user session is saved and closed, and later reloaded, the exact same tokens will be valid, and be related to the exact same stakeholders.

See also: Authentication.

Note: When there is already a session running with the same session token, the newly loaded session will have a new, random session token. This may occur when a save state is loaded multiple times in the same moment.

Configuring the Web Interface

This article describes a technical aspect, and is mainly for advanced users.

Although by default the web interface provides basic functionality and styling similar to the Tygron Engine itself, it is possible to configure the web interface. This can be done, for example, to more closely suit your use-cases, meet your organizations desired or required styling, or expand on the functionality provided to the end-user.

Template:Editor ribbon

Map

The map of the web interface is the most important part of the web interface. The map is only displayed in 2D, rather than 3D in the regular client. Despite this, it can still be referred to as the 3D World for most purposes. It is possible to move around across the map by clicking and dragging. It's also posible to zoom in and out by using the scrollwheel.

By default, the map will display the satellite map, which is also seen in the 3D interface. Overlaid on top are the polygons indicating the locations of water, roads, and constructions such as buildings.

How to change the base map:
  1. Open the Web Settings panel.
  2. Change the "Base map" to the desired setting.

Session Interface

The session interface is, in principle, the same as the regular user interface. The top bar can be found at the top of the screen, and the map panel on the right of the screen. However, there is no action menu available.

When a popup appears in the world, for example because of a stakeholder taking an action, or a panel being/becoming visible, the popup will be visible in the 2D map as well, and can be interacted with. Clicking the popup will open the related popup with the same contents and options are would be available in the 3D interface. Attention is not explicitly drawn to any popups in the web interface.

The session interface can not be edited directly. However, it is possible to use CSS, or javascript in a custom panel, to hide, move, or alter any available interface elements.

Custom HTML

It is possible to add custom content to the web interface as well. A panel can be selected to inject directly into the web interface, in a separate <div> element with both class and id set to "custom". If the content is HTML, and it contains <script> elements with javascript, the content will be injected into the page, and the javascript will be executed in order afterwards.

How to add a custom panel:
  1. Create a panel with the desired content.
  2. Open the Web Settings panel.
  3. Make sure the "Custom Panel" checkbox is checked.
  4. Select the desired panel in the dropdown menu.

Note that custom panels will periodically refresh, as data in the Engine is updated. This is so that the panel will always display the latest data as made available by the Engine. For some more complex projects, this may need to be taken into account when designing additional interface elements.

Also note that this is in contrast to indicator panels and popups opened explicitly by the user. Panels which are explicitly opened in the web interface are opened in an <iframe> and do not automatically refresh when the Engine has new data available. This allows for more complex interfaces in these panels.

Frontpage

It is also possible to configure a custom frontpage for the web interface. Any panel in the project can be selected as the frontpage. When a frontpage is set, users will be presented not with the 2D map, but with the defined frontpage content instead. This allows a project creator to add a splashscreen or login page to the web interface. The fronpage is a separate page from the page with the 2D map. The 2D map will not be present on the frontpage. If a custom panel is set, the custom panel will also not be present on the frontpage.

How to add a frontpage:
  1. Create a panel with the desired content.
  2. Open the Web Settings panel.
  3. Make sure the "Front Page Panel" checkbox is checked.
  4. Select the desired panel in the dropdown menu.

The default web interface link will link to the newly set frontpage: https://engine.tygron.com/web/?token=TOKEN.

The 2D map can still be accessed via the following direct link: https://engine.tygron.com/web/map.html?token=TOKEN.

Assets

Besides the content which is directly available, there are also a number of additional assets which can be uploaded to the project. These assets can then be referenced by content in the web interface to enrich the presentation of the content in the web interface.

CSS

Each project has a default CSS file available, which is used to define how the HTML of the web interface is displayed. Each project has a default CSS file which defines the default styling for the web interface. This CSS file can be downloaded from a project while in the editor. New or modified CSS files can also be uploaded to the project. In principle, only one CSS file can be uploaded at a time. Only one CSS file is provided in the web interface at a time. When uploading a new CSS file, it overwrites the existing CSS file.

It is important to note that the CSS file is only provided to the web interface (both the 2D map and the frontpage), and not to the regular user interface. This means that if the CSS file affects the styling of the contents of panels or indicators, there may be styling differences between the regular user interface and the web interface.

How to retrieving the current CSS file:
  1. Open the Web Settings panel.
  2. Select "Download current CSS file".
How to retrieving the current CSS file:
  1. Open the Web Settings panel.
  2. Select "Upload new CSS file".
  3. Select the file to upload.

Images

Each project can have images uploaded to it. When uploaded, each image will have their own url. That url can be used in indicators and panels to refer to those images. Images can only be uploaded when they are in the .png format.

How to add images:
  1. Open the Web Settings panel.
  2. Select the "Image URL" text area.
  3. In the Select Asset window, select "Upload asset".
  4. Select the desired file to upload and select "Open".

After following these steps, the file is uploaded. The file can be accessed via a link generated by the engine. The link for the asset can be obtained by selecting it in the same menu.

How to obtain the url of uploaded images:
  1. Open the Web Settings panel.
  2. Select the "Image URL" text area.
  3. In the Select Asset window, select the desired image.
  4. Select "Apply".
  5. In the Web Settings panel, the url is now displayed "Image URL" text area.

The url will be a relative url of the form "assets/image.png?token=$TOKEN". The full url will be: https://engine.tygron.com/web/assets/image.png?token=$TOKEN.

Note that as token "$TOKEN" is displayed. This notation is automatically replaced by the engine to match the appropriate token when required. See also: Using tokens in panels.

Images cannot be unloaded, but they can be overwritten by uploading a new image with the same name.

Authentication

This article describes a technical aspect, and is mainly for advanced users.

To connect to a session via the web interface, an authentication token must be provided. The authentication token consists of 2 parts: the session token and the web token. The session token identifies the session. The web token identifies the rights or perspective the user has therein. The authentication token is always exactly 32 characters long.

Sessiontokens

Each session has a unique session token, 8 characters long. This token uniquely identifies a session. Each time a project is started in the editor, that editing session will have a new session token. When a project is loaded as a single or multi user session, those sessions also each have a unique session token. When there are multiple teams, each team is a separate session (even when managed by a single facilitator application), and as such each have their own unique token.

When a single or multi user session is saved, its session token is saved as well. When (re)loading that saved state, the session will have the same session token.

Note: When there is already a session running with the same session token, the newly loaded session will have a new, random session token. This may occur when a save state is loaded multiple times in the same moment.

Webtokens

Each stakeholder has their own webtoken, which is part of the authentication token. This token indicates the rights or perspective the user has in the session. By default, the stakeholder webtokens are 24 characters long, and can be made up of upper- and lowercase letters, and numbers. It's possible to generate new webtokens for all stakeholders. When generating new webtokens, it is also possible to generate shorter webtokens. The complete authentication token will be padded with 0's between the session token and the web token.

Webtokens for stakeholders are randomly generated when the stakeholders are first added to a project, and do not change when a project is re-opened, loaded as a different type of session, or copied. After they are first created, webtokens are only generated anew when that option is selected in the editor.

Using tokens in panels

When using images uploaded to the Tygron Engine, they need to be referred to using an url with an authentication token. Because the authentication token will differ between stakeholders and between sessions, it's not recommended to literally place a token in those urls when creating panels. Instead, you can use the notation $TOKEN. When content, such as de CSS file or a panel is served by the Tygron Engine, every instance of $TOKEN is automatically replaced by the appropriate token.