How To Add New Badge

This describes the steps for adding a new Badge. Also see Badge Expectations (Attributes)

It helps to know how the badge fits into the Constellation of Badges.

Generally, there are role-based Badges and Progress Chip badges. The main distinction is a Role-based badge depends on performing certain tasks and a Progress Chip badge depends on repeating a certain task a number of times.

This starts out describing a Progress Chip badge (because I haven't done one yet and when I get it working, I won't remember how I did it, so I'm writing it down).

To orient, check out the BadgeOS Structure page. This takes the perspective of someone sitting at the WordPress BadgeOS menu.

Checklist

There is also a Checklist

Steps

  1. Decide if we're adding a new Role-based badge, or a Themed Badge. The Tiny Door Progress Chip will be Themed.
  2. Decide if an existing Achievement Type will work, or if we need a new Achievement Type. Trying out adding a New Achievement Type of "Theme (Close-ended)"
  3. Sub-Achievements are what most often show up as Badges and Progress Chips. These are the "steps" that build up to a Badge.
  4. For a Themed Badge, You would create a new record under the BadgeOS -> Themata (Closed) or Themata (Open).
  5. Complete the Form for the new Badge. This shell is given, and then we'll add the steps.
    • Name (checking the perma-link is OK too)
    • Type up a description, with references to the site, or how it is connected, or whatever gives it remarkability.
    • Create a Badge Image and give it an appropriate color.
    • This badge is earned by Completing Steps (select from the pull-down).
    • Give it a congratulatory text.
    • "Hidden?" field is set to "Show to User"
    • Save this for now. We need to make sure we have a sub-achievement we can refer to for the Steps.
  6. For a Closed Theme, each "step" has a unique identity that we are able to map one-to-one with a location or other feature in the real world. (For Open Themes, the count just keeps increasing to obtain higher levels of badge, the progress isn't a percentage of the goal, but just a number of times the achievement has been performed. In both cases, we just need a single sub-achievement time. Let's create that now.
  7. Navigate to BadgeOS -> sub-achievements and create a new record. The fields to be completed are:
    • Name (checking the perma-link is OK too) Our example here is "Visit Tiny Door"
    • Description not required.
    • Badge image not required.
    • "Earned By" is set to "Admin-awarded Only" (actually, this is an automated call from the server.)
    • "Maximum Earnings": -1 (limit is imposed by the system awarding the badge)
  8. Save this and return to the Badge instance. We'll add steps based on the sub-achievement.
  9. For each of the "steps" in this Theme — for each Tiny Door, as an example — Add a "Required Step" providing these fields:
    • Specific Achievement of Type …
    • Sub-achievement
    • The specific sub-achievement just entered above (Visit Tiny Door, as an example)
    • 1 times
    • Then, the field that identifies this step to the rest of the world: "Label" should correspond with the step:
      • Be unique across all steps within this Badge.
      • Be readable by humans
      • Be easy to match up with what is in the Real World. "TD #1" is too terse. "Tiny Door #1 - Krog Tunnel" is great.

Technical Notes

  • The Label is what we use as humans to match the arrival at a location with the step that should be checked off.
  • It's also what the human would use to assign the Sub Achievement's unique Primary Key to the API call that the system that tracks the arrivals will call.
  • Bundling these steps under a Badge allows reporting progress toward that badge.
  • Sub-Achievements have a post_name that hyphenates the Title and look more like a Badge in that they are explicitly named as requirements for a given badge.
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License