====== Customize UI components with Starling Builder =====

Sometimes the built-in Starling Builder components and configs do not satisfy what you need, it's easy to customize it.

===== Customize component properties with config change =====

If you want to add a property into the property UI, or add some new UI components that's already linked into the editor, you don't need to recompile the app. All you need is to change a config file.

Open Workspace menu and click on edit template, the editor_template.json will open for you. It's located in YOUR_WORKSPACE/setting folder.

When you are done editing it, you need to restart Starling Builder to see the changes

When a new version is upgraded, the editor_template.json may be overridden by a new one.
So it's a good idea to make a backup with the config file to preserve your changes.

Here's an example of adding the blendMode property to Image

<code as3>
{
    "cls":"starling.display.Image",
    "params":[
        {"name":"width", "component":"slider", "min":1, "max":2000, "step":1},
        {"name":"height", "component":"slider", "min":1, "max":2000, "step":1},
        {"name":"scaleX", "step":0.01, "default_value":1},
        {"name":"scaleY", "step":0.01, "default_value":1},
        {"name":"color", "component":"colorPicker", "default_value":16777215},
        {"name":"blendMode", "component":"pickerList", "options":["auto", "screen", "normal"], "default_value":"auto"}
    ],
    "constructorParams":
    [
        {"cls":"starling.textures.Texture"}
    ],
    "tag":"asset"
}
</code>

{{:builder:custom-component1.png?750}}


===== Create custom UI components with runtime library =====


If the UI components you want to use are not supported by Starling Builder, you can compile them into a swf file and drop them into YOUR_WORKSPACE/libs folder

Here's how it works

  * Open the https://github.com/yuhengh/starling-builder-extensions project, you can find a build configuration named components.

  * This is an sample project that compiled the awesome PixelMaskDisplayObject http://wiki.starling-framework.org/extensions/pixelmask into the swf.

  * Feel free to add as many custom UI components as possible and compile them into the swf.

  * Drop the EmbeddedComponents.swf into YOUR_WORKSPACE/libs folder

  * Make sure to click on Workspace menu -> delete template override, and reload the editor to make it work

When you add a new custom UI component, you need to complete 3 steps. 

  - Write the custom UI component class
  - Write the config in custom_component_template.json
  - Link the class to EmbeddedComponents.linkers

For more information you can take a look at the implementation of PixelMaskDisplayObject as an example.

You can also checkout [[builder:list_components|List of official Custom UI Components]]

{{:builder:pixelmask.png?750|}}

===== Editor Template Reference =====

==== Top level ====

^name^description^
|supported_components|Official components and its properties supported by the editor|
|custom_components|Custom components and its properties supported by the editor|
|default_component|common properties of any UI components|
|background|Properties for background|
|version|version number of the template|
|revision|revision number of the template, when there's any changes in the template, this number will increase, and the editor_template in the workspace will be overridenn|

==== Inside supported_components or custom_components ====

^name^description^
|cls|full qualified name of the UI component class|
|params|editable properties of the component, in addition to default_component.params|
|createButton|whether create button will show up below the picker list|
|container|whether the component can be a container of other components|
|tag|what tab the component belongs to on the left, can be either asset, text, container or feathers|
|createComponentClass|a full qualified class name of a class which will show up before creating the UI component|

==== Inside params ====

^name^description^
|name|name of property|
|component|component of the inspector, for the time being the following components are supported: textInput, textArea, slider, check, pickerList, colorPicker, popup|
|cls|whether the component is a class or a simple type|
|disable|whether the textInput is disabled|
|default_value|default value of the parameter in code. If the current value is equal to default value, then it won’t be saved to the layout file|
|editPropertyClass|full qualified class name when the edit button is triggered, only usable when component set to “popup”|


===== Testing UI Component =====

Sometimes it’s not very convenient to build the swf, place it to the workspace and test it with the editor. In this case, use the test app inside tests folder to test it. You can simply replace the placer holder image with your own ui component and test it by launching the app.

{{:builder:test_component.png?750|}}