Configuration#

Create a vizy.php file under your /config directory with the following options available to you. You can also use multi-environment options to change these per environment.

The below shows the defaults already used by Vizy, so you don't need to add these options unless you want to modify the values.

<?php

return [
    '*' => [
        'iconsPath' => '@webroot/icons/',
        'recursiveFieldCount' => 10,
    ],
];

Configuration options#

  • iconsPath - Provide a file system path for a collection of SVG icons. These are available when creating your Block Types for a Vizy field. This also accepts environment variables or aliases.
  • recursiveFieldCount - For recursive Vizy fields, set the limit for how many times a Vizy fields can be nested.

Control Panel#

You can also manage configuration settings through the Control Panel by visiting Settings → Vizy.

Editor Configuration#

You can provide configuration files for the editor by providing a .json file with its configurations, very similar to how the Redactor (opens new window) plugin works. From this file, you can define what buttons are shown, what order and more. This can be particularly useful in maintaining consistent configurations for your Vizy fields across projects.

Ensure your file is valid JSON, taking care of trailing commas, and double quotes around properties.

For example, create a vizy folder in your /config directory, and inside that, create a Minimal.json file. Place the following content into that file:

{
    "buttons": ["italic", "bold", "undo", "redo"]
}

Here, we're setting the buttons available to the editor to only show Italic, Bold, Undo and Redo (in that order). All other buttons and functionality will be disabled.

Available Options#

The below list details the available configuration options to use in your JSON files.

OptionDescription
buttonsAn array of available buttons. Refer to below.
formattingAn array of available formatting options. Refer to below.
toolbarFixedA boolean true/false to denote if the button toolbar should stick to the viewport when scrolling.
tableAn array of available table options. Refer to below.
commandsAn array of available commands for the Command Palette. These will be the same as buttons.

Buttons#

OptionDescription
h1Allow the use of <h1> heading tags.
h2Allow the use of <h2> heading tags.
h3Allow the use of <h3> heading tags.
h4Allow the use of <h4> heading tags.
h5Allow the use of <h5> heading tags.
h6Allow the use of <h6> heading tags.
paragraphAllow text to be shown as a paragraph.
boldAllow text to be bold.
italicAllow text to be italic.
underlineAllow text to be underlined.
strikethroughAllow text to have a strikethrough.
subscriptAllow text to be subscript.
superscriptAllow text to be superscript.
unordered-listAllow the use of <ul> elements for an unordered list.
ordered-listAllow the use of <ol> elements for an unordered list.
blockquoteAllow text to be shown as a blockquote.
highlightAllow text to be highlighted.
codeAllow text to be shown as inline code.
code-blockAllow text to be shown as a code blocks.
hrAllow the use of a <hr> element for a horizontal rule.
line-breakAllow the use of a <br> element for a horizontal rule.
align-leftAllow text to be left-aligned.
align-centerAllow text to be center-aligned.
align-rightAllow text to be right-aligned.
align-justifyAllow text to be justify.
clear-formatAllow all formatting to be cleared.
undoAllow undo functionality.
redoAllow redo functionality.
htmlAllow raw editing of HTML, generated by the editor.
linkAllow text to be shown as a link.
imageAllow an image to be inserted.
iframeAllow the creation of <iframe> elements.
media-embedAllow embedding of videos and other remote content.
formattingAllow a dropdown for formatting options. See below for configuration.
tableAllow a dropdown for table options. See below for configuration.
{
    "buttons": ["italic", "bold", "undo", "redo"]
}

You can also provide this as an empty array, to disable buttons completely.

{
    "buttons": []
}

Formatting#

You can use the following options in the formatting options. Note that you'll also need to include formatting as a button in the buttons options.

OptionDescription
h1Allow the use of <h1> heading tags.
h2Allow the use of <h2> heading tags.
h3Allow the use of <h3> heading tags.
h4Allow the use of <h4> heading tags.
h5Allow the use of <h5> heading tags.
h6Allow the use of <h6> heading tags.
code-blockAllow text to be shown as code blocks.
blockquoteAllow text to be shown as a blockquote.
paragraphAllow text to be shown as a paragraph.
{
    "buttons": ["formatting", "bold", "italic"],
    "formatting": ["h2", "h3", "h4", "h5", "h6"]
}

Table#

You can use the following options in the table options. Note that you'll also need to include table as a button in the buttons options.

OptionDescription
insert-tableCreates the <table> element.
delete-tableRemoves the <table> element.
add-col-beforeAdds a column before the current cursor.
add-col-afterAdds a column after the current cursor.
delete-colRemoves the column at the current cursor.
add-row-beforeAdds a row before the current cursor.
add-row-afterAdds a row after the current cursor.
delete-rowRemoves the row at the current cursor.
merge-cellsMerges one or more cells.
split-cellsSplits one or more cells.
toggle-header-columnToggles the header column at the current cursor.
toggle-header-rowToggles the header row at the current cursor.
toggle-header-cellToggles the header cell at the current cursor.
{
    "buttons": ["table", "bold", "italic"],
    "table": ["insert-table", "delete-table", "add-col-before", "delete-col", "add-row-before", "delete-col"]
}

Commands#

You can use the any of the buttons values in the commands options to enable them in the Command Palette.

{
    "buttons": ["table", "bold", "italic"],
    "commands": ["table", "bold", "italic"]
}

Kitchen Sink#

The below is a "kitchen sink" example that contains everything.

{
    "buttons": ["html", "formatting", "h1", "h2", "h3", "h4", "h5", "h6", "bold", "italic", "underline", "strikethrough", "subscript", "superscript", "ordered-list", "unordered-list", "code-block", "hr", "highlight", "align-left", "align-right", "align-center", "align-justify", "clear-format", "line-break", "link", "image", "table", "media-embed", "iframe", "undo", "redo"],
    "formatting": ["paragraph", "code-block", "blockquote", "h1", "h2", "h3", "h4", "h5", "h6"],
    "table": ["insert-table", "delete-table", "add-col-before", "add-col-after", "delete-col", "add-row-before", "add-row-after", "delete-row", "merge-cells", "split-cells", "toggle-header-column", "toggle-header-row", "toggle-header-cell"],
    "toolbarFixed": true
}

Custom Buttons#

In addition to including or excluding available button, you can also define your own custom buttons that extend an existing Node or Mark. For example, you might want to create your own custom Paragraph node with specific attributes.

{
    "buttons": [
        "bold",
        "italic",
        {
            "svg": "h1", 
            "title": "Featured Heading 1", 
            "type": "heading", 
            "attrs": {"level": "1", "class": "feature-heading"},
            "editorStyle": ".feature-heading { color: red; }"
        }
    ],
    "formatting": [
        {
            "svg": "<svg ... />", 
            "title": "Lead", 
            "type": "paragraph", 
            "attrs": {"class": "lead-text", "data-name": "lead-text"}
        },
        "paragraph"
    ]
}
OptionDescription
svgA named SVG that Vizy already uses, or a raw <svg> icon.
titleWhat the button or dropdown item should be labelled as.
typePick an existing Node or Mark to extend from, (e.g. paragraph, bold, heading, etc).
attrsAny attributes to be stored against the node/mark. These will be rendered as HTML attributes.
editorStyleAny CSS that will be applied to the node while in the control panel. This will not be applied on the front-end.

These definitions can be included at the top-level, or within the formatting dropdown.

Previous ← Requirements Next What is Vizy? →