TVC Helium : Configuration Guide

The Technia Value Components (TVC) product suite has existed for 10+ years, and contains well-established products such as Structure Browser, Graphic Reporting and File Manager. TVC Helium is the new version of these components, with the first General Availablity release in May of 2016.

The progress of HTML5, JavaScript and web browsers enable us to move HTML rendering and parts of the business logic to the client side, within the end-user’s web browser.

Helium components are designed to be as efficient as possible in terms of reducing server requests, and they support consuming data from any backend serving JSON data. Server calls made by Helium do not return entire prerendered HTML pages - only the JSON data needed to populate the views, which are already cached on the client. This makes server requests both fewer and smaller, leading to benefits in terms of reduced data traffic and shorter load times. In short: Helium is faster and generates less server load.

TVC Helium pages consist of column based grids or dashboards, with all your data placed inside rearrangeable widget containers. This allows for a responsive, customizable design and seamless adoption to mobile devices. Helium is designed with the flat design concept in mind, for a modern, very lightweight look and feel. In short: Helium looks modern and it works on mobile devices.

You may install TVC Helium in silent mode. See example command below for details:

The TVC Helium JAR file contains a /META-INF/web-fragment.xml, which contains the necessary web application descriptor content for Helium to work in a standard J2EE Web Application.

If you install to a web-application that has the metadata-complete="true" set in the WEB-INF/web.xml file, you need to manually configure your web.xml file and include the necessary configurations for Helium to work.

The web-fragment.xml file that is part of Helium looks like this:

Helium does not support ie compatibility mode but there are ways tell the browser to ignore this setting. Helium in standalone mode add these tags by default. For Helium embedded in tvc classic there is a filter that can be added to the web.xml that does the same.

Add to Web.xml

Helium can use Service Workers to cache some service (dynamic) and static resources (.js, .css, .png etc.) so that they are served from the cache instead of making network requests.

Click for more information and options

TVC Helium is continuously tested and validated with latest versions of Apple iOS (with Safari as browser) and Android (with Chrome), on both mobile and tablet devices.

Please note that some features of Helium may be unavailable on handheld devices, and some behaviour may on the other hand be exclusively applicable for handheld devices (such as device vibration or a different notification mechanism).

The Progressive Web App design approach to a web application is in part enabled by the Service Worker browser capability, that enables caching of data for later use. This, along with SSL, are prerequisites for using Helium in Offline mode. Please refer to the Cache section to learn about ServiceWorkers and which tvc.properties exist to enable it, also guaranteeing that static files like JS and CSS are cached by the browser.

With the Helium webapp folder, a manifest file called manifest.json is deployed. When a user opens the Helium webapp URL in their browser, the browser will prompt* the option to install the Helium webapp.

If the user accepts, they can then launch the webapp independently of their web browser, with a native-like behaviour, that minimizes the URL bar to give the webapp UI the fullcreen size. When multi tasking between applications, the app will also look and behave like a native app.

*behaviour varies depending on browser.

On iOS/Safari, manually adding the App to Homescreen may be needed.

If the Helium webapp detects that you have lost your network connectivity, it will indicate the offline status with a CSS class on the body element. You can then choose how this will be rendered in UI; using our examples you can e.g. color the Topbar element gray to indicate that you are not currently connected.

To keep using Helium offline in scenarios like this, you can leverage features like cached navigation to your previously visited Helium pages. To set this up, please refer to the example configuration, which you can customize for your needs.

In addition, it’s also possible to manually save object pages, e.g. for planned offline scenarios. To configure this behavior, please see Saving object pages for offline access.

A command can be added in the topbar or in any widget toolbar to allow scanning of QR, EAN and DataMatrix codes. By default, if the scanned content is detected as Enovia/ 3DEXPERIENCE object id, the framework will open corresponding object else it’ll perform a search for the matched content. The default behavior can be overridden by providing a callback, onScanComplete. Once the framework detects a code, it’ll invoke the callback with the scanned content.

A javascript call can add vibration feedback for supported devices. For more information see the App.Utils JS documentation.

It is now possible to jump between datatable pages by swiping left or right on the table. Feature is not supported for nonresponsive tables.

The routing framework in Helium is mapped to the following URL pattern:

This means that any URL that contains the /goto/…​ relative from the context root will reach the Helium routing filter.

The URL to a particular business object is by default:

The first path part after the /goto url is /o, which will trigger the object route mapping logic.

The URI after /goto/o/ must contain at least the Type and Name. If the third parameter (revision) is omitted, the routing framework will make a query and find the latest revision of the object having the specified Type and Name.

Example URL:

A global page is a page that does not require a business-object as context. A global page is typically used as the first page the user see in Helium after login. The URL to a global page is by default:

This will map to the page tvc:page/NameOfPage.xml.

If you want to map to a page in a sub-domain, see the next example:

This would then map to the page resource tvc:page:domain:subdomain/NameOfPage.xml.

See this page for more information about server side configuration within XML files.

Routing to dashboard is typically used when embedding a Helium dashboard in another application, e.g. 3DExperience. Read the embedding chapter for more details.The URL to a dashboard is by default:

This will map to the dashboard tvc:dashboard/NameOfDashboard.xml.

The dashboard may either have a context or be context-less. A widget in a dashboard showing details for a specific part is an example of a dashboard with context and a widget in a dashboard listing recently visited object is a example of a dashboard without context. Use the parameter objectId to specify the context object.

Example showing a part details dashboard with a context:

Routing to widgets is typically used when embedding a single Helium widget in another application, e.g. 3DExperience. Read the embedding chapter for more details.

The URL to a widget is by default:

This will map to the widget tvc:widget/NameOfWidget.xml.

Mapping to widgets in sub-domains works in the same way as when routing to pages.

The widget may either have a context or be context-less. A widget showing specifications for a specific part is an example of a widget with context and a widget listing recently visited object is a example of a context-less widget. Use the parameter objectId to specify the context object.

Example showing a specification widget with a context:

When routing to a widget the Helium page is rendered without the topbar menu and the widget rendered as headerless.

Note that actions in the header are not available when the widget is displayed in headerless mode. For example, it’s not possible for users to reset customizations unless an action is added inside the widget (e.g. in the toolbar).

The routing framework also handles files that are checked-in to a business object. The URL to a particular file is by default:

The first path part after the /goto url is /f, which will trigger the file download mechanism.

Even though this routing logic exists, it will typically only be used internally in Helium.

There are currently three different UI themes included with TVC Helium out of the box. The default theme "light" is a gray-ish. It’s also suitable if you want to build your own theme from scratch.

The second theme, called "flat", is a bit more inspired by material design, and will evolve towards using more colors, icons and other visual elements.

The third theme, called "blue", is a bit more inspired by Enovia out of the box, that easily blends in if you are using Helium in embedded mode. This theme will be automatically applied on Helium in embedded mode. To disable this behavior, use tvc.helium.embed.forceConfiguredTheme=true in tvc.properties. The default value is false.

The fourth theme named "white", which easily blends with 3DDashboard. This theme will automatically applied when helium is embeded in 3DDashboard. To disable this behavior, use tvc.helium.embed.forceConfiguredTheme=true in tvc.properties. The default value is false.

To switch between themes, change the tvc.properties as below: tvc.helium.theme.current=flat where the value can be flat, blue,white or light (default).

TVC Helium allows including custom scripts and stylesheets and make them available to the client.

Simply putting the files to be included somewhere below /helium/custom and the TVC Helium framework will automatically pick them up for inclusion on the main.jsp page. A good recommendation is to use the following structure for the files.

Coloring gives better visual identity than plain text. Helium supports auto coloring for table columns and chart. This will help in maintaining consistency in color for a given text within the application.

This auto coloring by default enable for charts and table columns it can be configured.

For charts and datatable column, helium will map each string to color, and then these string value will appear in unique color in all over application.

It is by default enable for all charts. However, A Setting can be configured at column as follows

This feature can optionally be extended to color the entire cell and not just cell text by using tvc.helium.datatable.column.colorWholeCell=true global setting.

UI labels and other information that needs to be translated should be kept inside translation files, which are in JSON format.

Helium contains built-in translations located in the directory /helium/lang. There is a file called default.json that contains the built-in translations used internally by Helium. The files below /helium/lang should NOT be changed.

To customize the translations and/or provide translations required by your custom logic, you should put your own translation file below:

The base language you support should be put into the file /helium/custom/lang/default.json.

Translations go into locale specific files, example:

You can also maintain translations in modules structure.

Please read more here.

In many cases there is a need to select more complex data structures from an object and/or relationship, or deal with different kind of business rules. One place where you can do this is via so called data handlers.

Data Handlers is a concept that has been around in TVC since many years. It is a well proven way of doing these kind of things, and it allows you to do so without comprimising the performance.

Data Handlers are deeply described in the TVC Classic documentation package, both within the developer documentation as well as in the administration guides.

One important thing to remember when using Data Handlers in the context of TVC Helium, is that the data (normally kept inside instances of different Cell implementations) works in a slightly different way. E.g. since the consumer of the data is logic that is executed on the client, there must be possibilities to transfer custom data structures down to the client. The TVC Helium Framework has solutions for this.

In TVC Helium, you will not perform any HTML creation on server side. All HTML is created on the client, typically by using so called Handlebars templates. In general terms, this will mean that you will create a file containing a snippet of HTML, with {{brackets}} inserted where you want to display your data or perform logic on it.

Helium’s client side rendering means that features from TVC Classic like Cell Renderers, Field Renderers etc are NOT supported.

You can read more about Handlebars (a superset of Mustache) in their own documentation, at http://handlebarsjs.com

Sometimes when user tries to edit some field but due to session timeout those changes might not get saved and he has to type in the value. To save these efforts a notification is shown to the user when session is timed out.

This can be enabled by configuring below in tvc.properties

tvc.helium.showTimeoutAlert= true // defaults to false

In order to get this notification before getting timedout, this can configured as below:

tvc.helium.timeoutAlert= 60 // seconds

After adding abover property in tvc.properties user will get notifcaiton 60 seconds prior to the timeout so that they can save unsaved changes.

The main configuration of the application is performed in a file named Helium.xml which is located in WEB-INF/classes/.

This file is responsible for the following.

The page component contains Dashboards and/or Tabs. Each Dashboard holds references to one or more widgets and the Tabs element holds references to other Dashboards.

Pages are used when configuring start pages in the application. They are also used in the page mappings.

A sidepanel is a container component where additional content can be placed. It can be either built-in components like (Collaboration) or custom component with own rendering. The visibility of this sidepanel container is toggled by clicking it.

Each page supports defining a sidepanel which can be revealed (slided in) from the right side. When the page is first loaded, the initial state of the sidepanel can be controlled from the component’s status method. Ex: "expand", "hidden", "disabled" or "enabled"

The <Sidepanel> element supports the following child elements.

The <Tabs> element renders a list of tabs, where each <Tab> element holds a reference to a Dashboard or another set of <Tabs> that will be rendered beneath the current tab (multi-level tabs). It is possible to configure different cache behavior for each tab that holds a dashboard.

Each widget supports an additional toolbar that may contain preconfigured actions. The toolbar can either be rendered in horizontal mode or in vertical mode. In vertical mode the toolbar will be placed to the left of the widget.

Like TVC Classic, we can also call OOTB service directly from client side. It will provide more flexibility and configuration support like allowing user to take input with the associated form and also it gives us possibility to perform multi selection and the chaining of the services. To call OOTB services, we need to predefined it in an XML configuration file. The services are then accessed from an ordinary service command, which contains the reference to the XML file that defines/configures the service.

Built-in javascript function App.dataTable.invokeServiceCall can be used to launch 3DExperience services, which can be configured using JSON config.

The main responsibility of the Dashboard is to hold references to different widgets.

All widgets (DataTable, Form, Charts) or any custom widget as described in the widget tutorial, share the following configuration options.

A sidepanel is a container element where additional content within a widget can be placed. It can be either any HTML content, or a menu containing commands. The visibility of this sidepanel container is toggled by clicking it.

Each widget supports defining a sidepanel which can be revealed (slided in) either from the left or the right side. When the widget is first loaded, the initial state of the sidepanel will be closed.

The <Sidepanel> element supports the position and width attribute. Valid values for position is "left" or "right". Valid value for width is a positive integer.

The <Sidepanel> element supports the following child elements.

Helium comes with basic search functionality, configurable in a number of ways. Search can be configured to appear in the global topbar by pointing out a search configuration file in Helium.xml: <Search>tvc:search:helium/TopBarSearch.xml</Search> This will render a magnifying glass icon on which you click to launch the search GUI overlay.

You can also choose to render an input field inside the topbar, so that you can type a query directly into it. The configuration is similar to that of the Topbar Icon <Search> command. A full example can be found in the TopBar chapter.

Please note that for topbar inline search, only <Search version="2"> search configuration is supported, and that you will initiate the search by either hitting enter key or clicking the icon.

Helium supports both server-side and client-side internationalization.

The server-side internationalization is achieved by defining a set of string resource files inside <webapp-root>/WEB-INF/classes directory of the web application.

The client-side internationalization is achieved by defining a set of language files in JSON format inside <webapp-root>/helium/lang or <webapp-root>/helium/custom/lang directory.

To decide which language to load, Helium will look at the current browser language (navigator.language), but if no suitable file is found a default one will be used.

Helium use toaster message to provide user notification. These messgae can be shown using javascript api.

The default options use to show toaster notification can be changed through javascript as shown below :

The above javascript can be placed in webapps/helium/custom folder.

The toaster message are shown for 8 seconds by default, but user might want to see it for longer duration. This can be achieved by adding below configuration in tvc.properties:

tvc.helium.toaster.timeout = 25000 // default is 8000

Helium has a common way of configuring access control that is shared among the different components (except table columns) that has this support (page, tab, commands etc.).

Access Control for table columns can be defined similar to TVC Classic. Please click here for more details.

The access restriction for components (other than table columns) can be defined based upon following:

The example below illustrates how you can construct the access restriction:

Or use an access program:

Or use an access expression:

For Topbar Search command :

For Topbar Myspace and Logout command :

A loader alerts a user to wait for an activity to complete.

It can contain message also. This message appears just below the animation.

One can enable this feature by defining key-value pair like below in translation JSON files

By defining this key/ value pair, all loading animations in the application will automatically display this value. No further configuration is needed.

It is also possible to define custom messages for different loading animations, e.g.

Or

A mix of the above, i.e. default message and custom message is also possible.

Also we can add loader over any particular element on the UI, for ex a table row

JavaScript API, Loader.

It would be helpful for users to have dim and non-reactive backgrounds while working on modal or fullscreen views. This feature can be enabled by configuring tvc.helium.widget.overlay.dimmable= true // default is false in tvc.properties.

The quick search allows users a way to easily find objects of interest. It can be used for various use cases, for example by clicking the magnifying glass in the topbar or when locating a person when editing a Part.

When the quick search is launched it opens as an overlay and the user enters a search term. The search result matching the term is presented and by clicking the search hits the user can open the corresponding object.

In more advanced use cases a search form, displayed on the left hand side, is used to further filter down the search result. The user can for instance specify that only Parts in state Released is of interest.

Quick search supports usage of Search Providers. This means that ENOVIA, EXALEAD or other data source can be used to find relevant information.

With search side panel, search can be configured within a page. Similar to quick search, search side panel allows users a way to easily find objects of interest related to context objects and load search result into page dashboard. When configured search side panel opens on left side with a search form.

When search is performed dashboards in the page can be reloaded with search result, it is possible to configure which dashboards should be reloaded. It may desired that only one dashboard is reloaded with search result and rest are left unaffected. It is also possible to customize this behaviour using javascript callback function and take complete control on what should happen when search is performed, see Client-Side Callbacks for more details.

Like quick search, search panel supports usage of Search Providers. This means that ENOVIA, EXALEAD or other data source can be used to find relevant information.