Template IDE Hints

The extension allows you to utilize specially formatted Antlers comments to improve code completion, suggestions, provide inline documentation, and other advanced features. The extension is capable of determining which blueprint fields to show in suggestions based on common collection configurations, but there are some scenarios where explicitly specifying them can improve your development experience.

Template and Partial Names and Descriptions

To provide a name, or description, for your partial, you must include an Antlers comment as the first item in your Antlers template. Within this comment you can prefix a line with @name to specify the partial name, and another line with @desc to provide a description:

1{{#
2 @name The template name.
3 @desc A human-friendly description for your awesome template.
4#}}
5 
6The rest of your awesome Antlers template.

When the a user is using the {{ partial }} tag, they will see the human-friendly names and descriptions as part of the suggestions:

User Friendly Descriptions

Specifying Collections or Blueprints

You can explicitly set the collection or blueprint names that apply to any template file within your Statamic project. These must appear within an Antlers comment as the first item in your Antlers template. When the extension sees these hints, it will pull in the relevant blueprint fields to improve suggestions and syntax highlighting.

Specifying the Entry (or Collection)

You may specify the collection name by using either the @entry or @collection directive (use whichever feels best for you as they are equivalent):

1{{#
2 @name The template name.
3 @desc A human-friendly description for your awesome template.
4 @entry collectionName
5 @collection collectionName
6#}}
7 
8The rest of your awesome Antlers template.

You can specify multiple collections by separating each name with a comma:

1{{#
2 @name The template name.
3 @desc A human-friendly description for your awesome template.
4 @entry collectionOne, collectionTwo
5#}}
6 
7The rest of your awesome Antlers template.

Specifying the Blueprint(s)

You may specify which blueprint(s) apply to any template file by using the @blueprint directive:

1{{#
2 @name The template name.
3 @desc A human-friendly description for your awesome template.
4 @blueprint blueprintName
5#}}
6 
7The rest of your awesome Antlers template.

You may specify multiple blueprints by separating each name with a comma:

1{{#
2 @name The template name.
3 @desc A human-friendly description for your awesome template.
4 @blueprint blueprintOne, blueprintTwo
5#}}
6 
7The rest of your awesome Antlers template.

Specifying Bard or Replicator Sets

If you are dynamically loading a partial based on a set type (such as when creating templates for a Bard or Replicator field), you can specify which set within the corresponding blueprint applies to a file by using the special @set directive:

1{{#
2 @name The template name.
3 @desc A human-friendly description for your awesome template.
4 @set collectionName.fieldName.setName
5#}}
6 
7The rest of your awesome Antlers template.

When the extension sees the special @set directive, it will load all the relevant blueprint fields only from that set to improve your suggestions and syntax highlighting.

Type Hinting Variables

Similar to the @set directive, you may type-hint variables within your Antlers template by adding a comment on the line preceding your usage of the variable by using the @var directive followed by the variable name, the collection (or blueprint name), and the field within the collection or blueprint that applies to the variable:

1<p>
2 {{# @var some_variable collectionName.fieldName #}}
3 {{ some_variable }}
4</p>

With the variable type-hint in place, the extension will now use whatever field reference you specify when determining suggestions, performing project analysis, and other advanced behind-the-scenes things.

You will rarely have to utilize the @var directive, but it can be a life-saver if you're doing complicated things with augmentation, view-models, or are dynamically injecting variables through some other method and want to keep your suggestions working.