From 00096ccb2b3d2715087446fb553c49050feee392 Mon Sep 17 00:00:00 2001 From: Jeremy Stretch Date: Mon, 17 Jul 2023 14:50:57 -0400 Subject: [PATCH] Update custom fields documentation --- docs/customization/custom-fields.md | 2 +- docs/models/extras/customfield.md | 4 ++-- docs/models/extras/customfieldchoiceset.md | 17 +++++++++++++++++ 3 files changed, 20 insertions(+), 3 deletions(-) create mode 100644 docs/models/extras/customfieldchoiceset.md diff --git a/docs/customization/custom-fields.md b/docs/customization/custom-fields.md index 612faefed..1e0d5c31e 100644 --- a/docs/customization/custom-fields.md +++ b/docs/customization/custom-fields.md @@ -60,7 +60,7 @@ NetBox supports limited custom validation for custom field values. Following are ### Custom Selection Fields -Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible. +Each custom selection field must designate a [choice set](../models/extras/customfieldchoiceset.md) containing at least two choices. These are specified as a comma-separated list. If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected. diff --git a/docs/models/extras/customfield.md b/docs/models/extras/customfield.md index df0408f7c..bf0c4755a 100644 --- a/docs/models/extras/customfield.md +++ b/docs/models/extras/customfield.md @@ -79,9 +79,9 @@ Controls how and whether the custom field is displayed within the NetBox user in The default value to populate for the custom field when creating new objects (optional). This value must be expressed as JSON. If this is a choice or multi-choice field, this must be one of the available choices. -### Choices +### Choice Set -For choice and multi-choice custom fields only. A comma-delimited list of the available choices. +For selection and multi-select custom fields only, this is the [set of choices](./customfieldchoiceset.md) which are valid for the field. ### Cloneable diff --git a/docs/models/extras/customfieldchoiceset.md b/docs/models/extras/customfieldchoiceset.md new file mode 100644 index 000000000..8fa30cfc7 --- /dev/null +++ b/docs/models/extras/customfieldchoiceset.md @@ -0,0 +1,17 @@ +# Custom Field Choice Sets + +Single- and multi-selection [custom fields documentation](../../customization/custom-fields.md) must define a set of valid choices from which the user may choose when defining the field value. These choices are defined as sets that may be reused among multiple custom fields. + +## Fields + +### Name + +The human-friendly name of the choice set. + +### Extra Choices + +The list of valid choices, entered as a comma-separated list. + +### Order Alphabetically + +If enabled, the choices list will be automatically ordered alphabetically. If disabled, choices will appear in the order in which they were defined.