/
Widgets on-prem (Helium) - Getting started

Widgets on-prem (Helium) - Getting started

Owned by Anders Axelsson
Last updated: Sept 13, 2024
8 min read

Chapter goals & duration

In this chapter you will learn the basics on how to install and configure Helium widgets. You will also learn where to find documentation, examples, installers & license.

Expected duration 3h.

Prerequisites

  • 3DEXPERIENCE dev env (TomEE 3dspace exploded web app)

    • “Issue” data

  • Basic XML & 3DEXPERIENCE / MQL understanding

  • (OPTIONAL) IDE - VSCode, Eclipse or similar

1. Installation

The installers adds web resources to 3dspace (schema is optional but required for live UI configuration etc). The web resources includes jar files, js, html, css etc. A servlet is registered with the web.xml.

Gradle

TECHNIA best practice project setups uses Gradle and Maven artifacts to build 3dspace web archive including TVC Helium. Gradle makes upgrades as easy as changing version in a property file and manual installation steps are avoided.

Gradle setup is not included in this training.

image-20240913-112558.png
image-20240913-112624.png

Exercise 1 - Install product

  1. Go to https://products.technia.com and download the latest Helium installers. Use customer license file or generate a time limited developers license.

  2. Stop TomEE

  3. Install Helium

    • Include ‘Structure Browser’ & 'Graphic Reporting'

2. Installation result and basic Setup

By now the web resources should be installed into your target 3dspace server folder. Value Component basic behaviour is controlled by global properties (e.g production mode for performance or development efficiency) . Let’s have a look at the result in 3dspace.

 

image-20240326-155718.png
image-20240328-102035.png

 

Exercise 2 - Installation result and Setup

  1. ‘3dspace/WEB-INF/web.xml’

    • Search “tvc”, you should find an added servlet, filter, mapping etc.

  2. ‘3dspace/WEB-INF/classes/helium.xml’

    • Copy below minimal setup code snippet (used for object routing etc)

  3. ‘3dspace/WEB-INF/classes/tvc.properties'

    • Copy below properties, remove conflicts from ‘web.xml’

  4. Locate all installed resources

    • ‘3dspace/WEB-INF/lib/tvc*.jar

    • ‘3dspace/webapps/HETrueWidget'

    • ‘3dspace/webapps/tvc'

    • ‘3dspace/WEB-INF/classes/technia.license'

    • ‘3dspace/WEB-INF/tvc' (configs go here in next step)

  5. With the current release a manual bug fix is needed, expand the fix in ‘3dspace/webapps/HETrueWidget/helium/custom/hex'

  6. Start server (3dspace TomEE)

    1. Verify that TVC system initialize correctly in logs (see above screenshot for reference)

  7. (Optional) Useful actions

    1. Clear cache (required in production mode): ‘/3dspace/tvc-action/clearCache’

    2. Set log levels runtime: ‘/3dspace/tvc-action/setLogLevel?logLevel=INFO’

    3. Monitor status & set runtime param: ‘/3dspace/tvc-action/monitorStatus’

    4. List all actions: ‘/3dspace/tvc-action/showActionMappings’

    5. MQL client: ‘/3dspace/tvc-action/MQLClient’

    6. Logs: '/3dspace/tvc/core/tvcLogWatcher.jsp'

    7. User persistence data: '/3dspace/tvc-action/tcm-showDataObjects'

WEB-INF/classes/Helium.xml

<?xml version="1.0" encoding="UTF-8"?> <Application xmlns="http://technia.com/helium/Application"> <DateFormat>YYYY-MM-DD</DateFormat> <DateTimeFormat>YYYY-MM-DD hh:mm</DateTimeFormat> </Application>

WEB-INF/classes/tvc.properties

tvc.core.logLevel=DEBUG tvc.core.productionMode=false tvc.core.user=User Agent tvc.core.password=secret123 tvc.3ddashboard.showEndUserConfigObjects=false tvc.3ddashboard.searchanddrop.enable=true tvc.helium.theme.3ddashboard=3dd

3. Deploy a widget

image-20240402-121729.png
Create Additional App
image-20240402-134738.png
App added to tab from compass

 

Widget definition is done in discrete separate XML files under '3dspace/WEB-INF/tvc'. The separation enable reuse, e.g. a description column could be defined once and referred by hundreds of widgets, templating is also possible, ensuring the same hight quality cross the full application. Read more in the Helium Page docs.

Overview definition structure

Exercise 3 - Deploy a widget

  1. Download issues widget

  2. Expand zip to ‘3dspace/WEB-INF/tvc/training’

    1. View, consider and understand overall file structure.

    2. Reflect on domains ‘training/common’ vs ‘training/issue’.

    3. Find and reflect on the template reference in the originated column

  3. Specify widget in JSON and deploy it somewhere reachable by 3ddashboard e.g. '3dspace/webapps/HETrueWidget/config'.

    1. Use “Sample JSON” code snippet below

  4. 3DDashboard Helium widget docs: 3DDashboard → Platform Management → Add app (Source code URL: https://<BASE_URL>/3dspace/webapps/HETrueWidget/heliumWidget.html, Configuration file URL: PATH TO JSON)

  5. Find the app in compass, add to a dashboard and test it! (should look like above screenshot)

Sample JSON (configuration file content)

{ "id": "training-issues", "title": "Training Issues", "path": "/goto/d/", "parameters": "tvc:dashboard:training:issue/IssuesDashboard.xml", "custom": "true" }

4. Basic Configuration

The framework holds a wide range of configurable features. Let’s take a look at some standard basic configurations done in most implementations.

image-20240403-134113.png
Expected result after applied configurations

Table configuration, Chart configuration

Folder structure notice

Note that there is a difference between the structure of configuration xml references and the folder structure.

Config reference: 'tvc:<CONF_TYPE>:<DOMAIN>:<SUB_1>:<SUB_N>:<FILE>.xml’

Folder structure: ‘tvc/<DOMAIN>/<SUB_1>/<SUB_N>/<CONF_TYPE>/<FILE>.xml’

Exercise 4 - Modify widget configuration

It is recommended to TEST all below steps incrementally (refresh widget in dev mode)

  1. Open 'WEB-INF/tvc' with an IDE, setup to use .xsd schema support, validate and autocomplete

  2. Add Priority column (copy an existing column, use issue domain, reflect why, Column configuration docs).

    1. Add auto colour template (see state column) Auto Colouring Docs

    2. Click an edit a cell value

  3. Add related data column e.g. 'from[Technical Assignee].to.name' (copy column type from owner), and/or Affected Item, Resolved By multiple properties

  4. Modify Data set to exclude closed issues (see docs link and elaborate, maybe past year only..).

  5. Chart configuration (copy paste state chart)

    1. Priority pie

      1. Note the matching table value colour mapping

    2. Owner bar

    3. Originated line

    4. Position the new widgets in a good layout (client reset might be needed) image-20240410-122424.png

  6. Drag drop to OOTB widget

    1. PHYSICALID REQUIRED! use data set select as object id is default.

    2. see below boiler plate and drag drop docs in name column, add lifecycle widget and drop an issue

  7. Create issue using OOTB service (Invoke service command, DS docs docs)

    1. Create servicecommand folder

    2. Create a file with the below service command code snippet

    3. Refer the definition form IssuesTableWidget toolbar <ServiceCommand ref="tvc:servicecommand:training1:issue/CreateIssue.xml"/>

  8. Enable built in table settings (se below boiler plate inc data group, export, sort, filter….)

    1. Try data group by state column in the UI and other features

Expected config result after exercise:

Technical Assignee

<?xml version="1.0" encoding="UTF-8"?> <Column xmlns="http://technia.com/TVC/Table" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://technia.com/TVC/Table http://products.technia.com/tvc/schema/latest/TableColumn.xsd"> <Name>assignee</Name> <Label>Technical Assignee</Label> <Expression>from[Technical Assignee].to.name</Expression> <HeaderNoWrap>true</HeaderNoWrap> <Editable>false</Editable> <ColumnType>helium-user</ColumnType> </Column>

Exclude Closed

<DataSet xsi:schemaLocation="http://technia.com/TVC/DataSet http://products.technia.com/tvc/schema/latest/DataSet.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://technia.com/TVC/DataSet"> <Query> <TypePattern> <Type>type_Issue</Type> </TypePattern> <Where>current!=Closed</Where> </Query> </DataSet>

Drag & drop column settings

<Draggable>true</Draggable> <Setting name="template" value="helium/templates/table/object-link" />

Drag & drop data set - 3DDashboard require physicalid!

<DataSet xsi:schemaLocation="http://technia.com/TVC/DataSet http://products.technia.com/tvc/schema/latest/DataSet.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://technia.com/TVC/DataSet"> <Query> <TypePattern> <Type>type_Issue</Type> </TypePattern> <Where>current!=Closed</Where> <Select>physicalid</Select> </Query> </DataSet>

Service command to create Issue (note current version require string escape of body content when macro is false)

<ServiceCommand> <Label>Create</Label> <FontIcon>ti-c ti-add</FontIcon> <Setting name="OnClick" value="App.dataTable.invokeServiceCall" /> <Setting name="OnClickParams"> { "url": "resources/v1/modeler/dsiss/issue", "header": {"content-type": "application/json"}, "addSecurityContext": "true", "addCsrfToken": "true", "method": "POST", "selectionCriteria": "none", "body": "{\"type\": \"Issue\",\"title\": \"A new Issue\",\"priority\": \"Low\"}", "macro":"false" } </Setting> </ServiceCommand>

Built in table features

<DataTable> ... <Toolbar> ... <DataGroup/> <ExportExcel /> <ExportPDF /> <Search /> <ToggleColumnVisibility /> <AdvanceSorting /> </Toolbar> </DataTable>

5. Create Issue form configuration

There is a configurable form component that could be used to view, edit and create objects. You can either configure with full control or call standard documented ‘OOTB’ services.

image-20240405-064520.png
The Issue create form

Create form

Exercise 5 - Add issue create form

  1. Add servicecommand & toolbar reference Toolbar Docs

  2. Add form config Form Docs

Expected config result after exercise:

Add command to Toolbar

<DataTable> ... <Toolbar> ... <ServiceCommand ref="tvc:servicecommand:training:issue/CreateIssueByForm.xml" /> </Toolbar> </DataTable>

Create Issue Form Command

<ServiceCommand> <Label>Create Issue Form</Label> <FontIcon>ti-c ti-plus</FontIcon> <Setting name="OnClick" value="App.dataTable.invokeServiceCall" /> <Setting name="OnClickParams">{ "macro":"false", "macroElements":"", "selectionCriteria": "none", "form":{ "options":{ "formConfigName": "tvc:form:training:issue/CreateIssueForm.xml", "fullscreen":true, "modal":{ "position":{"top":"30%","bottom":"20%","left":"40%","right":"10%"}, "controls":{"dock":true,"expand":true,"close":true} } }, "url": "resources/v1/modeler/dsiss/issue", "body":{"type": "Issue", "description":"{{description.values[0].value}}","priority": "{{priority.values[0].value}}"}, "method":"POST", "addSecurityContext": true, "addCsrfToken": "true", "bodyResolver": "description.values[0].value,priority.values[0].value" } }</Setting> </ServiceCommand>

Create form

<Form> <Title>Create Issue</Title> <Layout> <Columns>1</Columns> </Layout> <Section> <Field id="description"> <Label>Description</Label> <Editable>true</Editable> <FieldType>textarea</FieldType> </Field> <Field id="priority"> <Label>Priority</Label> <Editable>true</Editable> <FieldType>select</FieldType> <Defaults> <Value value="Low" selected="true"> <Label>Low</Label> </Value> <Value value="Medium"> <Label>Medium</Label> </Value> <Value value="High"> <Label>High</Label> </Value> </Defaults> </Field> </Section> </Form>

6. Launch Pads

Widget templates & examples

With the framework comes several configurations for real OOTB solutions (no extra cost). These configurations is good to use for:

  • Widget implementation templates

  • Runnable example conf reference

Confluence: Launch Pads

image-20240403-125344.png
image-20240403-125917.png

Exercise 6 - Download, expand zip and reference a specific Launch Pad

  1. Download from products.technia.com

  2. Expand issue domain configuration files only onto 3dspace (exclude jar’s etc to avoid server restart)

7. Issue page routing

Page routing is done globally. You map a configuration by type. When clicking links the routing mapping is used to define where to navigate to. When navigating a breadcrumb is added to enable navigate back easily.

Helium routing docs

image-20240405-064709.png
Routed to Launch Pads Issue page

Exercise 7 - Configure Route Config

  1. Add page mapping in Helium.xml

  2. Refresh training widget and click through a link in the issues list

    1. Find the breadcrumb and navigate back

Route config in WEB-INF/classses/helium.xml

<?xml version="1.0" encoding="UTF-8"?> <Application xmlns="http://technia.com/helium/Application"> <PageMapping> <Page namespace="helium:launchpad:issue" name="IssuePage.xml"> <Type is="type_Issue" /> </Page> </PageMapping> </Application>

8. Debug and troubleshoot

image-20240403-085348.png

 

image-20240403-083917.png

 

 

image-20240403-084016.png

 

  1. Log watcher (e.g. try referring column with spelling mistake)

  2. XSD validation

  3. Browser dev tools

9. History

A rich set of configurable UI components for 3DSPACE, 3DDASHBOARD and standalone applications, developed on demand from more than 130 customers in 20 years.

Value Components allows you to optimize 3DEXPERIENCE UI to perfectly match your business processes, this without carrying the added weight of custom code

image-20240405-063520.png

10. Standalone app

Standalone & mobile

It is possible to run the same configuration in standalone streamlined applications. Fully without the complexity of the 3DEXPERIENCE it could be useful for specific use cases such ass introducing hard to adopt user groups to contribute to platform data.

Standalone is not included in this training and requires a full helium install (widget mode unchecked).

image-20240403-085521.png
image-20240403-085539.png
Responsive for mobile

Launch the app standalone in new tab

<BASE URL>/3dspace/goto/d/training/issue/IssuesDashboard

11. Widget Studio - Live configuration using UI (In-app designer)

Studio (In-app designer)

Most configurations could be made live directly from within the UI. This way server access and deploys (release) is no longer needed but view definitions are handled like data.

Studio is not included in this training.

image-20240403-084223.png

Widget Box Studio (youtube)

12. Advanced / Dev

Advanced

There could be requirements outside what is possible by standard configuration. E.g. cells using custom calculation logic. The product supports a wide range of controlled extension plugins using well defined and upgrade safe interfaces.

Development of advanced use cases is not covered in this training.

image-20240403-084401.png

How data handlers works

Code examples

DataHandler interface

void prepareEvaluation(Column column, EvaluationInput input); Cell createCell(Column column, EvaluatedData data); void populateCell(Cell cell, EvaluatedData data);

Related content

TECHNIA CONFIDENTIAL