Registering Items

To enable a plugin to provide metrics, the metrics must first be registered with the MoBro Data Service.
This applies to all available item types.

Available Items

The following MoBroItems can be registered with the service:

• Metric - Represents a single data value provided by a plugin.
• MetricType - Specifies the type of a metric, including its value type and applicable units.
• Category - Categorizes items of a similar type.
• Group - Groups items within a shared context.
• Resource - Represents a file-based item (e.g., an icon or image).
• Action - A triggerable item that executes a certain action.

Creating and Registering Items

The easiest way to create any item is by using the MoBroItem builder available in the SDK.
Once created, items can be registered to MoBro through the IMoBroService interface.

Example: Creating and Registering a Metric

// Create a new metric
var metric = MoBroItem
  .CreateMetric() // Define the type of item: Metric
  .WithId("first_metric") // Assign a unique item ID
  .WithLabel("Metric", "My first metric") // Set the label and an optional description
  .OfType(CoreMetricType.Text) // Use the core 'Text' metric type
  .OfCategory(CoreCategory.Miscellaneous) // Use the 'Miscellaneous' category
  .OfNoGroup() // Specify that this metric does not belong to a group
  .Build();

// Register the metric to MoBro
_mobro.Register(metric);

Example: Creating and Registering an Action

// Handler that will be called whenver the action is invoked
void ActionHandler(IMoBroSettings settings)
{
  var value = settings.GetValue<string>("value", ""); // Retrieve the value of the custom setting
  _mobro.UpdateMetricValue("first_metric", value);
}

// Create a new action
var action = MoBroItem
  .CreateAction() // Define the type of item: Action
  .WithId("action_id")  // Assign a unique item ID
  .WithLabel("Set the metric value") // Set the label and an optional description
  .OfNoCategory() // Assign to the default 'Miscellaneous' category
  .OfNoGroup() // Specify that this action does not belong to a group
  .WithMetric("first_metric") // Specify the metric that represents the value that is adjusted by this action
  .WithHandler(ActionHandler) // Specify the handler to be called whenever this action is invoked
  .WithSetting(sb => sb // Register a custom 'string' type setting for the action
    .WithName("value")
    .WithLabel("New Value to set")
    .AsRequired()
    .OfTypeString()
    .Build()
  )
  .Build();

// Register the action to MoBro
_mobro.Register(metric);

---

Important Notes

• When registering a metric, the metric item passed to MoBro includes only the metadata, not the actual data value.
  This allows MoBro to recognize the metrics provided by a plugin even if:

  • A value is currently unavailable.
  • Value retrieval requires additional processing time.

• The actual value of a metric can be updated separately. Refer to Updating Metric Values for more details.

• Each item should be registered only once. For more about core types and categories, see:
  Reference: MetricType and Reference: Category.

---

Referencing and Using Custom Items

In addition to core categories and metric types, custom items can also be created and registered.
When using custom items, the registration order is critical because an IMoBroItem must be registered before it can be referenced by other items.

Example: Registering Custom Items

// Create a custom category
var financeCategory = MoBroItem
  .CreateCategory() // Type of item: Category
  .WithId("finance_category") // Unique category ID
  .WithLabel("Finances") // Category label
  .Build();

// Create a custom metric type for coins (e.g., 1 Gold = 100 Silver Coins)
var coinType = MoBroItem
  .CreateMetricType()
  .WithId("coin_type") // Unique metric type ID
  .WithLabel("Coins") // Type label
  .OfValueType(MetricValueType.Numeric) // Value type: Numeric
  .WithBaseUnit(baseUnit => baseUnit // Define the base unit
    .WithLabel("Gold") // Base unit label
    .WithAbbreviation("G") // Base unit abbreviation
    .Build())
  .WithDerivedUnit(derivedUnit => derivedUnit // Add a derived unit
    .WithConversionFormula("x * 100", "x / 100") // Conversion formulas
    .WithLabel("Silver") // Derived unit label
    .WithAbbreviation("S") // Derived unit abbreviation
    .Build())
  .Build();

// Create a new metric
var metric = MoBroItem
  .CreateMetric()
  .WithId("coin_metric") // Unique ID
  .WithLabel("Coins", "Number of coins") // Label with optional description
  .OfType(coinType) // Use the custom metric type
  .OfCategory(financeCategory) // Associate with the custom category
  .OfNoGroup() // No group for this metric
  .Build();

// Register items in the right order
_mobro.Register(financeCategory); // Register the custom category first
_mobro.Register(coinType); // Register the custom metric type next
_mobro.Register(metric); // Finally, register the metric

Best Practice

Register all metrics, categories, and custom items in the Init function of the plugin. This ensures that everything is properly initialized before updating metric values.

---

Using Icons

info

While icons are supported, their usage in the MoBro application is currently limited.

For certain items, such as Categories or MetricTypes, an icon can be assigned.
Before assigning an icon, it must be registered as a Resource.

Example: Assigning an Icon to a Category

// Create the icon resource
var categoryIcon = MoBroItem
  .CreateResource()
  .WithId("category_icon") // Unique resource ID
  .WithAlt("Icon") // Alternative text
  .Icon() // Specify that this resource is an icon
  .AddFromRelativePath("./path/to/icon.png", IconSize.Default) // Path to the icon file
  .Build();

// Create a custom category with an assigned icon
var category = MoBroItem
  .CreateCategory()
  .WithId("finance_category") // Unique category ID
  .WithLabel("Finances") // Category label
  .WithIcon("category_icon") // Reference the icon by ID
  .Build();

// Register the icon and category
_mobro.Register(categoryIcon);
_mobro.Register(category);

---

Unregistering Items

Registered IMoBroItems can be unregistered at any time using the IMoBroService interface.

caution

Unregistering metrics during plugin runtime may cause issues if they are already added to dashboards.

Example: Unregistering a Metric

// Unregister a metric by its ID
_mobro.Unregister("my_metric");