Powered by OVHcloud

Banner Documentation

Banners are created using HTML and CSS with Handlebars templates. If you are unfamilar with HTML, CSS or Handlebars it's recommended you start be modifing one of the default banners.

For the purposes of this documentation some knowledge of HTML and CSS is expected.

Banner Data

Banners are provided with the data to the right. Data for charts is loaded as needed by the chart helper.

{
  // All server data. This example is of an ArmA 3 server.
  "server": {
    "id": 1000,
    "game_id": "arma3",
    // Server address defaults to ip if a separate address has not been set.
    "address": "play.example.com",
    "ip": "127.0.0.1",
    "port": 2302,
    "port_query": 2303,
    "name": "Server name",
    "maxPlayers": 110,
    "rank": 1,
    "created": "2015-08-17T16:57:28.527Z",
    "last_updated": "2015-08-17T16:57:28.527Z",
    "country": "DE",
    "status": "online",
    "details": {
      "mods": [
        "Arma 3 Zeus",
        "6dbbef82",
        "Arma 3 Karts",
        "3d3c6d",
        "Arma 3 Helicopters",
        "54e1c164",
        "Arma 3 Marksmen",
        "d80931de"
      ],
      "sigNames": [
        "a3"
      ],
      "map": "Altis",
      "mission": "Mission Name"
    },
    "players": [
      {
        "name": "Player One",
        "start": 1419984000000,
        "player_id": 1000
      },
      {
        "name": "Player Two",
        "start": 1419984000000,
        "player_id": 1001
      },
      {
        "name": "Player Three",
        "start": 1419984000000,
        "player_id": 1002
      }
    ]
  },
  
  // Will be true if the requested server was never in our system.
  "serverNotFound": false,
  
  // Will be true if the server was in our system, but was removed.
  // A server would be removed for changing type,
  // being offline for too long, etc.
  "serverRemoved": false,
  
  // Banner options will be available on this object. The name you
  // provide in the banner editor will be
  // used in the options object.
  "options": {
    "foreground": "#EEEEEE",
    "background": "#222222",
    ...
  },
  
  // True when the banner will be rendered to a png, otherwise
  // it will be false.
  "isImage": false,
}

Banner Helpers

All standard Handlebars helpers are available for use in banners. In addition to standard Handlebars helpers we provide the following helpers.

duration

{{duration timestamp}}

Duration is used in the default banners for showing how long a player has been connected to a server. It will return the value using the format hh:mm.

Template Data
{"midnight":"2024-04-27T00:00:00.000Z"}
Template
Midnight UTC was {{duration midnight}} ago.
Preview

lowerCase

{{lowerCase string}}

Does exactly what you would expect. Simply transforms all text to lowercase.

Template
{{lowerCase 'I WILL BECOME LOWERCASE'}}
Preview

chart

{{chart 'Unique and First time players (1M)' 'unique:1M' 'first:1M'}}
{{chart 'Real time player count' 'players:RT'}}

Inserts a chart. The data is automatically fetched and provided to the chart. A valid chart code must be provided to the chart helper. Chart codes follow the format type:period.

The chart helper must be provided with a title and one or more chart types. You may also provide options to the chart render which are detailed below.

Valid types:
players
Player count over the given period.
rank
Rank over the given period.
unique
The number of unique players that were observed over the given period.
first
The number of first time players that were observed over the given period.
time
The about of time players spent on the server over the given period.
Valid time periods:
All charts can use the following time periods.
24H
24 Hours
7D
7 Days
1M
1 Month
3M
3 Months
RT
Real time - Last 100 data points. Only available for player charts.

You may provide options to the chart to further customize it. Options must be provided as valid JSON. For example: we use the 'high' option on player count charts to set the maximum value to the player limit.

All charts are rendered using Chartist line charts.
Show all chart options.
{
  // Options for X-Axis
  "axisX": {
    // The offset of the labels to the chart area
    "offset": 0,
    
    // Position where labels are placed. Can be set to \`start\` or \`end\`
    // where \`start\` is equivalent to left or top on vertical axis
    //  and \`end\` is equivalent to right or bottom on horizontal axis.
    "position": "end",
    
    // Allows you to correct label positioning on this axis by positive or
    // negative x and y offset.
    "labelOffset": {
      x: 0,
      y: 0
    },
    
    // If labels should be shown or not
    "showLabel": false,
    
    // If the axis grid should be drawn or not
    "showGrid": false
  },
  
  // Options for Y-Axis
  "axisY": {
    // The offset of the labels to the chart area
    "offset": 30,
    
    // Position where labels are placed. Can be set to \`start\` or \`end\`
    // where \`start\` is equivalent to left or top on vertical axis
    // and \`end\` is equivalent to right or bottom on horizontal axis.
    "position": "start",
    
    // Allows you to correct label positioning on this axis by positive or
    // negative x and y offset.
    "labelOffset": {
      x: 10,
      y: 5
    },
    
    // If labels should be shown or not
    "showLabel": true,
    
    // If the axis grid should be drawn or not
    "showGrid": true,
    
    // This value specifies the minimum height in pixel of the scale steps
    "scaleMinSpace": 15,
    
    // Use only integer values (whole numbers) for the scale steps
    "onlyInteger": false
  },
  // Specify a fixed width for the chart as
  // a string (i.e. "100px" or "50%")
  "width": undefined,
  
  // Specify a fixed height for the chart as
  // a string (i.e. "100px" or "50%")
  "height": undefined,
  
  // If the line should be drawn or not
  "showLine": true,
  
  // If dots should be drawn or not
  "showPoint": true,
  
  // If the line chart should draw an area
  "showArea": false,
  
  // The base for the area chart that will be used to close
  // the area shape (is normally 0)
  "areaBase": 0,
  
  // Specify if the lines should be smoothed.
  "lineSmooth": true,
  
  // Overriding the natural low of the chart allows you to zoom
  // in or limit the charts lowest displayed value
  "low": undefined,
  
  // Overriding the natural high of the chart allows you to zoom
  // in or limit the charts highest displayed value
  "high": undefined,
  
  // Padding of the chart drawing area to the container element and labels
  // as a number or padding object {top: 5, right: 5, bottom: 5, left: 5}
  "chartPadding": 5,
  
  // When set to true, the last grid line on the x-axis is not drawn and
  // the chart elements will expand to the full available width
  // of the chart. For the last label to be drawn correctly
  // you might need to add chart padding.
  "fullWidth": false,
  
  // If true the whole data is reversed including labels, the series order
  // as well as the whole series data arrays.
  "reverseData": false
}
Template Data
{"chartData":{"players:24H":[[1,0],[2,5],[3,0]]}}
Template
{{chart 'Simple chart' 'players:24H'}}
{{#chart 'Chart with options' 'players:24H'}}
{
  "low": 0,
  "high": 10,
  "height": 50
}
{{/chart}}
Preview

match

{{#match 'haystack' 'needle'}}contents{{/match}}

Match will only show its contents when it finds a match. See example on the right.

Template
{{#match 'haystack' 'hay'}}I'll show up.{{/match}}
{{#match 'foo' 'bar'}}I won't show up.{{/match}}
Preview

colorBlend

{{colorBlend float:amount string:color string:color}}
{{colorBlend float:amount string:color}}

When two colors are provided it will blend them together. When one color is provided it will either lighten or darken the color based on the amount given.

Template
<div style='background: {{colorBlend 0.5 '#000000' '#FFFFFF'}}; padding: 5px;'>Blended black and white.</div>
<div style='background: {{colorBlend 0.2 '#000000'}}; padding: 5px;'>Black lightened by 20%.</div>
<div style='background: {{colorBlend -0.2 '#FFFFFF'}}; padding: 5px; color: #000;'>White darkend by 20%.</div>
Preview

serverFeatures

{{#serverFeatures}}{{name}}: {{value}}{{/serverFeatures}}

Games very in what details they provide via their query protocol. Internally these are available under server.details. The serverFeatures helper abstracts this away and provides a suitable name for display along with a value that has any necessary formatting applied.

If you want raw access to the values used you can find them at server.details['detail'].

Template Data
{"server":{"game_id":"arma3","details":{"map":"Altis","mission":"Example mission"}}}
Template
Server features:<br />
{{#serverFeatures}}
  <strong>{{name}}</strong>: {{value}}<br />
{{/serverFeatures}}
Preview

flag

{{flag countryVariable}}

Embeds a 16x11px image of a flag. The countryVariableshould be in the ISO 3166-1 alpha-2 format. The country code for servers is in the appropriate format. To embed a flag for a server use {{flag server.country}}.

Flag images are from FAMFAMFAM.

Template Data
{"countryVariable":"US"}
Template
{{flag countryVariable}}<br />
{{flag "DK"}}
Preview