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 an attribute in your character sheet, use the {{ $attributeName }} syntax.

To display a multi-line attribute, use the {!! $attributeName !!} syntax.

To test an attribute in a condition, use the @if($attributeName) 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 an attribute to use the Kanka live editing, instead of calling your attribute with {{ $attributeName }}, you can use @liveAttribute('attributeName'). This will inject a span class="live-edit" data-id="xxx" element with the rendered attribute 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 attributes

You can reference ranged attributes by simply writing the attribute name without the range section. For example, if you have an attribute 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. Attribute 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 entity's name
  • $_entity_type The entity's type field, for example Your custom text
  • $_entity_type_name The entity's entity type, for example character
  • $_tags An array of the entity's tag names, sluggified (same as on the entity's body css classes). You can test for a tag with @isset($_tags['auburncrown'])
  • $attributes An array of the entity's attributes

Attributes

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

Abilities

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

[
    {
        "name": "My ability",
        "slug": "myability",
        "type": "Spell"
        "entry": "The following is the ability text",
        "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",
        name: 'My ability',
        slug: 'myability',
        type: 'Spell'
        entry: 'The following is the ability text',
        charges: 4,
        used_charges: null,
        thumb: 'https://kanka-cdn/path-to-thumbnail.jpg',
        link: 'https://app.kanka.io/w/1/abilities/1',
        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)

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 an attribute that doesn't exist without testing @isset($attributeName) @endisset beforehand.

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