Content System Interactive Elements - 5-Frame-Studios/Guidebook-docs GitHub Wiki

Interactive Elements

Interactive elements make your guidebook pages dynamic and engaging. This guide covers buttons and form fields in detail.

Important Page Type Constraint

You cannot mix buttons and fields on the same page. Pages must be exactly one of these types:

  • Content Page: Has buttons (and optional body content) for navigation and actions
  • Form Page: Has fields for data collection only
  • Dialog Page: Has exactly 2 buttons (and body content) for confirmation dialogs

Forms automatically submit when navigating away - no submit button is needed or allowed.

Buttons

Buttons allow players to trigger actions, navigate between pages, and interact with your guidebook.

Basic Button

buttons:
  - text: "Click Me"
    action: "my_action"

Button with Icon

buttons:
  - text: "Next Page"
    action: "navigateTo:next"
    icon: "textures/ui/arrow_right"

Button Properties

text (required)

The display text for the button. Supports property placeholders.

- text: "Hello {{c:player_name}}"
- text: "Level: {{p:player_level|1}}"
- text: "Server: {{w:server_name|Default}}"

action (required)

The action(s) to perform when clicked. Can be a string, object, or array.

icon (optional)

Texture path for the button icon.

Common icon paths:

  • "textures/ui/arrow_right" - Right arrow
  • "textures/ui/arrow_left" - Left arrow
  • "textures/ui/home" - Home icon
  • "textures/items/compass_item" - Compass
  • "textures/items/book_writable" - Book
  • "textures/items/diamond" - Diamond
  • "textures/blocks/crafting_table_top" - Crafting table

Button Actions

Navigation Actions

Navigate to Page

action: "navigateTo:page_id"

Examples:

- text: "Tutorial"
  action: "navigateTo:tutorial"
- text: "Advanced Guide"
  action: "navigateTo:tutorial/advanced"

Go Back

action: "back"

Returns to the previous page in the navigation stack.

Close Guidebook

action: "close"

Closes the guidebook completely.

Search

action: "search"

Triggers the built-in search functionality (requires a search field on the page).

Property Actions

Set Single Property

action:
  action: "set_properties"
  properties:
    - property: { name: "tutorial_completed", scope: "player" }
      value: "true"

Set Multiple Properties

action:
  action: "set_properties"
  properties:
    - property: { name: "tutorial_completed", scope: "player" }
      value: "true"
    - property: { name: "completion_date", scope: "player" }
      value: "{{parser:current_date}}"
    - property: { name: "tutorial_score", scope: "player" }
      value: 100

Custom Actions

Single Custom Action

action: "give_reward"

Multiple Actions

Execute multiple actions in sequence:

action:
  - "give_reward"
  - "navigateTo:congratulations"
  - action: "set_properties"
    properties:
      - property: { name: "reward_given", scope: "player" }
        value: "true"

Complex Action Examples

Conditional Navigation

- text: "Continue"
  action:
    - action: "set_properties"
      properties:
        - property: { name: "current_step", scope: "player" }
          value: 2
    - "navigateTo:step2"

Save and Navigate

- text: "Save & Continue"
  action:
    - action: "set_properties" 
      properties:
        - property: { name: "settings_saved", scope: "player" }
          value: "true"
        - property: { name: "save_timestamp", scope: "player" }
          value: "{{parser:current_time}}"
    - "save_player_data"
    - "navigateTo:next_section"

Form Fields

Form fields collect input from players and store the data in properties.

Text Field

Allows free-form text input.

fields:
  - type: "textField"
    label: "Enter your name:"
    property: { name: "player_name", scope: "player" }
    placeholder: "Type your name here..."
    default: "{{c:player_name}}"
    tooltip: "This will be your display name"

Properties

  • placeholder - Text shown when field is empty
  • default - Default value (supports placeholders)
  • tooltip - Help text shown on hover

Examples

# Basic text input
- type: "textField"
  label: "Favorite color:"
  property: { name: "favorite_color", scope: "player" }
  placeholder: "e.g., Blue"

# Text with dynamic default
- type: "textField"
  label: "Display name:"
  property: { name: "display_name", scope: "player" }
  default: "{{c:player_name}}"
  tooltip: "Leave blank to use your Minecraft name"

# Multi-purpose text field
- type: "textField"
  label: "Notes for {{c:player_name}}:"
  property: { name: "personal_notes", scope: "player" }
  placeholder: "Enter your notes here..."
  tooltip: "These notes are private and only visible to you"

Toggle Switch

Boolean on/off switch.

fields:
  - type: "toggle"
    label: "Enable notifications"
    property: { name: "notifications_enabled", scope: "player" }
    default: true
    tooltip: "Receive server notifications"

Advanced Toggle with Property Setting

- type: "toggle"
  label: "Join beta program"
  property: { name: "beta_participant", scope: "player" }
  default: false
  set_properties:
    - property: { name: "beta_join_date", scope: "player" }
      value: "{{parser:current_date}}"
    - property: { name: "beta_version", scope: "world" }
      value: "{{parser:beta_version}}"
  tooltip: "Get early access to new features"

The set_properties array defines additional properties to set when the toggle is activated (turned on). The toggle property itself is automatically set to false after the additional properties are set.

Examples

# Simple toggle
- type: "toggle"
  label: "Enable sound effects"
  property: { name: "sound_enabled", scope: "player" }
  default: true

# Toggle with side effects
- type: "toggle"
  label: "Reset progress"
  property: { name: "reset_triggered", scope: "player" }
  default: false
  set_properties:
    - property: { name: "level", scope: "player" }
      value: 1
    - property: { name: "experience", scope: "player" }
      value: 0
    - property: { name: "reset_date", scope: "player" }
      value: "{{parser:current_time}}"
  tooltip: "WARNING: This will reset all your progress!"

Slider

Numeric input within a specified range.

fields:
  - type: "slider"
    label: "Volume level"
    property: { name: "volume", scope: "player" }
    min: 0
    max: 100
    step: 10
    default: 50
    tooltip: "Adjust the volume level"

Properties

  • min (required) - Minimum value
  • max (required) - Maximum value
  • step (required) - Step size for increments
  • default - Default value
  • tooltip - Help text

Examples

# Volume slider
- type: "slider"
  label: "Master Volume"
  property: { name: "master_volume", scope: "player" }
  min: 0
  max: 100
  step: 5
  default: 75

# Difficulty slider
- type: "slider"
  label: "Difficulty Level"
  property: { name: "difficulty", scope: "player" }
  min: 1
  max: 10
  step: 1
  default: 5
  tooltip: "1 = Easy, 10 = Nightmare"

# Precision slider
- type: "slider"
  label: "Sensitivity"
  property: { name: "mouse_sensitivity", scope: "player" }
  min: 0.1
  max: 2.0
  step: 0.1
  default: 1.0

Dropdown

Select from a list of predefined options.

fields:
  - type: "dropdown"
    label: "Choose your class:"
    property: { name: "player_class", scope: "player" }
    options: ["Warrior", "Mage", "Archer", "Rogue"]
    default: 0
    tooltip: "This affects your starting equipment"

Properties

  • options (required) - Array of option strings
  • default - Index of default option (0-based)
  • tooltip - Help text

Options support property placeholders:

options: 
  - "{{w:class_warrior|Warrior}}"
  - "{{w:class_mage|Mage}}"
  - "{{w:class_archer|Archer}}"

Examples

# Language selection
- type: "dropdown"
  label: "Preferred Language"
  property: { name: "language", scope: "player" }
  options: ["English", "Spanish", "French", "German", "Japanese"]
  default: 0

# Game mode selection
- type: "dropdown"
  label: "Game Mode"
  property: { name: "preferred_gamemode", scope: "player" }
  options: ["Survival", "Creative", "Adventure", "Spectator"]
  default: 0
  tooltip: "Your preferred game mode for events"

# Dynamic options
- type: "dropdown"
  label: "Select Team"
  property: { name: "team_selection", scope: "player" }
  options: 
    - "Team {{w:team1_name|Red}}"
    - "Team {{w:team2_name|Blue}}"
    - "Team {{w:team3_name|Green}}"
  default: 0

Form Submission

on_submit_action

Specify what happens when a form is submitted:

# In page frontmatter
on_submit_action: "save_settings"

fields:
  - type: "textField"
    label: "Name:"
    property: { name: "name", scope: "player" }
  - type: "slider"
    label: "Age:"
    property: { name: "age", scope: "player" }
    min: 13
    max: 100
    step: 1

buttons:
  - text: "Save"
    action: "back"  # This will trigger form submission

Built-in Submit Actions

Search

on_submit_action: "search"

fields:
  - type: "textField"
    label: "Search for:"
    property: { name: "search_term", scope: "player" }
    placeholder: "Enter search term..."

buttons:
  - text: "Search"
    action: "search"

Custom Submit Actions

Register custom submit handlers in TypeScript:

guidebook.registerAction("save_settings", (player, formValues) => {
  if (formValues) {
    const [name, age, preferences] = formValues;
    console.log(`Saving: ${name}, ${age}, ${preferences}`);
    
    // Save to database or perform other actions
    savePlayerData(player.id, { name, age, preferences });
    
    player.sendMessage("§aSettings saved successfully!");
  }
});

Complete Interactive Examples

Form Page Example

---
title: "Player Configuration"
on_submit_action: "save_player_config"

fields:
  - type: "textField"
    label: "Display Name:"
    property: { name: "display_name", scope: "player" }
    placeholder: "Enter your display name..."
    default: "{{c:player_name}}"
    tooltip: "This name will be shown to other players"
    
  - type: "dropdown"
    label: "Preferred Language:"
    property: { name: "language", scope: "player" }
    options: ["English", "Spanish", "French", "German"]
    default: 0
    tooltip: "Choose your preferred language"
    
  - type: "slider"
    label: "UI Scale:"
    property: { name: "ui_scale", scope: "player" }
    min: 50
    max: 150
    step: 10
    default: 100
    tooltip: "Adjust the UI size (percentage)"
    
  - type: "toggle"
    label: "Enable Notifications"
    property: { name: "notifications", scope: "player" }
    default: true
    tooltip: "Receive server notifications and updates"
    
  - type: "toggle"
    label: "Reset All Settings"
    property: { name: "reset_settings", scope: "player" }
    default: false
    set_properties:
      - property: { name: "display_name", scope: "player" }
        value: "{{c:player_name}}"
      - property: { name: "language", scope: "player" }
        value: 0
      - property: { name: "ui_scale", scope: "player" }
        value: 100
      - property: { name: "notifications", scope: "player" }
        value: true
    tooltip: "WARNING: This will reset all your settings to defaults!"
---

**Player Configuration**

Configure your personal settings below:

**Current Settings:**
Display Name: {{p:display_name|{{c:player_name}}}}
Language: {{p:language|English}}
UI Scale: {{p:ui_scale|100}}%
Notifications: {{p:notifications|Enabled}}

Fill out the form above. Your configuration will be saved automatically when you navigate away from this page.

Content Page Example

---
title: "Configuration Menu"
buttons:
  - text: "Edit Configuration"
    action: "navigateTo:player-config"
    icon: "textures/ui/check"
  - text: "Reset to Defaults"
    action: "navigateTo:config-reset-confirm"
    icon: "textures/items/barrier"
  - text: "Back to Main"
    action: "navigateTo:main"
    icon: "textures/ui/cancel"
---

**Configuration Menu**

Choose an option below:

**Current Settings Summary:**
Display Name: {{p:display_name|{{c:player_name}}}}
Language: {{p:language|English}}
UI Scale: {{p:ui_scale|100}}%
Notifications: {{p:notifications|Enabled}}

Dialog Page Example

---
title: "Reset Configuration"
buttons:
  - text: "Yes, Reset All"
    action: "reset_player_config"
  - text: "Cancel"
    action: "back"
---

**Are you sure you want to reset all configuration settings to their default values?**

This action cannot be undone. All your customized settings will be lost.

Best Practices

Button Design

  • Use clear, action-oriented text
  • Provide appropriate icons for better UX
  • Group related actions together
  • Always provide a way to go back or cancel

Form Design

  • Use descriptive labels
  • Provide helpful placeholder text
  • Include tooltips for complex fields
  • Set sensible default values
  • Use appropriate field types for the data

Property Management

  • Use consistent naming conventions
  • Choose appropriate scopes (player vs world)
  • Provide meaningful default values
  • Consider using property placeholders in defaults

User Experience

  • Keep forms concise and focused
  • Group related fields together
  • Provide immediate feedback after actions
  • Use progressive disclosure for complex workflows