TVC Helium : Extended Configuration

1. Extended Configuration

1.1. Theme support

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 "3dd", 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,3dd or light (default).

1.1.1. Dark Theme

Dark theme makes it easier for users to use the application in low-light environment and improves visibility. On mobile devices, it can also save battery life.

Every theme available in application has its dark mode and user can switch to dark mode by using Themes Menu.

User’s theme preferences are persisted at application level.

Native OS dark theme is also supported. This means that Helium reads your OS display preferences (Light or Dark) from Windows, Android, iOS or Mac OS and automatically applies it within Helium, unless you actively choose another theme from the Theme menu

Dark theme is not supported in Internet Explorer.

1.2. Custom Resources (Scripts, Stylesheets)

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.

/helium/custom/js
/helium/custom/css

Script files must have the suffix .js and stylesheets .css otherwise they will NOT be included.

In a production environment, the number of requests made by the client to the server should be as low as possible.

Try to concatenate and minify the scripts and stylesheets into a single file for optimal performance.

Ensure that TVC is running in production mode in production systems. This will force Helium to use its own concatenated files instead of requesting multiple scripts and/or stylesheets. Read more about Production mode in the admin guide for TVC Core.

1.3. Auto Coloring

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

<Column>
  ...
  <Setting name="Colorable" value="true" />
  ...
</Column>

Figure 1. Auto Coloring

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.

Figure 2. Coloring Entire Cell

1.3.1. Fixed color mapping

It is also possible to assign a fixed color to a specific text. This will be helpful in assigning more meaningful color to text. For example, active can be green color and inactive can be red color.

The mapping files can be defined with name colorMapping.json at <webapp-root>/helium/custom/color.

The framework will first look for file inside <webapp-root>/helium/custom/color with name colorMapping.json, if no suitable file is found, it will fall back to file defined in <webapp-root>/helium/color with name colorMapping.json.

The directory path can be configure by using global setting tvc.helium.resources.directory.path. defaule value is /helium.

For Example, If you want to use built-in color mapping located in the directory <webapp-root>/webapps/HETrueWidget/helium/color then the global setting should be like this tvc.helium.resources.directory.path = /webapps/HETrueWidget/helium.

Following is example colorMapping.json file

{
    "In Work": "#6C7075",
    "Frozen": "#bbe116",
    "Released": "#8FCE00",
    "Obsolete": "#FFD966",
	"Material" :"#ccd5d4"
}

1.3.2. Auto colorable builtin handlebars template

Handlebar template defined to add customized look and feel to table column. A builtin auto colorable handlebar template is available for table column. It can be configured on column as follows:

<Column>
  ...
  <Setting name="template" value="helium/templates/table/autocolorable" />
  ...
</Column>

1.4. Custom Translations (i18n)

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.

The directory path can be configure by using global setting tvc.helium.resources.directory.path. defaule value is /helium.

For Example, If you want to use built-in translations located in the directory <webapp-root>/webapps/HETrueWidget/helium/lang then the global setting should be like this tvc.helium.resources.directory.path = /webapps/HETrueWidget/helium.

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

/helium/custom/lang

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

Translations go into locale specific files, example:

/helium/custom/lang/en_us.json
/helium/custom/lang/en.json
/helium/custom/lang/sv_se.json
…

You can also maintain translations in modules structure.

/helium/custom/lang/projects/default.json
/helium/custom/lang/projects/en_us.json
/helium/custom/lang/projects/en.json
/helium/custom/lang/projects/sv_se.json
/helium/custom/lang/parts/default.json
/helium/custom/lang/parts/en_us.json
/helium/custom/lang/parts/en.json
/helium/custom/lang/parts/sv_se.json
…

The data must be well-formed JSON data, if not, the application does not load correctly. It is wise to run a validation tool to sanity check the JSON files before deployment.

Please read more here.

1.5. Data Handlers

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.

1.5.1. JSONWriteable

Data handlers are responsible for creating Cell instances. A Cell in its simplest form is an instanceof a StringCell, IntCell, RealCell or BooleanCell, etc. These cells are simple because they typically only contain a single value or an array of values.

In more complex situations, you need to keep track of more information than just a literal value, and you need to manage it in a special data structure. So how do you transfer such data structure to the client? The solution is to let your Cell implementation also implement an interface called com.technia.tvc.core.util.json.JSONWriteable.

This interface has one method:

void toJSON(JSONWriter writer)

So letting your cell implement this interface and implement the toJSON method will let you transfer any kind of data structure to the client, where in most cases you will pass the JSON data into a Handlebar template that will render and display this data.

1.6. Cell Renderers replaced by Templates

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

1.7. File Manager

1.7.1. Firefox Extension Alert

Firefox does not allow the side loading of the web extensions which fails to auto install the file manager plugin.

To address this issue, We have enabled a feature to show an alert message in firefox so that user can add the plugin manually by clicking the url available on the message. If user does not want to install the filemanager web extension, user can continue with fallback HTML UI and in that case user needs to disable the alert message by clicking on the button which says Do not show this message again.

tvc.office.filemanager.extension.firefoxInstallAlert=true
Default value is set to false.

Figure 3. Filemanager extension alert for firefox.

1.8. Session timeout notification

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.

Figure 4. Logout Notification

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.

1.9. Invoke Services

1.9.1. Subscription

3DExperience provides different services for subscription actions - Subscribe, Unsubscribe, Edit Subscription, and My Subscriptions. Helium provides provisions to make use of these services and perform the respective actions.

Invoke Service is generic capability in Value Component using which different 3DExperience services can be called. These existing services can be used to load data into table/widget or call the action from the toolbar

3DExperience provides a service to subscribe for events of a particular object for the context user. Helium provides a provision to add command subscribe in the toolbar of a datatable to facilitate subscribe. This command can be configured as below:

<Command>
	<Label>Subscribe</Label>
	<FontIcon>bell icon</FontIcon>
	<OnClick>App.ootbServices.subscribe</OnClick>
	<OnClickParams>{
		"selectionCriteria" : "multi",
		"serviceUrl":"resources/v1/modeler/subscriptions"
		}
	</OnClickParams>
</Command>

Unsubscribe

3DExperience provides a service to unSubscribe for events of a particular object for the context user. Helium provides a provision to add command unSubscribe in the toolbar of a datatable to unSubscribe and object’s events for the context user. This command can be configured as below:

<Command>
	<Label>Unsubscribe</Label>
	<FontIcon>bell slash icon</FontIcon>
	<OnClick>App.ootbServices.unSubscribe</OnClick>
	<OnClickParams>{
		"selectionCriteria" : "multi",
		"serviceUrl":"resources/v1/modeler/subscriptions"
		}
	</OnClickParams>
</Command>

Edit Subscriptions

3DExperience provides a service to edit subscriptions where we can choose to add or remove events on a particular object or group of objects' subscription. Helium provides similar functionality, edit subscriptions can be added as a toolbar command and configured as below:

<Command>
	<Label>Edit</Label>
	<FontIcon>pencil alternate icon</FontIcon>
	<OnClick>App.ootbServices.editSubscription</OnClick>
	<OnClickParams>{
		"selectionCriteria" : "multi",
		"eventsSubscribed": "dataelements.eventsSubscribed",
		"objEventList_NLS": "dataelements.objEventList_NLS",
		"objEventList": "dataelements.objEventList"
		}
	</OnClickParams>
</Command>

There are a few parameters that can be configured in OnClickParams

Name Description Example

Name	Description	Example
eventsSubscribed	JSON path expression for events subscribed from the response of service call	`"eventsSubscribed": "dataelements.eventsSubscribed"`
objEventList_NLS	JSON path expression for available events(internationalized) for selected objects from the response of service call	`"objEventList_NLS": "dataelements.objEventList_NLS"`
objEventList	JSON path expression for available events for selected objects from the response of service call	`"objEventList": "dataelements.objEventList"`

eventsSubscribed

JSON path expression for events subscribed from the response of service call

"eventsSubscribed": "dataelements.eventsSubscribed"

objEventList_NLS

JSON path expression for available events(internationalized) for selected objects from the response of service call

"objEventList_NLS": "dataelements.objEventList_NLS"

objEventList

JSON path expression for available events for selected objects from the response of service call

"objEventList": "dataelements.objEventList"

There is an option to provide a parameter called serviceUrl where we can specify a URL to make service calls for subscribe/unSubscribe/edit Subscriptions in OnClickParams. This parameter is optional and if no serviceUrl is specified default service will be used.

1.9.2. Unsubscribe for context or other user

3DExperience provides a service to allow current user to easily manage their and other users subscriptions for events associated with specific objects. By defining the Unsubscribe command as below in the toolbar settings, users gain quick access to the functionality needed to unsubscribe from events.

<Command>
    <Label>Unsubscribe</Label>
    <Id>unsubscribe</Id>
    <FontIcon>bell slash icon</FontIcon>
    <OnClick>App.ootbServices.unsubscribeUserAndGroup</OnClick>
    <OnClickParams>{
        "useObjectId":true,
        "type":"Part"
    }</OnClickParams>
    <ValidFor>
        <Types>
            <Type>Person</Type>
            <Type>Member List</Type>
            <Type>Group</Type>
        </Types>
    </ValidFor>
</Command>

There are a few parameters that can be configured in OnClickParams

Name Description Example

Name	Description	Example
useObjectId	When dataset configured with select physical id, it will be require to send object id as payload	`"useObjectId": "true"`
type	Type of can be configured for payload	`"type": "Part"`

useObjectId

When dataset configured with select physical id, it will be require to send object id as payload

"useObjectId": "true"

type

Type of can be configured for payload

"type": "Part"

1.9.3. Push Subscription

3DExperience provides a service to allow current user to push subscription for events of a particular object to the other user. Helium provides a provision to add command in the toolbar of a datatable to facilitate push subscription. This command can be configured as below.

<SearchAndConnect >
    <Id>searchAndConnectSubscribeSidepanel</Id>
    <Label>Push Subscription</Label>
    <SelectionCriteria>single</SelectionCriteria>
    <Relationships>
        <Relationship default="true" direction="to">Subscribed Person</Relationship>
    </Relationships>
    <SearchConfig>tvc:search:helium/SearchAndConnectSubscription.xml</SearchConfig>
    <ExpandRow>true</ExpandRow>
    <SubmitButtonLabel>Subscribe</SubmitButtonLabel>
    <OnSubmit>App.ootbServices.searchAndConnectPerson</OnSubmit>
    <OnClickParams>{
        "closePanelOnSearch":true
    }</OnClickParams>
    <ValidFor>
        <Types>
            <Type>Event</Type>
        </Types>
    </ValidFor>
</SearchAndConnect>

There is a parameter that can be configured in OnClickParams

Name Description Example

Name	Description	Example
closePanelOnSearch	This can be configured with true , when it is required to close search panel after click on search button	`"closePanelOnSearch": "true"`

closePanelOnSearch

This can be configured with true , when it is required to close search panel after click on search button

"closePanelOnSearch": "true"

My Subscriptions

3DExperience provides a service which gives list of all subscribed objects for the context user. Helium provides a provision to make use of the service call and populate data in the table directly form the received response. As this table is populated from response, display mode will be flat. Refer configurations related to populating table data from response of service call TableConfig, ColumnConfig

1.9.4. Open Subscription Widget

Helium provides built-in widget to manage subcription on objects. This built-in widget facilates user to manage subcription and can do different operations like Subscribe, Unsubscribe, Edit Subscription and Push Subscription from same view.

This widget can be configured on toolbar command and table columns by using below API

App.page.sidepanel.openDashboard('tvc:dashboard:helium/OpenSubscription.xml','{{objectId}}')

Files column have in-built support for it with below setting configuration

<Column>
	...
	<ColumnType>helium-files</ColumnType>

	<Setting name="options">
		{
			"showSubscription":true
		}
	</Setting>
</Column>

The subscription services are available from versions V6R2022x FP2250, V6R2023x FP2306 and can be used in versions starting with them or above.