Customizing UI Previews

Introduction

OSLC resources served by a Lynxwork Connector are displayed in consumer applications through four types of UI previews:

• Small Preview — a compact card shown on hover or inlined
• Large Preview — a detailed card shown on hover or inlined
• Selection Dialog — shows a set of resources for the user to search and select from
• Query Preview — used in query result listings (mainly for debugging purposes)

The information and the layout of each of these preview types is defined by a layout template. The Connector ships with bundled default templates for each supported resource type. You can override any of these by placing your own template files in a designated directory.

• Templates you do not override continue to use the bundled defaults.
• You only need to provide files for the specific resource types and layouts you want to override — everything else continues to use the bundled defaults.

Two tools are available to support the customization workflow:

• Admin page — helps you inspect the currently loaded templates and reload templates after making changes. You can access this page through the Connector page {base_url}/admin/previews/

• Storyboard — helps you design the template layout live, adjust its attributes, and copy the resulting HTML into your template. The following table provides direct links to the most relevant components of a template.

  Component	Tag
  Title	lynx-title
  Section	lynx-section
  Property rows/columns	lynx-short-properties
  Short plain text	lynx-plain-property + heading + value='[…]'
  Date	lynx-date-property + format='Do MMM YY'
  Long HTML text	lynx-long-string-property
  Table	lynx-table
  Link	lynx-link-property + heading + value + url + copy-url + new-tab
  Multi-value list	lynx-list

Instructions

1. Initial setup

   1. Create a directory on the Connector server where the customized preview templates will reside, for example /opt/lynxwork/previews.
   2. You will create templates under this folder using the following folder and file naming convention

      {LYNXWORK_PREVIEW_TEMPLATES_DIR}/
        {resource-type}/          ← lowercase, e.g. "item", "testcase"
          smallpreview.html
          largepreview.html
          query.html
          selector.html

   3. Set the environment variable LYNXWORK_PREVIEW_TEMPLATES_DIR to that path.
   4. Restart the Connector.

2. Get an overview of the current setup through the Preview Admin page

   1. Navigate to {connector_base_url}/admin/previews/.
   2. The Preview Admin page shows all currently loaded type/layout combinations, the path of the override directory, and the timestamp when the layouts were last refreshed.
   3. Select any layout to view a source view of that template’s current content. This content is a good starting point when overriding or creating new templates.

3. Customize the UI previews. You can combine the instructions from any of these three base scenarios to best fit your needs:

   • Scenario 1: Change the layout of an existing resource type
   • Scenario 2: Add a dedicated layout for a subtype
   • Scenario 3: Show additional properties

4. Verifying your changes after creating or modifying a template in the override directory

   1. Click Reload on the Preview Admin page. No Connector restart is required — changes take effect immediately after reload.
   2. Click the layout link for the type/layout you modified.
   3. Confirm the source view reflects your changes.
   4. Navigate to the relevant page in the Connector debug pages to verify that the UI preview renders with the expected layout and content.

Scenario 1: Change the layout of an existing resource type

Rearrange, add, or remove properties from an already existing template layout (e.g. item / largepreview).

1. On the Preview Admin page, select the template you want to override.
2. Copy the entire source from the source view.
3. In your override directory, create the subfolder item/ - if it does not exist.
4. Create a file with the expected template name (e.g. item/largepreview.html) and paste the copied content.
5. Modify the template: rearrange sections, adjust headings, remove <lynx-*> elements you do not need.
6. Reload and verify as described in Verifying your changes.

Scenario 2: Add a dedicated layout for a subtype

The Connector ships with templates for the most general resource type (e.g. item). Depending on your configuration, resources may represent more specific subtypes — for example testcase or changerequest in Jira, or specific work item types in Azure DevOps.

1. From the Preview Admin page, select a template to use as a basis for your more specific subtype.
2. Copy the entire source from the source view.
3. In your override directory, create a subfolder named after the subtype in lowercase, e.g. testcase.
4. Create a file with the expected template name in the subfolder (e.g. testcase/largepreview.html) and paste the copied content.
5. Modify the template: rearrange sections, adjust headings, remove <lynx-*> elements you do not need.
6. Reload and verify as described in Verifying your changes.

The subtype’s own layout will now be used for resources of that type. Any layout not present in the subtype folder falls back to the bundled item default.

Scenario 3: Show additional properties

By default, the Connector fetches and displays a fixed set of properties per resource (title, state, dates, etc.). You can extend this by declaring additional properties in an override template. The Connector detects these declarations automatically and fetches the corresponding values from the backend.

1. Create an override template for the relevant type and layout (similar to Scenario 1 or Scenario 2 above).

2. Add a <lynx-*> binding element for the property you want to show. For example, to show Assigned To in Azure DevOps:

   <lynx-plain-property heading="Assigned To" value="[ado:System.AssignedTo]" align-items="items-center"></lynx-plain-property>

   • The field name (e.g. System.AssignedTo) must be a valid field reference name in the backend.

   • If the field does not exist or the resource has no value for it, the slot is left blank — no error is shown.

   • Do not re-declare properties the Connector already handles by default (title, state, dates, etc.) — this has no effect.

   • Use the correct namespace prefix for your Connector — using a different prefix results in a blank slot without an error:

     Connector	Field prefix
     Azure DevOps	ado
     Jira	jira

3. Reload and verify as described in Verifying your changes.