diff --git a/03-Parameter Tags.md b/03-Parameter Tags.md index 83e0c92..9c23e79 100644 --- a/03-Parameter Tags.md +++ b/03-Parameter Tags.md @@ -4,6 +4,9 @@ There are several parameter tags available to create the MuCow widget's On-Objec Parameters can then be included in your code, and replaced ## `` + +###### Versions Supported: 1+ + Specifies a parameter that will be user entered text. This text can be displayed as either a single-line or multi-line entry box in the OOUI. The maximum number of characters allowed in this field is 2048 starting with Muse 2014.0. Prior to this, the maximum was 1024. ### Examples @@ -18,19 +21,19 @@ Specifies a parameter that will be user entered text. This text can be displayed ![Example parameter tag with the multiline option set](images/example_param_tag_multiline_text.png) ### Required Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| name | Unique String | The name of the value. | -| defaultValue | String | The default value this item should have when first placed | +| name | Unique String | 1+ | The name of the value. | +| defaultValue | String | 1+ | The default value this item should have when first placed | ### Optional Attributes -| Name | Values | Minimum Format | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| label | String | | Label to display in the OOUI | -| toolTip | String | | Tooltip to display in the OOUI when hovering over this option | -| paramEncoding | `URIComponent`
`spaceToPlus` | | The type of encoding to apply to the entered parameter | -| multiline | Boolean | | If set to true a multiline text control will be created in the UI instead of a single line text box. | -| defaultIllegalForOutput | Boolean | 2 | Will warn the user if the default value is used when exporting or publishing the site | +| label | String | 1+ | Label to display in the OOUI | +| toolTip | String | 1+ | Tooltip to display in the OOUI when hovering over this option | +| paramEncoding | `URIComponent`
`spaceToPlus` | 1+ | The type of encoding to apply to the entered parameter | +| multiline | Boolean | 1+ | If set to true a multiline text control will be created in the UI instead of a single line text box. | +| defaultIllegalForOutput | Boolean | 2+ | Will warn the user if the default value is used when exporting or publishing the site | ## `` Specifies a parameter that a user can select from a set of given options. Options are given using `` tags, which are children of the `` tag. See Child Tags section. @@ -45,29 +48,36 @@ Specifies a parameter that a user can select from a set of given options. Option ![Example parameter tag](images/example_param_tag_list.png) ### Required Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| name | Unique String | The name of the value. | -| defaultValue | String | The default value this item should have when first placed. This must match one of the `name` attributes of a child `` element. | +| name | Unique String | 1+ | The name of the value. | +| defaultValue | String | 1+ | The default value this item should have when first placed. This must match one of the `name` attributes of a child `` element. | ### Optional Attributes -| Name | Values | Description | -|---|---|---| -| label | String | Label to display in the OOUI | -| toolTip | String | Tooltip to display in the OOUI when hovering over this option | +| Name | Values | Versions Supported | Description | +|---|---|---|---| +| label | String | 1+ | Label to display in the OOUI | +| toolTip | String | 1+ | Tooltip to display in the OOUI when hovering over this option | ### Child tags #### `` Specifies a user-selectable value. **NOTE: `` tags can contain [Content Tags][1] which will modify the output.** -##### Attributes -| Name | Values | Description | +##### Required *Child* Attributes +| Name | Values | Versions Supported | Description | +|---|---|---|---| +| name | Unique String | 1+ | Value that will be passed to the final code. | + +##### Optional *Child* Attributes +| Name | Values | Versions Supported | Description | |---|---|---|---| -| name | Unique String | **REQUIRED** Value that will be passed to the final code. | -| label | String | A label to display to the user | -| disableOptions | List | A comma separated list of name values for options that are disabled when the selected item is this +| label | String | 1+ | A label to display to the user | +| disableOptions | List | 1+ | A comma separated list of name values for options that are disabled when the selected item is this ## `` + +###### Versions Supported: 1+ + Specifies the user should enter either a partial or full URL. ### Examples @@ -84,22 +94,25 @@ Specifies the user should enter either a partial or full URL. ![Example parameter tag](images/example_param_tag_url_or_current.png) ### Required Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| name | Unique String | The name of the value. | -| defaultValue | String | The default value this item should have when first placed. This must match one of the `name` attributes of a child `` element. | +| name | Unique String | 1+ | The name of the value. | +| defaultValue | String | 1+ | The default value this item should have when first placed. This must match one of the `name` attributes of a child `` element. | ### Optional Attributes -| Name | Values | Minimum Format | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| label | String | | Label to display in the OOUI | -| toolTip | String | | Tooltip to display in the OOUI when hovering over this option | -| urlStart | String | | A comma separated list of URL prefixes. all entered URLs must start with one of these, or be incomplete URLs. | -| currentPageOrURL | Boolean | | If set to 'true', user will be able to enter an arbitrary URL, or choose the URL for the current Muse Page. | -| dummyDomainPrefix | String | | If the user hasn't yet entered a domain name, when generating HTML for the current page, this dummy prefix will be used, along with a GUID. | -| defaultIllegalForOutput | Boolean | 2 | Will warn the user if the default value is used when exporting or publishing the site | +| label | String | 1+ | Label to display in the OOUI | +| toolTip | String | 1+ | Tooltip to display in the OOUI when hovering over this option | +| urlStart | String | 1+ | A comma separated list of URL prefixes. all entered URLs must start with one of these, or be incomplete URLs. | +| currentPageOrURL | Boolean | 1+ | If set to 'true', user will be able to enter an arbitrary URL, or choose the URL for the current Muse Page. | +| dummyDomainPrefix | String | 1+ | If the user hasn't yet entered a domain name, when generating HTML for the current page, this dummy prefix will be used, along with a GUID. | +| defaultIllegalForOutput | Boolean | 2+ | Will warn the user if the default value is used when exporting or publishing the site | ## `` + +###### Versions Supported: 1+ + Specifies an option that the user will be able to toggle on/off. Must include the values to use for true & false. One or both values may disable other options. Multiple bool UI elements will be arranged in columns ### Examples @@ -112,37 +125,38 @@ Specifies an option that the user will be able to toggle on/off. Must include th ![Example parameter tag with option off](images/example_param_tag_bool_off.png) ### Required Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| name | Unique String | The name of the value. | -| defaultValue | String | The default value this item should have when first placed. This must match one of the `name` attributes of a child element. | +| name | Unique String | 1+ | The name of the value. | +| defaultValue | String | 1+ | The default value this item should have when first placed. This must match one of the `name` attributes of a child element. | ### Optional Attributes -| Name | Values | Description | -|---|---|---| -| label | String | Label to display in the OOUI | -| toolTip | String | Tooltip to display in the OOUI when hovering over this option | +| Name | Values | Versions Supported | Description | +|---|---|---|---| +| label | String | 1+ | Label to display in the OOUI | +| toolTip | String | 1+ | Tooltip to display in the OOUI when hovering over this option | ### Child tags #### `` Specifies a value to pass when user turns on this option. **NOTE: `` tags can contain [Content Tags][1] which will modify the output.** -##### Attributes -| Name | Values | Description | -|---|---|---|---| -| value | String | **Required.** Value that will be passed to the final code. | -| disableOptions | List | A comma separated list of name values for options that are disabled when the item is in this state. | - #### `` Specifies a value to pass when user turns off this option. **NOTE: `` tags can contain [Content Tags][1] which will modify the output.** -##### Attributes -| Name | Values | Description | +##### Required *Child* Attributes +| Name | Values | Versions Supported | Description | +|---|---|---|---| +| value | String | 1+ | Value that will be passed to the final code. | + +##### Optional *Child* Attributes +| Name | Values | Versions Supported | Description | |---|---|---|---| -| value | String | **Required.** Value that will be passed to the final code. | -| disableOptions | List | A comma separated list of name values for options that are disabled when the item is in this state. | +| disableOptions | List | 1+ | A comma separated list of name values for options that are disabled when the item is in this state. | ## `` + +###### Versions Supported: 1+ + Specifies the user entered value should be a number ### Examples @@ -153,28 +167,28 @@ Specifies the user entered value should be a number ![Example parameter tag](images/example_param_tag_number.png) ### Required Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| name | Unique String | The name of the value. | -| defaultValue | String | The default value this item should have when first placed | -| min | Number | The minimum allowed value | -| max | Number | The maximum allowed value | +| name | Unique String | 1+ | The name of the value. | +| defaultValue | String | 1+ | The default value this item should have when first placed | +| min | Number | 1+ | The minimum allowed value | +| max | Number | 1+ | The maximum allowed value | ### Optional Attributes -| Name | Values | Description | -|---|---|---| -| label | String | Label to display in the OOUI | -| toolTip | String | Tooltip to display in the OOUI when hovering over this option | -| step | Number | How large a step should be if the user clicks the up or down arrow. Defaults to 1 | -| snap | Number | What increment should values snap to. Defaults to 1 | -| digitsPrecision | Number | The number of digits to show after the decimal point | +| Name | Values | Versions Supported | Description | +|---|---|---|---| +| label | String | 1+ | Label to display in the OOUI | +| toolTip | String | 1+ | Tooltip to display in the OOUI when hovering over this option | +| step | Number | 1+ | How large a step should be if the user clicks the up or down arrow. Defaults to 1 | +| snap | Number | 1+ | What increment should values snap to. Defaults to 1 | +| digitsPrecision | Number | 1+ | The number of digits to show after the decimal point | ## `` A built in is a special type that allows you to get values that are specified directly in Adobe Muse. These values are passed in the same as any other parameters, and the name can be any one of the values listed below. ### Attributes | Name | Values | Description | -|---|---|---|---| +|---|---|---| | name | Type | **Required.** One of the types listed below | | supportedLocales | List | When the `name` attribute is "locale", this attribute is a comma separated list of locales supported by this MuCow. If the document locale is not one of these, the en_US will be used | | supportedLanguages | List | When the `name` attribute is "language", this attribute is a comma separated list of languages supported by this MuCow. If the document language is not one of these languages, the English equivalent will be used instead | @@ -253,7 +267,10 @@ A built in is a special type that allows you to get values that are specified di ## `` -Informative text to show in the On-Object UI, which can optionally link to a URL. **Only supported by widgets format 2 or above.** + +###### Versions Supported: 2+ + +Informative text to show in the On-Object UI, which can optionally link to a URL. ### Examples @@ -266,17 +283,20 @@ Informative text to show in the On-Object UI, which can optionally link to a URL ![Example parameter tag with a link](images/example_param_tag_info_link.png) ### Required Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| label | String | The text to display to the user | +| label | String | 2+ | The text to display to the user | ### Optional Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| linkURL | URL | The URL to take the user to if the text is clicked | +| linkURL | URL | 2+ | The URL to take the user to if the text is clicked | ## `` -A line used to separate parameters in the On-Object UI. **Only supported by widgets format 2 or above.** + +###### Versions Supported: 2+ + +A line used to separate parameters in the On-Object UI. ### Examples @@ -287,35 +307,41 @@ A line used to separate parameters in the On-Object UI. **Only supported by widg ![Example parameter tag](images/example_param_tag_separator.png) ## `` -Specifies a parameter that will be a user chosen file. This file will be added as a file for upload. **Only supported by widgets format 3 or above.** + +###### Versions Supported: 3+ + +Specifies a parameter that will be a user chosen file. This file will be added as a file for upload. ### Examples - + ![Example parameter tag](images/example_param_tag_file.png) ### Required Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| name | String | The name of the value | +| name | String | 3+ | The name of the value | ### Optional Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| label | String | Label to display in the OOUI | -| toolTip | String | Tooltip to display in the OOUI when hovering over this option | -| filterLabel | String | Label for filter in the file browse dialog | -| fileTypes | String | File types allowed in the file browse dialog. Should be a semicolon-separated list in format "\*.ext;\*.ext2" | -| fileRequiredForOutput | Boolean | Will warn the user when exporting or publishing the site if no file was chosen. Defaults to false. | -| asAbsoluteURL | Boolean | v4 The result is computed as an absolute (http) URL based on publish settings. | +| label | String | 3+ | Label to display in the OOUI | +| toolTip | String | 3+ | Tooltip to display in the OOUI when hovering over this option | +| filterLabel | String | 3+ | Label for filter in the file browse dialog | +| fileTypes | String | 3+ | File types allowed in the file browse dialog. Should be a semicolon-separated list in format "\*.ext;\*.ext2" | +| fileRequiredForOutput | Boolean | 3+ | Will warn the user when exporting or publishing the site if no file was chosen. Defaults to false. | +| asAbsoluteURL | Boolean | 4+ | The result is computed as an absolute (http) URL based on publish settings. | -Starting in v4 of the MuCow format, the `` parameter can resolve with an absolute url to the file if the `asAbsoluteURL` attribute is true. -Special care must be taken when the user chooses their publication settings when Muse is not publishing the site on their behalf (i.e. when generating -the site to disk.) Muse uses the values entered in these options to build a canonical URL to the file specified. +Starting in v4 of the MuCow format, the `` parameter can resolve with an absolute url to the file if the `asAbsoluteURL` attribute is true. Special care must be taken when the user chooses their publication settings when Muse is not publishing the site on their behalf (i.e. when generating the site to disk.) Muse uses the values entered in these options to build a canonical URL to the file specified. ## `` -Specifies a parameter that will be user chosen color. Presented to the user as a color picker in the UI. **Only supported by widgets format 3 or above.** + +###### Versions Supported: 3+ + +Specifies a parameter that will be user chosen color. Presented to the user as a color picker in the UI. ### Examples @@ -325,35 +351,34 @@ Specifies a parameter that will be user chosen color. Presented to the user as a ![Example parameter tag](images/example_param_tag_color.png) ### Required Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| name | String | The name of the value | -| defaultValue | String | Can be either hex color or comma separated RGB value. Does not affect output format. Use rgbColor to output comma separated RGB value. | +| name | String | 3+ | The name of the value | +| defaultValue | String | 3+ | Can be either hex color or comma separated RGB value. Does not affect output format. Use rgbColor to output comma separated RGB value. | ### Optional Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| label | String | Label to display in the OOUI | -| toolTip | String | Tooltip to display in the OOUI when hovering over this option | -| rgbColor | Boolean | Color value to be returned as comma separated RGB value. Defaults to false. | -| formatHexColor | Boolean | Adds the # character before the hex value. Use when color is used in CSS. Defaults to false. | -| supportsNoneColor | Boolean | Allow user to pick the none color swatch. Choosing none will output the word transparent. Defaults to false. | -| transparentOption | String | The name of a `` input parameter to use to control transparency. This Allows the color picker to include a slider to adjust the alpha channel of the color. The named input can later be referenced by the generated code as content to pass as the alpha parameter to rgba(). When specifying a transparentOption, supportsNoneColor must also be set to `true` . | +| label | String | 3+ | Label to display in the OOUI | +| toolTip | String | 3+ | Tooltip to display in the OOUI when hovering over this option | +| rgbColor | Boolean | 3+ | Color value to be returned as comma separated RGB value. Defaults to false. | +| formatHexColor | Boolean | 3+ | Adds the # character before the hex value. Use when color is used in CSS. Defaults to false. | +| supportsNoneColor | Boolean | 3+ | Allow user to pick the none color swatch. Choosing none will output the word transparent. Defaults to false. | +| transparentOption | String | 3+ | The name of a `` input parameter to use to control transparency. This Allows the color picker to include a slider to adjust the alpha channel of the color. The named input can later be referenced by the generated code as content to pass as the alpha parameter to rgba(). When specifying a transparentOption, supportsNoneColor must also be set to `true` . | ## `
` + +###### Versions Supported: 4+ + Section is a special parameter tag which allows for related parameters to be grouped together. The user experience for section tags is a collapsable group with a disclosure arrow. `
` tags should have at least 1 of the child parameter tags listed above but it may not contain any other `
` tags. -### Required Attributes -| Name | Values | Description | -|---|---|---|---| -| label | String | Label to display in the OOUI | - ### Optional Attributes -| Name | Values | Description | +| Name | Values | Versions Supported | Description | |---|---|---|---| -| expanded | Boolean | Specifies if the section is initially expanded when the OOUI is displayed for the widget. Defaults to false. | -| name | Unique String | The name of the section. This name can be used to reference the section from a "disableOptions" attribute of another parameter | +| label | String | 4+ | Label to display in the OOUI | +| expanded | Boolean | 4+ | Specifies if the section is initially expanded when the OOUI is displayed for the widget. Defaults to false. | +| name | Unique String | 4+ | The name of the section. This name can be used to reference the section from a "disableOptions" attribute of another parameter |