Extending Functionality with Plugins

Plugins in ZoboUI are powerful tools that allow you to enhance or create new utilities and features, especially those that involve generating custom classes based on data. Whether you're crafting a custom plugin or incorporating third-party plugins, they enable the addition of functionalities that may not be natively supported by USS and UXML.

Why Use Plugins?

Aligning closely with USS and UXML's current capabilities, ZoboUI uses plugins to extend features that are not yet available. A prime example is Grid support. Since Unity's UI Toolkit doesn't currently support Grid layouts, a custom plugin can be developed to introduce this functionality. When native support becomes available, the feature can be integrated into the official config, possibly replacing the need for the plugin.

How to Use Plugins

To incorporate plugins into your project:

1. Open the Theme Config Asset: Find the Theme Config asset within your Unity project.
2. Navigate to the 'Plugins' Field: Here, you can manage the plugins for your project.
3. Plugin Assets: Whether you're using a custom or third-party plugin, you'll need to create an asset that stores the relevant plugin information. This asset can then be included in the plugin field list.
4. Plugin Order: Plugins are executed in the order they appear in the list. This can be important if you're using multiple plugins that affect the same utility. For example, if you're using a plugin that adds custom grid support and a plugin that adds custom flex support, the order in which they're executed can affect the final result.

Developing Custom Plugins

Creating plugins requires familiarity with C#. You'll need to inherit from BaseUtilityPlugin and override the necessary methods to implement the desired functionality.

Key Methods in BaseUtilityPlugin

• ProcessThemeConfig: Called during class and selector generation, allowing the plugin to add rules to the generated USS file.
• OnPurgeComplete: Invoked after the purging process, letting the plugin take action based on the remaining rules.
• GetClassExtractor: Provides a class extractor for purging, crucial for classes that don't follow conventional naming.

Implementing a Plugin

Here's a conceptual overview of creating a plugin:

using ZoboUI.Core.Plugins;
using ZoboUI.Editor;

public class MyCustomPlugin : BaseUtilityPlugin
{
    public override string PluginNamespace => "com.mycompany.mypluginname";
    public override string PluginUtilityName => "My Custom Plugin";
    public override string PluginDescription => "A plugin that adds custom grid support.";

    public override RuleGenerationPriority RuleGenerationPriority => RuleGenerationPriority.AfterDefaultUtilities;

    public override void ProcessThemeConfig(ThemeConfig themeConfig, UtilityRuleBag bag, ICustomLogger logger = null)
    {
        // Add custom rules based on the ThemeConfig
    }

    public override IClassExtractor GetClassExtractor(ICustomLogger logger = null)
    {
        // Provide a class extractor if needed
    }

    public override void OnPurgeComplete(ThemeConfig themeConfig, UtilityRuleBag bag, ICustomLogger logger = null)
    {
        // Perform any necessary cleanup after purging
    }

    public override string ToJson()
    {
        // Serialize plugin data to JSON
    }

    public override void FromJson(string jsonString)
    {
        // Initialize the plugin from JSON data
    }
}

By leveraging plugins, ZoboUI provides a flexible and expandable framework that adapts to your project's unique requirements.