Skip to content

Commit

Permalink
Merge branch '7.3'
Browse files Browse the repository at this point in the history
  • Loading branch information
@stroomdev66
stroomdev66 committed May 3, 2024
2 parents 08e0c12 + 8fbdbc8 commit aeead76
Show file tree
Hide file tree
Showing 3 changed files with 137 additions and 110 deletions.
76 changes: 17 additions & 59 deletions content/en/docs/user-guide/dashboards/expressions/link.md
View file
Expand Up @@ -8,12 +8,14 @@ description: >
Functions for linking to other screens in Stroom and/or to particular sets of data.
---

Links can be inserted into dashboard tables using the `link` function. Links behave as described in [Internal Links]({{< relref "../internal-links" >}}) and the `link` function is just a convenient way to add them to tables. In addition to the `link` function there are other functions such as `annotation`, `dashboard`, `data` and `stepping` that make it easier to supply the required link parameters.
Links can be inserted into dashboard tables using the `link` function.
All link types described in [Internal Links]({{< relref "../internal-links" >}}) can be added to dashboard tables using the `link` function.
In addition to the `link` function there are convenience functions such as `annotation`, `dashboard`, `data` and `stepping` that make it easier to supply the required link parameters.

## Annotation

{{% see-also %}}
[Annotation Links]({{< relref "../internal-links#Annotation" >}}).
[Annotation Links]({{< relref "../internal-links#annotation" >}}).
{{% /see-also %}}

A helper function to make forming links to annotations easier than using [Link](#link).
Expand Down Expand Up @@ -52,7 +54,7 @@ annotation('Create suspect event annotation', null(), 123, 456, 'Suspect Event',
## Dashboard

{{% see-also %}}
[Dashboard Links]({{< relref "../internal-links#Dashboard" >}}).
[Dashboard Links]({{< relref "../internal-links#dashboard" >}}).
{{% /see-also %}}

A helper function to make forming links to dashboards easier than using [Link](#link).
Expand All @@ -75,45 +77,16 @@ dashboard('Click Here','e177cf16-da6c-4c7d-a19c-09a201f5a2da', 'userId=user1')
## Data

{{% see-also %}}
[Data Links]({{< relref "../internal-links#Data" >}}).
[Data Links]({{< relref "../internal-links#data" >}}).
{{% /see-also %}}

Creates a clickable link to open a sub-set of a source of data (i.e. part of a stream) for viewing.
The data can either be opened in a popup dialog (`dialog`) or in another stroom tab (`tab`).
It can also be display in `preview` form (with formatting and syntax highlighting) or unaltered `source` form.
A helper function to make forming links to data easier than using [Link](#link).

```clike
data(text, id, partNo, [recordNo, lineFrom, colFrom, lineTo, colTo, viewType, displayType])
```

Stroom deals in two main types of stream, segmented and non-segmented (see [Streams]({{< relref "docs/user-guide/concepts/streams" >}})).
Data in a non-segmented (i.e. raw) stream is identified by an `id`, a `partNo` and optionally line and column positions to define the sub-set of that stream part to display.
Data in a segmented (i.e. cooked) stream is identified by an `id`, a `recordNo` and optionally line and column positions to define the sub-set of that record (i.e. event) within that stream.

The line and column positions will define a highlight block of text within the part/record.

Arguments:

* `text` - The link text that will be displayed in the table.
* `id` - The stream ID.
* `partNo` - The part number of the stream (one based).
Always `1` for segmented (cooked) streams.
* `recordNo` - The record number within a segmented stream (optional).
Not applicable for non-segmented streams so use `null()` instead.
* `lineFrom` - The line number of the start of the sub-set of data (optional, one based).
* `colFrom` - The column number of the start of the sub-set of data (optional, one based).
* `lineTo` - The line number of the end of the sub-set of data (optional, one based).
* `colTo` - The column number of the end of the sub-set of data (optional, one based).
* `viewType` - The type of view of the data (optional, defaults to `preview`):
* `preview` : Display the data as a formatted preview of a limited portion of the data.
* `source` : Display the un-formatted data in its original form with the ability to navigate around all of the data source.
* `displayType` - The way of displaying the data (optional, defaults to `dialog`):
* `dialog` : Open as a modal popup dialog.
* `tab` : Open as a top level tab within the Stroom browser tab.

{{% warning %}}
The `displayType` value `tab` is not supported if the dashboard is viewed via a [Direct URL]({{< relref "../direct-urls" >}}). This is because a direct URL displays only the dashboard without Stroom's top level tab bar so it is not possible to open it as a top level tab.
{{% /warning %}}
Example

```clike
data('Quick View', ${StreamId}, 1)
Expand All @@ -138,11 +111,6 @@ Example of a single record (event) from a segmented stream, viewed formatted in
data('View Cooked', ${StreamId}, 1, ${eventId}, null(), null(), null(), null(), 'preview', 'tab')
```

{{% note %}}
To make full use of the `data()` function foe viewing raw data, you need to use the `stroom:source()` [XSLT Function]({{< relref "docs/user-guide/pipelines/xslt/xslt-functions" >}}) to decorate an event with the details of the source location it derived from.
{{% /note %}}


## Link

{{% see-also %}}
Expand All @@ -160,30 +128,20 @@ link(text, url, type)
Example

```clike
link('http://www.somehost.com/somepath')
> [http://www.somehost.com/somepath](http://www.somehost.com/somepath)
link('Click Here','http://www.somehost.com/somepath')
> [Click Here](http://www.somehost.com/somepath)
link('Click Here','http://www.somehost.com/somepath', 'dialog')
> [Click Here](http://www.somehost.com/somepath){dialog}
link('Click Here','http://www.somehost.com/somepath', 'dialog|Dialog Title')
> [Click Here](http://www.somehost.com/somepath){dialog|Dialog Title}
link('https://www.somehost.com/somepath')
> [https://www.somehost.com/somepath](https://www.somehost.com/somepath)
link('Click Here','https://www.somehost.com/somepath')
> [Click Here](https://www.somehost.com/somepath)
link('Click Here','https://www.somehost.com/somepath', 'dialog')
> [Click Here](https://www.somehost.com/somepath){dialog}
link('Click Here','https://www.somehost.com/somepath', 'dialog|Dialog Title')
> [Click Here](https://www.somehost.com/somepath){dialog|Dialog Title}
```

Type can be one of:

* `dialog` : Display the content of the link URL within a stroom popup dialog.
* `tab` : Display the content of the link URL within a stroom tab.
* `browser` : Display the content of the link URL within a new browser tab.
* `dashboard` : Used to launch a stroom dashboard internally with parameters in the URL.

If you wish to override the default title or URL of the target link in either a tab or dialog you can. Both `dialog` and `tab` types allow titles to be specified after a `|`, e.g. `dialog|My Title`.


## Stepping

{{% see-also %}}
[Stepping Links]({{< relref "../internal-links#Stepping" >}}).
[Stepping Links]({{< relref "../internal-links#stepping" >}}).
{{% /see-also %}}

Open the _Stepping_ tab for the requested data source.
Expand Down
155 changes: 112 additions & 43 deletions content/en/docs/user-guide/dashboards/internal-links.md
View file
Expand Up @@ -2,23 +2,27 @@
title: "Internal Links"
linkTitle: "Internal Links"
weight: 50
date: 2024-05-02
date: 2024-05-03
tags:
- link
description: >
Adding links within Stroom to internal items or external URLs.
Adding links within Stroom to internal features/items or external URLs.
---

Within Stroom links can be created in dashboard tables or dashboard text panes that will direct Stroom to display an item in various ways.
Within Stroom, links can be created in dashboard tables or dashboard text panes that will direct Stroom to display an item in various ways.

Links are inserted in the form:
```clike
[Link Text](URL and parameters){Link Type}
```

In dashboard tables links can be inserted using the [`link()`]({{< relref "expressions/link#Link" >}}) function or more specialised functions such as [`data()`]({{< relref "expressions/link#Data" >}}) or [`stepping()`]({{< relref "expressions/link#Stepping" >}}).
In dashboard tables links can be inserted using the [`link()`]({{< relref "expressions/link#link" >}}) function or more specialised functions such as [`data()`]({{< relref "expressions/link#data" >}}) or [`stepping()`]({{< relref "expressions/link#stepping" >}}).

In dashboard text panes, links can be inserted into the HTML as `link` attributes on elements. Note that the text pane must be set to `Show As HTML`.
In dashboard text panes, links can be inserted into the HTML as `link` attributes on elements.

{{% note %}}
The text pane must be set to `Show As HTML` for links to operate.
{{% /note %}}

```html
<div style="padding: 5px;">
Expand All @@ -38,63 +42,88 @@ The link type can be one of the following:

## Dialog

Dialog links are used to embed any referenced URL in a Stroom popup Dialog. Dialog links look something like this in HTML:
Dialog links are used to embed any referenced URL in a Stroom popup Dialog.
Dialog links look something like this in HTML:

```html
<div style="padding: 5px;">
<span style="text-decoration:underline;color:blue;cursor:pointer"
link="[Show](localhost:8080){dialog|Embedded In Stroom}">
link="[Show](https://www.somehost.com/somepath){dialog|Embedded In Stroom}">
Show In Stroom Dialog
</span>
</div>
```

Note that the dialog title can be controlled by adding a `|` and required title after the type, e.g.
{{% note %}}
The dialog title can be controlled by adding a `|` and required title after the type, e.g.
{{% /note %}}

```clike
{dialog|Embedded In Stroom}
```

## Tab

Tab links are similar to dialog links are used to embed any referenced URL in a Stroom tab. Tab links look something like this in HTML:
Tab links are similar to dialog links are used to embed any referenced URL in a Stroom tab.
Tab links look something like this in HTML:

```html
<div style="padding: 5px;">
<span style="text-decoration:underline;color:blue;cursor:pointer"
link="[Show](localhost:8080){tab|Embedded In Stroom}">
link="[Show](https://www.somehost.com/somepath){tab|Embedded In Stroom}">
Show In Stroom Tab
</span>
</div>
```

Note that the tab title can be controlled by adding a `|` and required title after the type, e.g.
{{% note %}}
The tab title can be controlled by adding a `|` and required title after the type, e.g.
{{% /note %}}

```clike
{tab|Embedded In Stroom}
```

## Browser

Browser links are used to open any referenced URL in a new browser tab. In most cases this is easily accomplished via a normal hyperlink but Stroom also provides a mechanism to do this as a link event so that dashboard tables are able to open new browser tabs. Again this can be accomplished by using the [`link()`]({{< relref "expressions/link#Link" >}}) table function but in HTML this might look like:
Browser links are used to open any referenced URL in a new browser tab.
In most cases this is easily accomplished via a normal hyperlink but Stroom also provides a mechanism to do this as a link event so that dashboard tables are also able to open new browser tabs.
This can be accomplished by using the [`link()`]({{< relref "expressions/link#link" >}}) table function.
In a dashboard text pane the HTML could look like this:

```html
<div style="padding: 5px;">
<span style="text-decoration:underline;color:blue;cursor:pointer"
link="[Show](localhost:8080){browser}">
link="[Show](https://www.somehost.com/somepath){browser}">
Show In Browser Tab
</span>
</div>
```

Note that unlike the other link types there is no way to control the browser tab title.
{{% note %}}
Unlike the other link types there is no way to control the browser tab title.
{{% /note %}}

## Dashboard

Instead of viewing/embedding external URLs Stroom links can be used to direct Stroom to show an internal page. The dashboard link type allows Stroom to open a new tab and show a dashboard with the specified parameters. The format for a dashboard link is as follows:
In addition to viewing/embedding external URLs, Stroom links can be used to direct Stroom to show an internal item or feature.
The `dashboard` link type allows Stroom to open a new tab and show a dashboard with the specified parameters.

The format for a dashboard link is as follows:

```clike
[Link Text](uuid=<UUID>&params=<PARAMS>&title=<CUSTOM_TITLE>){dashboard}
```

The parameters for dashboard links are:
* `uuid` - The UUID of the dashboard to open.
* `params` - A URL encoded list of params to supply to the dashboard, e.g. `params=user%3Duser1`.
* `title` - An optional URL encoded title to better identify the specific instance of the dashboard, e.g. `title=Details%20For%20user1`.

{{% note %}}
Parameter values can be URL encoded in XSLT using the `encode-for-uri` function.
{{% /note %}}

An example of this type of link in HTML:

```html
Expand All @@ -106,41 +135,54 @@ An example of this type of link in HTML:
</div>
```

Note that using a pipeline with the appropriate XSLT it is possible to dynamically generate links in dashboard text panes that will be specific to the data being displayed.
{{% note %}}
By using a pipeline with the appropriate XSLT it is possible to dynamically generate links in dashboard text panes that will be specific to the data being displayed.
{{% /note %}}

## Stepping
## Data

A stepping link can be used to launch the data stepping feature with the specified data. The format for a stepping link is as follows:
A link can be created to open a sub-set of a source of data (i.e. part of a stream) for viewing.
The data can either be opened in a popup dialog (`dialog`) or in another stroom tab (`tab`).
It can also be display in `preview` form (with formatting and syntax highlighting) or unaltered `source` form.

```clike
[Link Text](id=<STREAM_ID>&partNo=<PART_NO>&recordNo=<RECORD_NO>){stepping}
```
{{% note %}}
To make full use of data links for viewing raw data, you need to use the `stroom:source()` [XSLT Function]({{< relref "docs/user-guide/pipelines/xslt/xslt-functions" >}}) to decorate an event with the details of the source location it derived from.
{{% /note %}}

An example of this type of link in HTML:

```html
<div style="padding: 5px;">
<span style="text-decoration:underline;color:blue;cursor:pointer"
link="[link](id=1822&amp;partNo=1&amp;recordNo=1){stepping}">
Step Source</span>
</div>
```

## Data

A link can be used to display a specific portion of the data held by Stroom using a data link. The format for a data link is as follows:
The format for a data link is as follows:

```clike
[Link Text](id=<STREAM_ID>&partNo=<PART_NO>&recordNo=<RECORD_NO>&lineFrom=<LINE_FROM>&colFrom=<COL_FROM>&lineTo=<LINE_TO>&colTo=<COL_TO>){data}
[Link Text](id=<STREAM_ID>&partNo=<PART_NO>&recordNo=<RECORD_NO>&lineFrom=<LINE_FROM>&colFrom=<COL_FROM>&lineTo=<LINE_TO>&colTo=<COL_TO>&viewType=<VIEW_TYPE>&displayType=<DISPLAY_TYPE>){data}
```

The parameters for data links are as follows:
* id - The id of the stream to display.
* partNo - The sub part no within the stream to display (usually 1).
* recordNo - The record or event number within the stream to display.
* viewType - Which type of data display to show, `preview` (default), or `source`.
* displayType - Choose whether to display the data in a `dialog` (default), or Stroom `tab`.
* lineFrom, colFrom, lineTo, colTo - In `preview` mode limit the data displayed to the specified selection. In `source` mode highlight the selection.
Stroom deals in two main types of stream, segmented and non-segmented (see [Streams]({{< relref "docs/user-guide/concepts/streams" >}})).
Data in a non-segmented (i.e. raw) stream is identified by an `id`, a `partNo` and optionally line and column positions to define the sub-set of that stream part to display.
Data in a segmented (i.e. cooked) stream is identified by an `id`, a `recordNo` and optionally line and column positions to define the sub-set of that record (i.e. event) within that stream.

The parameters for data links are:
* `id` - The stream ID.
* `partNo` - The part number of the stream (one based).
Always `1` for segmented (cooked) streams.
* `recordNo` - The record number within a segmented stream (optional).
Not applicable for non-segmented streams so use `null()` instead.
* `lineFrom` - The line number of the start of the sub-set of data (optional, one based).
* `colFrom` - The column number of the start of the sub-set of data (optional, one based).
* `lineTo` - The line number of the end of the sub-set of data (optional, one based).
* `colTo` - The column number of the end of the sub-set of data (optional, one based).
* `viewType` - The type of view of the data (optional, defaults to `preview`):
* `preview` : Display the data as a formatted preview of a limited portion of the data.
* `source` : Display the un-formatted data in its original form with the ability to navigate around all of the data source.
* `displayType` - The way of displaying the data (optional, defaults to `dialog`):
* `dialog` : Open as a modal popup dialog.
* `tab` : Open as a top level tab within the Stroom browser tab.

In `preview` mode the line and column positions will limit the data displayed to the specified selection.
In `source` mode the line and column positions define a highlight block of text within the part/record.

{{% warning %}}
The `displayType` value `tab` is not supported if the dashboard is viewed via a [Direct URL]({{< relref "direct-urls" >}}).
This is because a direct URL displays only the dashboard without Stroom's top level tab bar so it is not possible to open it as a top level tab.
{{% /warning %}}

An example of this type of link in HTML:

Expand Down Expand Up @@ -180,8 +222,35 @@ In source mode the optional parameters `lineFrom`, `colFrom`, `lineTo`, `colTo`
### Display Type
Choose whether to display data in a `dialog` (default) or a Stroom `tab`.

## Stepping

A stepping link can be used to launch the data stepping feature with the specified data.
The format for a stepping link is as follows:

```clike
[Link Text](id=<STREAM_ID>&partNo=<PART_NO>&recordNo=<RECORD_NO>){stepping}
```

The parameters for stepping links are as follows:
* id - The id of the stream to step.
* partNo - The sub part no within the stream to step (usually 1).
* recordNo - The record or event number within the stream to step.

An example of this type of link in HTML:

```html
<div style="padding: 5px;">
<span style="text-decoration:underline;color:blue;cursor:pointer"
link="[link](id=1822&amp;partNo=1&amp;recordNo=1){stepping}">
Step Source</span>
</div>
```

## Annotation
A link can be used to edit or create annotations. To view or edit an existing annotation the id must be known or one can be found using a stream and event id. If all parameters are specified an annotation will either be created or edited depending on whether it exists or not. The format for an annotation link is as follows:
A link can be used to edit or create annotations.
To view or edit an existing annotation the id must be known or one can be found using a stream and event id.
If all parameters are specified an annotation will either be created or edited depending on whether it exists or not.
The format for an annotation link is as follows:

```clike
[Link Text](annotationId=<ANNOTATION_ID>&streamId=<STREAM_ID>&eventId=<EVENT_ID>&title=<TITLE>&subject=<SUBJECT>&status=<STATUS>&assignedTo=<ASSIGNED_TO>&comment=<COMMENT>){annotation}
Expand Down

0 comments on commit aeead76

Please sign in to comment.