Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Panel
panelIconId1f3af
panelIcon:dart:
panelIconText🎯
bgColor#DEEBFF

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)

  • (OPTIONAL) IDE - VSCode, Eclipse or similar

Table of Contents
stylenone

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.

Info

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.pngImage Addedimage-20240913-112624.pngImage Added
Panel
panelIconId1f4bf
panelIcon:cd:
panelIconText💿
bgColor#F4F5F7

Exercise 1 - Install product

  1. Go to https://products.technia.com and download the latest

...

  1. Helium installers. Use customer license file or generate a time

...

  1. limited developers license.

...

Install TVC https://products.technia.com/app/docs/tvc-documentation-2024.1.0/tvc/install/index.html#installation

  • Structure Browser

  • Graphic Reporting

  • Exclude schema - (require ‘User Agent’ password, default is ‘secret123’)

...

Install Helium https://products.technia.com/app/docs/tvc-helium-documentation-2024.1.1/helium/admin/index.html#installation

  1. Stop TomEE

  2. 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.pngImage Added

image-20240328-102035.pngImage Added

Panel
panelIconId1f446
panelIcon:point_up_2:
panelIconText👆
bgColor#F4F5F7

Exercise 2 - Installation result and Setup

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

    • Search “tvc”, you should find an added servlet

...

...

  1. ‘3dspace/WEB-INF/classes/helium.

...

  1. xml

    • Copy below minimal setup code snippet

...

    • (used for

...

    • object routing etc)

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

    • Copy below

...

    • properties, remove conflicts from ‘web.xml’

  1. 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)

  1. With the current release a manual bug fix is needed, expand the

    View file
    nametrainingjs.zip
    fix in ‘3dspace/webapps/HETrueWidget/helium/custom/hex'

  2. Start server (

...

  1. 3dspace TomEE)

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

  2. (Optional)

...

  1. 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

...

Code Block

...

<?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

...

Code Block
tvc.core.

...

logLevel=

...

DEBUG
tvc.core.

...

productionMode=false
tvc.

...

core.user=User Agent
tvc.

...

Deploy a widget

core.password=secret123
tvc.3ddashboard.showEndUserConfigObjects=false
tvc.3ddashboard.searchanddrop.enable=true
tvc.helium.theme.3ddashboard=3dd

3. Deploy a widget

image-20240402-121729.pngImage Added
image-20240402-134738.pngImage Added

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.

Gliffy
imageAttachmentIdatt4456054819
macroIdef17b501-91cb-4324-aeee-09ee547a9d1e
baseUrlhttps://technia.jira.com/wiki
nameHelium definition structure
diagramAttachmentIdatt4455465004
containerId4452548643
timestamp1711640183046

Overview definition structure

Panel
panelIconId1f446
panelIcon:point_up_2:
panelIconText👆
bgColor#F4F5F7

Exercise 3 - Deploy a widget

  1. Download

...

  1. issues widget

    View file
    nametraining-1.zip

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

...

json widget spec < 3dspace PATH>

...

Go to 3ddashboard → platform management → add app

  • Add widget <SCREENSHOT><URL>

...

  1. /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

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

    1. Use “Sample JSON” code snippet below

  3. 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)

  4. Find the app in compass, add to a dashboard and test it

...

json sample

Code Block
<TODO/>

...

  1. ! (should look like above screenshot)

Sample JSON (configuration file content)

Code Block
{
	"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.pngImage Added

Table configuration, Chart configuration

Note

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’

Panel
panelIconId1f446
panelIcon:point_up_2:
panelIconText👆
bgColor#F4F5F7

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 (

...

Using xsd schema and IDE validation support? <xsd link>

...

Add related data (Assignee and Change Request) <docs link>

...

Add built in template for fancy Priority rendering <docs link>

...

  1. 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

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

  3. Modify Data set to exclude closed issues (

...

Add command using calling ootb service <docs link>

...

Add Priority pie chart <docs link>

...

(Optional) Misconfigure xml and use log watcher to find details

Attribute

Code Block
<boilerPlate/>

XSD validation with IDE

Code Block
<boilerPlate/>

Related Assignee and CR inc group header

Code Block
<boilerPlate/>

Style cell using built-in handlebar template

Code Block
<boilerPlate/>

Modify Data set to exclude closed issues

Code Block
<boilerPlate/>

Toolbar command to add CR using service invoke

Code Block
<boilerPlate/>

Add priority pie

Code Block
<boilerPlate/>

...

  1. see docs link and elaborate, maybe past year only..).

  2. 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.pngImage Added

  3. 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

  4. 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"/>

  5. 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:

View file
nametraining2.zip

Technical Assignee

Code Block
<?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

Code Block
<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

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

Drag & drop data set - 3DDashboard require physicalid!

Code Block
<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)

Code Block
<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

Code Block
<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.pngImage Added

Create form

Panel
panelIconId1f446
panelIcon:point_up_2:
panelIconText👆
bgColor#F4F5F7

Exercise 5 - Add issue create form

  1. Add

...

  1. servicecommand & toolbar reference Toolbar Docs

  2. Add form

...

TEST <SCREENSHOT>

Toolbar sample

Code Block
<boilerPlate/>

Create form sample

Code Block
<boilerPlate/>

HEX / Launch Pads

  1. config Form Docs

Expected config result after exercise:

View file
nametraining3.zip

Add command to Toolbar

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

Create Issue Form Command

Code Block
<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

Code Block
<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

Info

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.pngImage Addedimage-20240403-125917.pngImage Added
Panel
panelIconId1f446
panelIcon:point_up_2:
panelIconText👆
bgColor#F4F5F7

Exercise 6 - Download, expand zip and reference a specific

...

Instructions <docs link>

Useful as runnable documentation or real project templates

Code Block
<boilerPlate/> or json

...

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.pngImage Added
Panel
panelIconId1f446
panelIcon:point_up_2:
panelIconText👆
bgColor#F4F5F7

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

Code Block
<?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.pngImage Added

image-20240403-083917.pngImage Added

image-20240403-084016.pngImage Added

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

  2. XSD validation

  3. Browser dev tools

9. History

Panel
panelIconId1f3db
panelIcon:classical_building:
panelIconText🏛️
bgColor#DEEBFF

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.pngImage Added

10. Standalone app

Info

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.pngImage Added
image-20240403-085539.pngImage Added

Launch the app standalone in new tab

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

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

Info

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.

...

<SCREENSHOT>

12. Advanced / Dev

Info

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.

Covered in separate training.

...

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

DataHandler interface

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