Creating a dictionary

Pro

Click Create on Dictionaries, give the dictionary a label, and choose a Key (up to 64 characters of lowercase letters, numbers, hyphens and underscores; it can't start with an underscore). The key is permanent.

Adding entries

Each entry is a Label and a Value. Keep values stable once content uses them, because changing a value doesn't update posts that already stored the old one. Change labels freely.

How you edit entries depends on the size of the list:

• Short lists use a row editor, where you can drag entries into order.
• Lists over 200 entries switch to a plain text view with one label|value pair per line.
• Past 1,000 entries, the editor works a page at a time. Search still covers the whole dictionary, but drag-to-reorder is off, and you need to save a page before moving to another page or changing the search.

A dictionary can hold up to 50,000 entries.

Importing and exporting entries

Bulk import accepts plain text or CSV files up to 20 MB, in two modes:

• Append adds new values, and updates the labels of values that already exist.
• Replace all entries discards the current list and uses the file instead.

Export CSV downloads the entries. It's your backup before a Replace.

Using a dictionary in a field

In a choice field (Select, Multiselect, Checkboxes or Radio Buttons), set the choices source to the dictionary instead of typing choices. The field then always offers the dictionary's current entries. Button Group fields only take typed choices, and can't use a dictionary.

Editing at the same time as someone else

If someone saves the dictionary while you have it open, your save is refused rather than silently overwriting theirs. Reload and make your change again.

Deleting a dictionary

Before you confirm, VX lists every field that uses the dictionary, grouped by fieldset. After deletion, those fields switch to an empty list of typed choices; relink them to another dictionary or type the choices in. Values already stored on posts aren't changed.

Warning

Replace all entries and Delete can't be undone from the dictionary screen. Export the entries first.

Technical details for LLMs

• Key rules: ^[a-z0-9_-]+$, max 64, no leading _, not the key of a system dictionary.
• Storage: database dictionaries keep entries in {prefix}vx_dictionary_entries; code-defined dictionaries (PHP or JSON) carry entries inside their config and are read-only until overridden to the database.
• Field linking: choices_source: "dictionary" with dictionary: "<key>", or choices_source: "system_dictionary" with system_dictionary: "<key>". button_group supports manual choices only.
• Abilities: vx-framework/list-dictionaries, vx-framework/get-dictionary-entries (paged, searchable), vx-framework/create-dictionary, vx-framework/update-dictionary, vx-framework/set-dictionary-entries, vx-framework/delete-dictionary. All require the dictionary module (Pro, active license).
• Concurrent saves are refused on a stale version guard rather than merged.
• Delete fires vxframework/dictionary/before_delete and clears the reference from every linked field.