Purpose #
Annotations let snippet authors add human-readable descriptions and type hints to config variables. GOCSM reads these annotations and uses them to label the config panel inputs and (in v2) render appropriate input types.
Syntax #
Place a docblock annotation immediately above the declaration:
/** @config <type>[:<params>] <description> */
$variable = default_value;For CSS, use a block comment inside the config rule. Both /* */ and /** */ work:
/** @config <type>[:<params>] <description> */
--property-name: value;Reserved annotation types #
| Type | Intended input (v1: text, v2: typed) |
|---|---|
string |
Plain text input |
int |
Integer input |
float |
Decimal input |
bool |
Checkbox or toggle |
email |
Email input |
url |
URL input |
select |
Select input |
multiselect |
Multi-select input |
gf_form |
Gravity Forms form selector |
gf_field |
Gravity Forms field selector |
post_id |
Post selector |
user_id |
User selector |
page_id |
Page selector |
array |
Array input |
object |
Object input |
color |
Color picker |
In v1, all annotated variables render as plain text inputs regardless of the declared type. The type is stored in the database and will drive typed UI in a future release.
Example #
// === BEGIN CONFIG ===
/** @config int The Gravity Forms form ID to listen on */
$form_id = 5;
/** @config email Address to receive notification emails */
const NOTIFY_EMAIL = 'admin@example.com';
/** @config bool Enable debug logging */
$debug = false;
// === END CONFIG ===Variables without annotations #
Config variables without an @config annotation are still shown in the config panel with their variable name as the label. Annotations are optional but recommended for clarity.
