Skip to content

[Levelbuilder] Creating a Callout

Jump to bottom
Ken Akiha edited this page Dec 13, 2023 · 15 revisions

Creating a Callout

A callout is a pop-up that points to a specific area on the screen. These are used to point things out to the user, which might otherwise be difficult to explain just with text.

Callouts can be triggered by events, or when the level loads. They can be used anywhere there's a reliable CSS reference, but there's typically two different places where callouts occur: on blocks in the toolbox, and code in the workspace.

Table of Contents

Callouts for Dance Party (and other updated Blockly labs)

Adding a new callout to the TOOLBOX

Step 1: Identifying the block you want to add the callout to

I want to add a callout to the toolbox in this level in Dance Party. I want the call out to appear under the first make a new cat at center block in the toolbox.

image

Open the Developers Tools and find the Inspector tool.

image

Then click on the block you want to attach the callout to. In this case we want to add it to a specific block that exists in the Toolbox.

image

When you select the block, it may select one of the "inner" HTML elements. In the inspector, find the <g> HTML tag that is the container for what you selected and check if it has a data-id tag. In the screenshot above, it has data-id="1". Sometimes the data-id is a simple number, like "data-id = 1", or sometimes it is a long string of random numbers and letters generated automatically.

(Optional): How to manually set a block id if one isn't there or a really weird long id was automatically generated

If the block in question already has a short clear data-id (such as “1”), go onto the next step. If it doesn’t have a data-id or has a long string of letters and numbers, you can do the following to create a simpler data-id:

  • Go to the level edit page.
  • Expand the Toolbox or Start blocks section and find the block XML for the block you want to add a callout to.
  • Edit the <block> tag to add an id property. Ensure that the id isn’t used by any other toolbox or start block. The id can be letters and/or numbers.

image

Important: When editing the block XML, you are setting the id property. And then, when the level loads, it becomes a data-id property. These are essentially the same thing, but the name changes depending on where you view or edit them. In the block XML editor: use id. When inspecting the webpage and making the actual callout (see below): use data-id.

Since we're attaching a callout to a block within the toolbox (and not, for example, in the workspace), we also want to identify the class of the element that contains the toolbox blocks on the left side. In this case, it's blocklyFlyout:

image

This means the element we want to attach a callout to can be found using the CSS identifier .blocklyFlyout [data-id="1"]. In other words: look inside the element with a class of blocklyFlyout for the element with a data-id of "1". Remember this for later!

Step 2: Creating the Callout in the Levelbuilder Editor

I have to go to the levelbuilder edit page and find the callout section and click Add a Callout

image

This will expand the screen with boxes to type into

image

Fill out the fields you'll need. This can be confusing at first, here's what everything does:

  • ElementID: This is the ID for the block itself. This is what we identified earlier! For adding a callout to a block in the toolbox, always use the .blocklyFlyout class in front of the [data-id]. It will usually look like this:

    • .blocklyFlyout [data-id="element ID name or number after data-id"]
    • Examples:
      • .blocklyFlyout [data-id="1"]
      • .blocklyFlyout [data-id=";H],)@7Aw*-dzna)%X;Z"]
        • Note: This type of ID gets generated automatically when an ID isn't manually set by the levelbuilder. You can follow the optional steps above to manually set an easier-to-read id instead of using a weird one like this.

  • Localization Key: Provide a unique value here. These keys are used for reference when the callout is being translated. If you reuse a key then it would reference the original translation.

  • Callout text: This is the text you want to appear in the callout.

  • Qtip on Callout: Dropdown with options that refer to where the tip of the callout should be positioned (e.g. "top left" would put the tip on the top left of the callout)

  • Qtip Points to: Refers to the position of the element the callout should point to (e.g. "bottom right" would make the callout point to the bottom right of the block)

  • Show When: Put the name of the link you'd want to use for trigger the callout here. It can be whatever you want it to be, but no spaces - use dashes or underscores instead. You'll reference it later in the instructions.

  • X and Y Dist: Use these textboxes to move the callout by different pixel values.

  • Classes: These are CSS classes that style the tooltip. The main one used is no-tip, which gets rid of the qtip.

  • Reappear: Checking this box allows the callout to appear again when a user clicks on the link in the instructions or every time they visit the level

  • Palette Category: The name of the palette category you want this callout to appear in.

You'll see a JSON output when you finish filling these fields in. Don't worry about that, you don't have to touch it. Here's a completed callout form for blocks in the workspace:

image

Adding a new callout to the WORKSPACE

Follow the same steps as above BUT in the Element ID field replace .blocklyFlyout with .blocklySvg. For example:

.blocklySvg [data-id="1"].

image

Callouts for older versions of Blockly

Older versions of Blockly have a different CSS class for the toolbox, so if you look at older levels, you may see a different class used instead of .blocklyFlyout. You can always tell which version to use by using the Inspector tricl and identifying the class of the SVG element that contains the toolbox.

Callouts for Blocks in the Toolbox (Droplet - Game Lab / App Lab)

image

  1. Find the ID of the element you want to attach your callout to. You'll need this later.

You can find this by opening up your browser's developer console and inspecting the target block. This should bring up the html for that block, including its ID, like in the gif below:

image

  1. In the level editor, click on the "Add a callout" button.

image

A form like this should popup:

image

  1. Fill out the fields you'll need. This can be confusing at first, here's what everything does:

  • ElementID: This is the ID for the block itself in the following format (replace the stuff in red):

    image

  • Localization Key: Provide a unique value here. These keys are used for reference when the callout is being translated. If you reuse a key then it would reference the original translation.

  • Callout text: This is the text you want to appear in the callout.

  • Qtip on Callout: Dropdown with options that refer to where the tip of the callout should be positioned (e.g. "top left" would put the tip on the top left of the callout)

  • Qtip Points to: Refers to the position of the element the callout should point to (e.g. "bottom right" would make the callout point to the bottom right of the block)

  • Show When: Put the name of the link you'd want to use for trigger the callout here. It can be whatever you want it to be, but no spaces - use dashes or underscores instead. You'll reference it later in the instructions.

  • X and Y Dist: Use these textboxes to move the callout by different pixel values.

  • Classes : These are CSS classes that style the tooltip. The main one used is no-tip, which gets rid of the qtip.

  • Reappear: Checking this box allows the callout to appear again when a user clicks on the link in the instructions.

  • Palette Category: The name of the palette category you want this callout to appear in.

You'll see a JSON output when you finish filling these fields in. Don't worry about that, you don't have to touch it.

Here's a completed callout form for blocks in the workspace:

image

  1. Update the markdown instructions to include a link that triggers the callout. Format (replace the stuff in red):

[<link text>](#triggercallout=<"show when" field>)

  1. Be sure to test your changes!

Congrats, you've created a callout for blocks in the toolbox!

Callouts for Code in the Workspace (Droplet - Game Lab / App Lab)

image

  1. In the level editor, click on the "Add a callout" button.

image

A form like this should popup:

image

  1. Fill out the fields you'll need. This can be confusing at first, here's what everything does:

Fields that Affect The Callout Itself. These are the most important

  • ElementID: Leave this blank! You only use this field when creating a callout on an existing block on the page (like in the toolbox). For callouts in the code, you use a different process

  • Localization Key: Provide a unique value here. These keys are used for reference when the callout is being translated. If you reuse a key then it would reference the original translation.

    • STANDARDIZATION TIP: [Curriculum] U[Unit #]L[Lesson #].[Level Number] - [The link text that you use in instructions]
    • Example: CSD U3L12.2 - if_statement (and then later, the link to the callout will be #triggercallout=if_statement)

  • Callout text: This is the text you want to appear in the callout.

  • Show When: Put the name of the link you'd want to use for trigger the callout here. It can be whatever you want it to be but no spaces - use dashes or underscores instead. You'll reference it later in the instructions.

    • In the instructions, this will show up as part of the link: [Show Me Where](#triggercallout={{This_Text_Here}})

  • Reappear: Checking this box allows the callout to appear again when a user clicks on the link in the instructions.

Fields that Affect the Position of the Callout

  • Qtip on Callout: Dropdown with options that refer to where the tip of the callout should be positioned (e.g. "top left" would put the tip on the top left of the callout)

  • Qtip Points to: Refers to the position of the element the callout should point to (e.g. "bottom right" would make the callout point to the bottom right of the block)

  • X and Y Dist: Use these textboxes to move the callout by different pixel values.

  • Classes : These are CSS classes that style the tooltip. The main one used is no-tip, which gets rid of the qtip.

  • Palette Category: The name of the palette category you want this callout to appear in.

  1. This next step takes place in the actual code blob that is being automatically generated by the text inputs - you need to manually edit the JSON code to look for the custom text string in the code.
  • Find the part of the code that looks like:
"codeStudio": {
  //SOME STUFF, like canReappear and dropletPaletteCategory
}
  • In that SOME STUFF section, add a comma to the end of the previous last line and add new line: codeString: "{{the literal string of code you want it to find}}"

This step is tricky - here's a before-and-after of how this change could look (there are also examples at the bottom of the page).

Before:

"codeStudio": {
    "canReappear": true,
    "dropletPaletteCategory": ""
   },

After: (notice the extra comma at the end of the 2nd line in "codeStudio" that wasn't there before)

   "codeStudio": {
    "canReappear": true,
    "dropletPaletteCategory": "",
     "codeString": "//Add your variable update here"
   },

Note: If you make any changes to the fields above the code area after entering the codeString the value will be erased and you will need to replicate the steps above.

  1. Update the markdown instructions to include a link that triggers the callout. Format (replace the stuff in red):

[<link text>](#triggercallout=<"show when" field>)

  1. Be sure to test your changes!

Congrats, you've created a callout that points to code in the workspace!

Examples of Completed Callouts (Droplet - Game Lab / App Lab)

[
 {
  "localization_key": "U6L6.4 - Counter",
  "callout_text": "Increase your variable here",
  "element_id": "",
  "on": "increase_variable",
  "qtip_config": {
   "codeStudio": {
    "canReappear": true,
    "dropletPaletteCategory": "",
     "codeString": "//Add your variable update here"
   },
   "style": {
    "classes": ""
   },
   "position": {
    "my": "right center",
    "at": "left center",
    "adjust": {
     "x": 0,
     "y": 0
    }
   }
  }
 },
  {
  "localization_key": "U6L6.4 - If",
  "callout_text": "Add your if-statement here",
  "element_id": "",
  "on": "if-statement",
  "qtip_config": {
   "codeStudio": {
    "canReappear": true,
    "dropletPaletteCategory": "",
     "codeString": "//Add your if-statement here"
   },
   "style": {
    "classes": ""
   },
   "position": {
    "my": "right center",
    "at": "left center",
    "adjust": {
     "x": 0,
     "y": 0
    }
   }
  }
 }
]

Instructions:

# Do This

- Add code inside your event that increases the `size` variable by 10 each time a button is pressed ( [Show me where](#triggercallout=increase_variable) )
- Add an if-statement that checks when the heart has reached a size of at least 300 pixels ( [Show me where](#triggercallout=if-statement) )
- Inside the if-statement: Have the buzzer make a noise to let the user know they're reached their goal

Template for Callouts in Code Area (Droplet - Game Lab / App Lab)

You still need to press the "Add Callout" button, but then you can copy-and-paste this into the JSON blob and edit it directly

[
 {
  "localization_key": "CSD U#L#.LEVEL - {{SAME THING IN 'on' PART OF JSON}}",
  "callout_text": "{{WHAT APPEARS IN THE CALLOUT}}",
  "element_id": "",
  "on": "{{GOES INSIDE LINK - [link](#triggercallout=THISPART)",
  "qtip_config": {
   "codeStudio": {
    "canReappear": true,
    "dropletPaletteCategory": "",
     "codeString": "{{LITERAL CODE STRING TO LOOK FOR IN THE CODE}}"
   },
   "style": {
    "classes": ""
   },
   "position": {
    "my": "right center",
    "at": "left center",
    "adjust": {
     "x": 0,
     "y": 0
    }
   }
  }
 }
]

For Levelbuilders

For Developers

Contact Rollups

Clone this wiki locally