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.
* 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)
Javascript variables
When rendering the character sheet on Kanka, the following javascript constants are defined on the page that expose data related to the entity.
The first one is entityData, an object containing data related to the entity. Note that the attributes sluggifies attribute names. A proper API exposing attributes 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 entity 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" }, }
Attributes API
If the need to interact with the full attributes of the entity, which also includes creating, updating and deleting attributes, 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 entity, 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 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.