BuildMaster Documentation

Custom Value Renderers

  • Last Modified: 2019-07-18

Variable value renderers are used to control or modify how a specific variable's value is rendered on an overview page. This can be used to support use-cases such as:

  • Linking to another page within BuildMaster
  • Linking to an external tool
  • Displaying a subset of properties of a map
  • Adding customized styles or images to a value
  • Cleanup of names that are too long or unreadable

A value renderer may be specified at the system, application group, or application level, and applies to variables displayed on the following pages:

  • Build overview
  • Release overview
  • Application settings
  • Pipeline details
A Variable Value Before Rendering

A Variable Value After Rendering

Adding a Custom Renderer

To add a custom renderer, visit the Administration > Variables > Value Renderers tab, and enter the name and scope of the variable that will use the custom renderer.

Only non-legacy variables are considered when applying a value renderer. Additionally, variables denoted as sensitive in the UI will be rendered as (hidden) regardless if a value renderer matches or not.

Value Renderer Format

A value renderer is specified as HTML. The rendered HTML also considers variable functions in context, including for example: $BuildNumber, $Substring(...), and $ApplicationName. To access the variable's value within the renderer itself, use $Value (or @Value/%Value depending on type).

Because values are rendered as HTML, BuildMaster administrators (i.e. you) are responsible for ensuring that values are either fully-trusted (i.e. only trusted parties create safe values), or that they are properly sanitized to prevent Cross Site Scripting attacks, malformed HTML, and more. A number of helpful functions are included in the InedoCore extension to mitigate these risks such as $HtmlEncode(), $UrlEncode(), and $JsEncode().

Examples

  • Simple Substring
  • 3-property Map
  • Custom Image
$Substring($Value, 0, 10)...

Initial value: This value is too long to fit on the page

Rendered as: This value...

<a href="%Value.Href?queryData=$UrlEncode(%Value.Data)">$HtmlEncode(%Value.Text)</a>

Initial value: %(Text: Some link text..., Href: https://example.org, Data: "some string")

Rendered as: Some link text...

<img style="max-width: 150px;" src="/resources/images/logos/proget-logo.png" alt="ProGet Logo" title="$HtmlEncode($Value)" />

Initial value: Some text that appears on hover

Rendered as: ProGet Logo

Value Renderer Icons

BuildMaster has several CI/CD icon classes that can be used to quickly distinguish and identify links to your branches, builds, or pipelines. When creating your variable value renderer just use any of the following in your renderer HTML:

git

class="ci-icon git"

gitlab

class="ci-icon gitlab"

github

class="ci-icon github"

bitbucket

class="ci-icon bitbucket"

proget

class="ci-icon proget"

otter

class="ci-icon otter"

jenkins

class="ci-icon jenkins"

travis ci

class="ci-icon travis"

circle ci

class="ci-icon circle-ci"

appveyor

class="ci-icon appveyor"

bamboo

class="ci-icon bamboo"

CI Icon Examples

Variable value renderers are useful in terms of CI mainly because they can transform captured important variable values into an image or link to a third-party system.

Examples:
  • ProGet Package
  • GitHub Commit
  • GitLab Branch
<a class="ci-icon proget" 
   href="{pg-host}/feeds/{feedName}/$ApplicationName/$UrlEncode($Value)">
$Value
</a>
<a class="ci-icon github" 
   href="https://github.com/{orgName}/$ApplicationName/commit/$Value">
$Substring($Value, 0, 7)
</a>
<a class="ci-icon gitlab" 
   href="https://gitlab.com/{orgName}/$CustomAppVariable/tree/$Value">
$Substring($Value, 0, 8)
</a>

Visit the Variable Value Renderers documentation for more information.

Is this documentation incorrect or incomplete? Help us by contributing!

This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.

Generated from commit ce197caa on master