Difference between revisions of "Custom elements"

From PowerUI
Jump to: navigation, search
(Created page with "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 b...")
 
(Copy what exists)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
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!  
 
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 tag ==
+
== A basic element ==
  
The most basic tag (A C# file) looks like this:
+
The most basic custom element (A C# file) looks like this:
  
 
<syntaxhighlight lang="csharp">
 
<syntaxhighlight lang="csharp">
Line 9: Line 9:
 
using PowerUI;
 
using PowerUI;
  
 +
// This would be used as e.g. <hello/>
  
 
[Dom.TagName("hello")]
 
[Dom.TagName("hello")]
Line 17: Line 18:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Place it somewhere outside the PowerUI folders. This is just incase you update PowerUI, as you won't want to loose your changes. It can go anywhere you find appropriate.
+
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 Html''TagName''Element
 +
 
 +
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 ==
 
== Handling Attributes ==
Line 92: Line 99:
 
* Will your tag be clicked on?
 
* Will your tag be clicked on?
 
* Does it have attributes (attribute="it's value")?
 
* Does it have attributes (attribute="it's value")?
* Does it have non-html content like a <script> tag?
+
* 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 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 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?
+
* Does it have 'virtual' elements like the dropdown button of a select element?
  
== Finding built-in elements ==
+
== Finding built-in elements ==
  
 
Currently there are 4 major groups of elements in PowerUI:
 
Currently there are 4 major groups of elements in PowerUI:
Line 106: Line 113:
 
* LangDoc elements (localisation) - Path/To/PowerUI/Dom/LangDoc/Elements
 
* LangDoc elements (localisation) - Path/To/PowerUI/Dom/LangDoc/Elements
  
== Checking your tag is available ==
+
== Checking your element is available ==
  
An easy sanity check is to make sure your new tag is being correctly detected by PowerUI. To do that:
+
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
 
* Go to Window > PowerUI > Supported Tags
 
* Look for e.g. xhtml:yourTagName
 
* Look for e.g. xhtml:yourTagName
  
If PowerUI is successfully detecting your tag, it will be visible on this list.
+
If PowerUI is successfully detecting your element, it will be visible on this list.

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.