YAML Descriptor Files for App Studio Properties Panels

From KickApps Documentation

App Studio users customize and configure components and plug-ins via properties panels. To create one or more properties panels for your plug-in, simply compose a YAML descriptor file to map configurable properties of your plug-in to UI controls. The App Studio will parse this file and automatically generate the properties panels defined in it.

Please note: You must use spaces for indentation, rather than tabs.

Contents 1 panels 2 title 3 items 4 title 5 items or type 5.1 items 5.2 type: multistate 5.3 type: multipart 6 !panel!PanelItem 6.1 control elements 6.1.1 Single Text Input 6.1.2 Single Text Input with Apply Button 6.1.3 Double Text Input 6.1.4 Single Text Area 6.1.5 Single Text Area with Apply Button 6.1.6 Asset Text Input 6.1.7 Single Slider 6.1.8 Double Slider 6.1.9 Single Color Picker 6.1.10 Double Color Picker 6.1.11 Dropdown List 6.1.12 Single Checkbox 6.1.13 Scrubber Dropdown List 6.1.14 Volume Control Dropdown 6.1.15 Single Numeric Stepper 6.1.16 Quad Numeric Stepper

panels

panels should be the first element in your YAML file.

panels:

title

title should be the second line in your YAML file. It defines the label that should appear at the top of the property panel bay when your plug-in is selected.

title: "Captioner"

Result:

items

items should be the third line in your YAML file. It wraps all the panels defined below it.

title

title should be the fourth line of your YAML file. It defines the label of your first panel. For a component that needs multiple panels, simply include multiple title nodes with their own items collections.

- title: "Button"

Result:

items or type

The next element in your YAML file specifies what kind of panel it should be. Use one of the following:

items

for a regular panel containing UI controls

type: multistate

for a tabbed panel used to configure the component in different states

type: multipart

for a panel that contains a dropdown used to pick different parts of the component to configure

items

items contains a collection of !panel!PanelItem entries for generating UI controls that set properties on your component. Each of these entries begins with

    - !panel!PanelItem

type: multistate

The type element is used to set out panels that will have tabs representing multiple states. The labels for these tabs are defined by a tabs element that takes an array of tab labels.

  type: multistate
  tabs: [UP, HOVER, DOWN, TOGGLE]

Result:

Each of the tabs reveals a different screen in which the user can configure your component in a particular state. Each state is defined within the states element by !panel!PanelItem entries:

  type: multistate
  tabs: [UP, HOVER, DOWN, TOGGLE]
  states:
    UP: |-
      %TAG !panel! !actionscript/object:com.kickapps.widgetbuilder.panel.
      %TAG !control! !actionscript/object:com.kickapps.widgetbuilder.panel.components.
      ---
      - !panel!PanelItem
          control: !control!FontPicker
                      label: "Font:"
          bindings: [ { componentProperty: fontFace, itemProperty: font }, { componentProperty: fontsEmbedded, itemProperty: useEmbeddedFont } ]
         
      - !panel!PanelItem
          control: !control!SingleColorPicker
                    label: "Font Color:"
          componentProperty: fontColor
          itemProperty: selectedValue  
          
      - !panel!PanelItem
          control: !control!SingleSlider
                    label: "Font Size:"
                    maximum: 64
                    textDecorator: "px"
          componentProperty: fontSize
          itemProperty: selectedValue
 
    HOVER: |-
      %TAG !panel! !actionscript/object:com.kickapps.widgetbuilder.panel.
      %TAG !control! !actionscript/object:com.kickapps.widgetbuilder.panel.components.
      ---
      - !panel!PanelItem
          control: !control!FontPicker
                      label: "Font:"
          bindings: [ { componentProperty: overFontFace, itemProperty: font }, { componentProperty: fontsEmbedded, itemProperty: useEmbeddedFont } ]
     
      ...

Result:

type: multipart

Setting type to "multipart" creates a panel that lets users set the same properties on different parts of a component. Users select which part of a component is to be configured from a dropdown menu. The options in the dropdown are defined by the parts element, which accepts an array of objects containing labels and data attributes. The UI controls are specified in an items element containing !panel!PanelItem entries.

The example below is taken from the KickApps volume control component, which lets the user set background & border properties on its background, load progress bar, play progress bar, and handle.

- title: "Background & Border"
  type: multipart
  parts: [{label: 'Background', data: 'background'}, {label: 'Load Progress Bar',data: 'loadProgress'},  {label: 'Play Progress Bar', data: 'playProgress'}, {label: 'Handle', data: 'handle'}]
  items:
    - !panel!PanelItem
        control: !control!AssetTextInput
                    label: "Icon URL or Upload Icon:"
                    prompt: "http://"
        componentProperty: BackgroundImage
        itemProperty: text

  ...

Result:

!panel!PanelItem

Each - !panel!PanelItem entry contains the following elements:

control

the UI control element complete with its properties

componentProperty

the property of your component that the UI control will change

itemProperty

the value on the panel item that sets the value of the component

  items:
    - !panel!PanelItem
        control: !control!DoubleColorPicker
                  label: "Spectrum Colors:"
        componentProperty: spectrumColors
        itemProperty: selectedValue

Result:

control elements

Single Text Input

   - !panel!PanelItem
        control: !control!SingleTextAreaWithApplyButton
                  label: "Media URL:"
        componentProperty: name
        itemProperty: text      

Result:

Single Text Input with Apply Button

    - !panel!PanelItem
        control: !control!SingleTextInputWithApplyButton
                  label: "Media URL:"
        componentProperty: name
        itemProperty: text  

Result:

Double Text Input

    - !panel!PanelItem
        control: !control!DoubleTextInput
                  label: Handle Dimensions
                  firstLabel: "Width:"
                  secondLabel: "Height:"
        bindings:
          - componentProperty: handleWidth
            itemProperty: firstTextInput
          - componentProperty: handleHeight
            itemProperty: secondTextInput

Result:

Single Text Area

    - !panel!PanelItem
        control: !control!SingleTextArea
                  label: "Label:"
        componentProperty: name
        itemProperty: text

Result:

Single Text Area with Apply Button

   - !panel!PanelItem
        control: !control!SingleTextAreaWithApplyButton
                  label: "Media URL:"
        componentProperty: name
        itemProperty: text 

Result:

Asset Text Input

prompt

sample text displayed inside this field. disappears on click.

    - !panel!PanelItem
        control: !control!AssetTextInput
                    label: "Video Thumbnail URL:"
                    prompt: "http://"
        componentProperty: videoImageURL
        itemProperty: text

Result:

Single Slider

- !panel!PanelItem
    control: !control!SingleSlider
              label: "Button Stroke:"
              minimum: 0
              maximum: 7
              stepValue: 0.1
    componentProperty: buttonStrokeThickness
    itemProperty: selectedValue

Result:

Double Slider

      - !panel!PanelItem
          control: !control!DoubleSlider
                    label: "Background Opacities:"
                    valueModifier: 100
                    textDecorator: "%"
          componentProperty: downFillAlpha
          itemProperty: selectedValue

Result:

Single Color Picker

    - !panel!PanelItem
        control: !control!SingleColorPicker
                  label: "Control Bar Color:"
        componentProperty: controlBackgroundColor
        itemProperty: selectedValue

Result:

Double Color Picker

    - !panel!PanelItem
        control: !control!DoubleColorPicker
                  label: "Button Colors:"
        componentProperty: buttonFills
        itemProperty: selectedValue

Result:

Dropdown List

    - !panel!PanelItem
        control: !control!DropDownList
                  label: Ratio
                  items: [{label:Fit, data:fit}, {label:Auto, data:auto}, {label: "4:3", data:4-3}, {label:"16:9", data:16-9}, {label:Zoom to Fit, data:zoom-to-fit}]
                  dataField: data
        componentProperty: videoAspectRatio
        itemProperty: selectedValue

Result:

Single Checkbox

    - !panel!PanelItem
        control: !control!SingleCheckBox
                  label: Auto Play
        componentProperty: autoPlay
        itemProperty: selected   

Result:

Scrubber Dropdown List

    - !panel!PanelItem
        control: !control!ScrubberDropDownList
                  label: Select Scrubber
        componentProperty: scrubber
        itemProperty: selectedValue

Result:

Volume Control Dropdown

    - !panel!PanelItem
        control: !control!VolumeControlDropDownList
                  label: Select Volume Control
        componentProperty: volumeControl
        itemProperty: selectedValue

Result:

Single Numeric Stepper

    - !panel!PanelItem
        control: !control!SingleNumericStepper
                  label: "Delay:"
                  minimum: 0.1
                  maximum: 10000
                  stepSize: 0.1
                  valueModifier: 1000
        componentProperty: delay
        itemProperty: selectedValue

Result:

Quad Numeric Stepper

      - !panel!PanelItem
          control: !control!QuadNumericStepper
                    label: "Corner Radius:"
          componentProperty: selectedCornerRadius
          itemProperty: selectedValue 

Result: