Template HTML Syntax

We use the powerful Blade rendering engine behind the scenes. This allows you to use many blade directive like @if(), @empty(), and @for().

TL;DR

To display a property in your character sheet, use the {{ $propertyName }} syntax.

To display a paragraph property, use the {!! $propertyName !!} syntax.

To test a property in a condition, use the @if($propertyName) syntax.

To keep your sanity as the HTML becomes larger, use the {{-- My comment --}} syntax to write down comments.

Conditional statements

The following condition methods are available to use in the character sheet's HTML.

  • @if *
  • @elseif
  • @else
  • @isset
  • @empty
  • @for *
  • @foreach *
  • @switch *
  • @case
  • @break
  • @continue
  • @default

* All conditional blocks needs to be closed with an equivalent @endxxx call, for example @endforeach

Live editing

If you want a property to use the Kanka live editing, instead of calling your property with {{ $propertyName }}, you can use @liveAttribute('propertyName'). This will inject a span class="live-edit" data-id="xxx" element with the rendered property value in it.

Translating character sheets

You can use @i18n("This is my text"). The value in the view is considered the default translation, and will render as This is my text in the character sheet rendering, or as a translation for the user's language if one is defined.

Passing variables to your translation strings is possible using the following syntax: @i18n("He is :title :name", ['title' => 'Mr.', 'name' => 'Bob']), this will render as He is Mr. Bob in the character sheet rendering, or as a translation for the user's language if one is defined, note that for other language translations of an already existing translation string its not necessary to re-declare the variables, they should only be called using : followed by the variable name inside the translation.

Limitations and invalid characters

The default translation strings need to be escaped, meaning you need to write @i18n("Hello \"world\"") or @i18n('Hello \'world\'').

Displaying ranged properties

You can reference ranged properties by simply writing the property name without the range section. For example, if you have a property called level[range:0,10], write {{ $level }} in the HTML field.

Limitations

Since we use the blade engine in the background, we have a few limitations. Property names can't have a space or special characters like '",.-\/@([{#+=, and can't start with a number (basically any invalid variable name in PHP). $dext_érité is valid, but $life points isn't.

Available variables

The following variables are available when rendering a character sheet in a Kanka campaign.

  • $_locale The current language used to display Kanka
  • $_entity_name The entry's name
  • $_entity_type The entry's type field, for example Your custom text
  • $_entity_type_name The entry's category, for example character
  • $_tags An array of the entry's tag names, sluggified (same as on the entry's body css classes). You can test for a tag with @isset($_tags['auburncrown'])
  • $attributes An array of the entry's properties

Properties

An $attributes array represents all the properties of the entry. The array has a key => value representing the property name => the property value (parsed for mentions).

Abilities

An $_abilities array is also available that represents the entry's abilities.

[
    {

        "id": 32,
        "ability_id": 42,
        "name": "My ability",
        "slug": "my-ability",
        "type": "Spell"
        "entry": "<p>The following is the ability text</p>",
        "note": "Custom note with a mention a <href=\"...\">mention</a>",
        "note_raw": "Custom note with a mention [character:123]",
        "charges": 4,
        "used_charges": null,
        "thumb": "<img src="https://kanka-cdn/path-to-thumbnail.jpg" class="ability-thumb" />",
        "link": "<a href="https://app.kanka.io/w/1/entities/1" class="ability-link">My ability</a>",
        "tags": [
            "newtag",
            "magic",
            "campaigns",
        ],
        "parent": {
            "name": "Flamingo",
            "slug": "flamingo",
        }
    },
    // More abilities
]

Character variables

Characters have the following variables also available when rendering a character sheet.

  • $_character_title The character's title
  • $_character_gender The character's gender
  • $_character_pronouns The character's pronouns
  • $_character_age The character's age (This uses the age field, not the calendar age)
  • $_character_appearances An array of the character's appearances. Appearances can be looped with @foreach ($_character_appearances as $name => $text)
  • $_character_traits An array of the character's traits. Traits can be looped with @foreach ($_character_traits as $name => $text)

Javascript variables

When rendering the character sheet on Kanka, the following javascript constants are defined on the page that expose data related to the entry.

The first one is entityData, an object containing data related to the entry. Note that the properties sluggifies property names. A proper API exposing properties as full objects is described later.

{
  "name": "_Arkansas",
  "is_private": true,
  "type": {
    "id": 1,
    "code": "character",
    "custom": ""
  },
  "attributes": {
    "race": "",
    "class": "",
    "subclass": "",
    "alignment": "",
    "level": "1",
    "experience": "0",
    "header-text": "",
    "armor-class": "10 + {DEX_MOD}",
    "layout": "68512a73-49cd-46ec-b8cb-b109f2de3b9f"
  },
  "tags": [{
      "id": 68664,
      "name": "Thalian Gods",
      "slug": "thaliangods",
      "url": "https://app.kanka.io/w/thaelia/entities/886710"
    },
    {
      "id": 204875,
      "name": "Arc I - A friendly fundraiser",
      "slug": "arciafriendlyfundraiser",
      "url": "https://app.kanka.io/w/thaelia/entities/2900236"
    }]

If the current entry is a Character, the following properties are also available in the entityData object.

  "type_field": "Test",
  "gender": "A concept",
  "pronouns": "They/Them",
  "is_dead": true,
  "title": "The Tester",
  "age": "44",
  "traits": [{
      "name": "Goals",
      "entry": "Find purpose in life",
      "section_id": 2,
      "section": "personality"
    },
    {
      "name": "Hair",
      "entry": "Mostly",
      "section_id": 1,
      "section": "appearance"
    }],
  "races": [{
      "id": 37898,
      "name": "Goblin",
      "url": "https://app.kanka.io/w/thaelia/entities/379591"
    },
    {
      "id": 162,
      "name": "Human",
      "url": "https://app.kanka.io/w/thaelia/entities/45494"
    },],
  "families": [{
      "id": 34572,
      "name": "Almunia",
      "url": "https://app.kanka.io/w/thaelia/entities/994223"
    }],
  "location": {
    "id": 255254,
    "name": "Troncone Mines",
    "url": "https://app.kanka.io/w/thaelia/entities/1027340"
  },
}

Properties API

If the need to interact with the full properties of the entry, which also includes creating, updating and deleting properties, the attributeApis object is exposed.

{
    "all": {
        "method": "GET",
        "url": "https://app.kanka.io/w/thaelia/entities/1/attributes/live-api"
    },
    "create": {
        "method": "POST",
        "url": "https://app.kanka.io/w/thaelia/entities/1/attributes/live-api"
    }
}

Abilities API

Lastly, if the need to interact with the abilities of the entry, the abilityApis object details an API that exposes all the abilities as proper objects.

{
    "all": {
        "method": "GET",
        "url": "https://app.kanka.io/w/thaelia/entities/1/entity_abilities/api"
    },
}

Handling Errors

When an error happens while rendering a character sheet, a message will warn the user, along with a hint on what went wrong. The most common cause is trying to display a property that doesn't exist without testing @isset($attributeName) @endisset beforehand.

Another common cause is testing for `$property when the property name is $Property (notice the capital letter). Our rendering engine is case-sensitive.