docs.modx.pro
  1. Extras
  2. ms3OptionsColor
  3. Snippets
  4. ms3OptionsColor

ms3OptionsColor ​

The snippet reads product option values or ready JSON, matches them to the dictionary, and returns HTML via a chunk or an array of rows. Prefer an uncached call: [[!ms3OptionsColor]] / {'!ms3OptionsColor' | snippet}.

On each run the snippet may load storefront CSS when ms3optionscolor_frontend_css is enabled.

How rows are selected ​

  1. Option keys come from the options parameter or ms3optionscolor_default_option_key.
  2. When byOptions is set, values come from JSON. Product options are not read from the database.
  3. Otherwise values are read for product product (current resource by default).
  4. Each value is looked up in the dictionary. With includeUnset=1, values without a dictionary entry still appear (empty swatch).
  5. With activeOnly=1, inactive dictionary entries are hidden.
  6. limit trims the list from the top.
  7. With return=tpl each row is output through chunk tpl. With return=data you get an array.

Parameters ​

ParameterDefaultDescription
productcurrent resource idminiShop3 product ID. 0 or empty: current resource
optionsfrom setting / colorOption keys comma-separated, e.g. color or color,material
byOptions-JSON of option values. When set, the product is not read from the database
tpltplMs3OptionsColorRow chunk: Elements name or @FILE path/to/file.tpl
returntpltpl — HTML, data — array of rows
activeOnly1Only active dictionary entries
includeUnsetautoInclude values without a dictionary entry. Default 1 with byOptions, otherwise 0
limit0Max rows. 0 — no limit
selectedValue-Set field selected on the row with this value (handy for <option>)
toPlaceholder-Placeholder name. The snippet prints nothing to output

The alias selected for selectedValue is also accepted.

Row fields ​

In the chunk and in return=data:

FieldDescription
option_keyOption key
valueOption value (as in miniShop3)
colorHEX without #
patternPattern / background URL
ralRAL code
titleLabel (if empty, chunks often use value)
descriptionDescription
imageImage
activeWhether the dictionary entry is active
statusactive / inactive / unset
hint_colorHEX from comboColors, no dictionary write
configuredNon-empty HEX or pattern. Title/RAL/image alone is false and status=unset
id / rankDictionary row id and sort
selectedtrue when value matches selectedValue

In CSS and select use #{$color} or data-color="#{$color}": the field holds the code without #.

Examples ​

Product page ​

fenom
{'!ms3OptionsColor' | snippet : [
  'product' => $_modx->resource.id,
  'options' => 'color',
  'tpl' => 'tplMs3OptionsColor'
]}
modx
[[!ms3OptionsColor?
  &product=`[[*id]]`
  &options=`color`
  &tpl=`tplMs3OptionsColor`
]]

Without &options the snippet uses keys from ms3optionscolor_default_option_key.

Multiple option keys ​

fenom
{'!ms3OptionsColor' | snippet : [
  'product' => $_modx->resource.id,
  'options' => 'color,material',
  'tpl' => 'tplMs3OptionsColor'
]}
modx
[[!ms3OptionsColor?
  &product=`[[*id]]`
  &options=`color,material`
  &tpl=`tplMs3OptionsColor`
]]

Catalog row ​

In the msProducts row chunk pass the row product ID and a short list:

fenom
{'!ms3OptionsColor' | snippet : [
  'product' => $id,
  'options' => 'color',
  'tpl' => 'tplMs3OptionsColor',
  'limit' => 6
]}
modx
[[!ms3OptionsColor?
  &product=`[[+id]]`
  &options=`color`
  &tpl=`tplMs3OptionsColor`
  &limit=`6`
]]

Show values without a dictionary color ​

An empty swatch (checkerboard in stock CSS) shows a value until the dictionary has a HEX:

fenom
{'!ms3OptionsColor' | snippet : [
  'product' => $_modx->resource.id,
  'options' => 'color',
  'includeUnset' => 1,
  'tpl' => 'tplMs3OptionsColor'
]}
modx
[[!ms3OptionsColor?
  &product=`[[*id]]`
  &options=`color`
  &includeUnset=`1`
  &tpl=`tplMs3OptionsColor`
]]

Hide inactive rows and limit the list ​

fenom
{'!ms3OptionsColor' | snippet : [
  'product' => $_modx->resource.id,
  'options' => 'color',
  'activeOnly' => 1,
  'limit' => 4,
  'tpl' => 'tplMs3OptionsColor'
]}
modx
[[!ms3OptionsColor?
  &product=`[[*id]]`
  &options=`color`
  &activeOnly=`1`
  &limit=`4`
  &tpl=`tplMs3OptionsColor`
]]

To a placeholder ​

fenom
{'!ms3OptionsColor' | snippet : [
  'product' => $_modx->resource.id,
  'options' => 'color',
  'toPlaceholder' => 'ms3oc.swatches'
]}
{$_modx->getPlaceholder('ms3oc.swatches')}
modx
[[!ms3OptionsColor?
  &product=`[[*id]]`
  &options=`color`
  &toPlaceholder=`ms3oc.swatches`
]]
[[+ms3oc.swatches]]

return=data (custom loop) ​

fenom
{set $rows = $_modx->runSnippet('!ms3OptionsColor', [
  'product' => $_modx->resource.id,
  'options' => 'color',
  'return' => 'data'
])}
{foreach $rows as $row}
  {$row.color} {$row.title ?: $row.value}{if $row.ral} RAL {$row.ral}{/if}
{/foreach}
modx
[[!ms3OptionsColor?
  &product=`[[*id]]`
  &options=`color`
  &return=`data`
  &toPlaceholder=`ms3oc.rows`
]]

In MODX tags send the array to a placeholder and parse it with your own snippet or Fenom chunk.

byOptions: cart and ready JSON ​

When values already exist (cart line, your JSON), do not read product options from the database:

fenom
{set $colors = $_modx->runSnippet('!ms3OptionsColor', [
  'product' => $product.id,
  'byOptions' => json_encode($product.options),
  'return' => 'data',
  'includeUnset' => 1
])}
{foreach $colors as $row}
  {if $row.option_key == 'color'}
    <span data-ms3oc-swatch
          style="{if $row.color}background:#{$row.color}{/if}"></span>
    {$row.value}
  {/if}
{/foreach}
modx
[[!ms3OptionsColor?
  &product=`[[+id]]`
  &byOptions=`{"color":["Синий","Чёрный"]}`
  &return=`data`
  &includeUnset=`1`
]]

byOptions is a JSON string. In a cart chunk Fenom is easier. Cart branches: chunk tplMs3OptionsColorCart on Frontend.

Select with a preselected value ​

Chunk tplMs3OptionsColorSelect calls the snippet itself. Direct option chunk call:

fenom
<select name="options[color]" data-ms3oc-select data-ms3oc-native="1">
  <option value="">Выберите цвет</option>
  {'!ms3OptionsColor' | snippet : [
    'product' => $_modx->resource.id,
    'options' => 'color',
    'tpl' => 'tplMs3OptionsColorSelectOption',
    'selectedValue' => 'Синий',
    'includeUnset' => 1
  ]}
</select>
modx
<select name="options[color]" data-ms3oc-select data-ms3oc-native="1">
  <option value="">Выберите цвет</option>
  [[!ms3OptionsColor?
    &product=`[[*id]]`
    &options=`color`
    &tpl=`tplMs3OptionsColorSelectOption`
    &selectedValue=`Синий`
    &includeUnset=`1`
  ]]
</select>

Select with a label:

fenom
<script src="{'assets_url' | option}components/ms3optionscolor/js/web/select.js"></script>
{$_modx->getChunk('tplMs3OptionsColorSelect', [
  'product' => $_modx->resource.id,
  'option_key' => 'color',
  'caption' => 'Цвет',
  'placeholder' => 'Выберите цвет',
  'selectedValue' => 'Синий',
  'native' => 1
])}
modx
<script src="[[++assets_url]]components/ms3optionscolor/js/web/select.js"></script>
[[$tplMs3OptionsColorSelect?
  &product=`[[*id]]`
  &option_key=`color`
  &caption=`Цвет`
  &placeholder=`Выберите цвет`
  &selectedValue=`Синий`
  &native=`1`
]]

Select chunk parameters: table on Frontend.

Custom chunk via @FILE ​

Path is relative to pdotools_elements_path (usually core/elements/):

fenom
{'!ms3OptionsColor' | snippet : [
  'product' => $_modx->resource.id,
  'options' => 'color',
  'tpl' => '@FILE chunk/ms3OptionsColor/tpl.option_row.tpl'
]}
modx
[[!ms3OptionsColor?
  &product=`[[*id]]`
  &options=`color`
  &tpl=`@FILE chunk/ms3OptionsColor/tpl.option_row.tpl`
]]

Dots and _ are allowed in the file name. Segment .. is rejected. Minimum markup: custom swatch chunk.

Common issues ​

SymptomWhat to check
Empty outputProduct has option values; key matches options / setting
No color squaresDictionary entry and CSS (ms3optionscolor_frontend_css)
No options in selectChunk tpl must be tplMs3OptionsColorSelectOption or your own with <option>
byOptions returns nothingJSON is valid; keys match options; try includeUnset=1

Frontend, mFilter, ms3variants. Chunk overview: Snippets.