Difference between revisions of "Custom elements"

Latest revision as of 17:25, 29 March 2017

Custom tags can be a great way to reuse functionality and extend PowerUI. They're designed to be simple to make, so simple copy and pasting skills or basic coding skills can be all that's required. Let's get started!

A basic element

The most basic custom element (A C# file) looks like this:

using PowerUI;

// This would be used as e.g. <hello/>

[Dom.TagName("hello")]
public class HtmlHelloElement : HtmlElement{

}

At the very least, you must:

• Inherit from an appropriate type of element (it'll almost always be HtmlElement that you use)
• Give it a tag name
• Give it a class name, which is typically of the form HtmlTagNameElement

Place it somewhere outside the PowerUI folders. This is just incase you update PowerUI, as you won't want to lose your changes. It can go anywhere you find appropriate.

Handling Attributes

Most tags have at least one attribute - something like <hello name='PowerUI'>. Often you would want your tag to respond to an attribute being changed. Use OnAttributeChange for that:

/// <returns>True if your tag handled the change.</returns>
public override bool OnAttributeChange(string attrib){
    
    // The fastest approach is to simply use a series of if statements
    // A dictionary only becomes useful if you're handling 20+ attributes
    
    if(attrib == "name"){
    
        // name='something' was set! Note that this occurs both during parsing
        // and if e.g. anElement.setAttribute was called.
    
        // Get the actual value (or getAttribute if you prefer):
        string nameValue = this["name"];
    
    // }else if(attrib == "surname"){ // Etc!
      
    }else{
        
        // Fallback on base - it handles class, id, style etc:
        return base.OnAttributeChange(attrib);
        
    }
    
    return true;
    
}

Events

Some tags also respond to specific types of event or simply all events. The camera tag, for example, fires all events it receives into the scene. If an event does not have a specific overrideable method (like OnClickEvent does) then use HandleLocalEvent:

/// <returns>True if the default is allowed (you're returning the result for dispatchEvent).</returns>
protected override bool HandleLocalEvent(Dom.Event e, bool bubblePhase){
    
    // You generally want to handle it on the bubble phase:
    if(bubblePhase){
    
        if(e.type == "click"){
        
            // We got a click event! Do something with e.
            // Note that this is almost identical to OnClickEvent
            // (only this fires first, and can optionally block OnClickEvent from occuring).
        
        }
        
    }
    
    // Default otherwise!
    return base.HandleLocalEvent(e, bubblePhase);
    
}

Copy what exists

Think of some standard element that is similar to what your new element will do and take a look at it for inspiration. Think of things like:

• Will your tag be clicked on?
• Does it have attributes (attribute="it's value")?
• Does it have non-html content like a script?
• Does it have complex parsing behaviour like a table, where tbody is often automatically inserted?
• Does it handle its children in a special way like a select element does?
• Does it have 'virtual' elements like the dropdown button of a select element?

Finding built-in elements

Currently there are 4 major groups of elements in PowerUI:

• HTML elements - Path/To/PowerUI/Engine/Tags
• SVG elements - Path/To/PowerUI/Source/SVG/Tags
• MathML elements - Path/To/PowerUI/Source/Extras/MathML/Tags
• LangDoc elements (localisation) - Path/To/PowerUI/Dom/LangDoc/Elements

Checking your element is available

An easy sanity check is to make sure your new element is being correctly detected by PowerUI. To do that:

• Go to Window > PowerUI > Supported Tags
• Look for e.g. xhtml:yourTagName

If PowerUI is successfully detecting your element, it will be visible on this list.