Templates

Overview

A Template is a Resource you can define in order to create a re-usable chunk of UI with custom properties called 'slots'. Let's look at a simple example:

resources:
  play_pause_button:
    type: template

    slots:
      is_paused: false
      play_icon: spr_play_icon
      pause_icon: spr_pause_icon

      // handler for when pause state changes
      on_paused_changed: null

    template:
      type: button
      padding: 5
      content:
        type: image
        // choose the icon based on the $is_paused slot value
        sprite: $is_paused then $pause_icon else $play_icon

      // call the change handler with the opposite of the current pause value
      on_click: $on_paused_changed(!is_paused)

Here we're defining a new template with the name: play_pause_button.

The slots section then defines the custom properties we want to add and their default values.

The template section then defines the YUI element to use elsewhere, except that now in addition to the normal data binding options, we can also use the $ YuiScript operator to bind to slot values. Note that you can use $ within a binding in a nested element, such as in the example above when defining the sprite value for the image element used in the button's content property.

So where do those incoming slot values come from? Let's take a look at how we use a template:

type: panel
layout: horizontal
spacing: 10
elements:
  - "Play/Pause"
  - type: play_pause_button
    is_paused: @is_music_paused
    on_paused_changed: @@ paused => @is_music_paused = paused

Wow, that looks like just like a built-in element! The slots we defined in the template definition get set just like regular properties of a built-in element.

You can even override the properties of the root element of the template. In the above example definition, the padding property of the button in the template is set to 5, but we could stomp that with a new value when using the template:

  - type: play_pause_button
    padding: 10
    is_paused: @is_music_paused
    on_paused_changed: @@ paused => @is_music_paused = paused

This also works for properties on the template root element that aren't explicitly defined in the template definition. For example, you could set the border_color property, even though that isn't explicitly set in the template slots definition. Basically, any properties that don't match one of the slots will get forwarded to the root element of the template. NOTE: If that property doesn't exist on the root element type, it will get ignored!

That's really all there is to templates: define your slots, then use $ to access slot values in the template's content. Very simple, but incredibly powerful when put to good use.

Performance

You may be wondering, how does using a template affect performance in GameMaker? The good news is that there is no performance cost at runtime. When YUI loads a screen and finds a template, it essentially inserts the template content directly into the screen at that point, and then inserts the slot values into all the places they are used. The result is the same as if you had simply written out all the YAML for the template and slot values yourself in each place.

Advanced Usage

Item Templates

TODO

Custom Events

TODO