Create and use custom StyleBooks
You can write your own StyleBook for your deployment, import it to NetScaler Console, and create configuration objects. You can also use APIs to create configurations from your StyleBooks.
This document includes the following information:
Before you begin
Before you begin creating StyleBooks, make sure you have knowledge of the following:
-
NITRO API. For more information, see NITRO API documentation.
-
YAML
StyleBook files use the YAML format. For information about the YAML format, see YAML Syntax.
The following is a list of YAML guidelines you must be aware of while creating StyleBooks:
- YAML is case sensitive.
- YAML requires proper indentation
- Use the
<spacebar>key to create proper indentation. Do not use the<tab>key. Using the<tab>key creates compilation error while importing your StyleBook to MA Service. - Do not use strings within quotation marks. Include the string within quotation marks only if a string has punctuation marks (dashes, colons, and so on.) If you want to interpret a number as a string, either include the number within quotation marks or use the str() built-in function of StyleBooks.
-
Literals like YES/Yes/yes/Y/y/NO/no/No/n/N, ON/On/on/OFF/Off/off, and TRUE/true/truthy/FALSE/False/false/falsely are considered Booleans, and are equivalent to true and false respectively. To interpret them as strings, include them within quotation marks. For example:
- “YES”
- “No”
- “True”
- “False” and so on.
Note
Before importing your StyleBook file into NetScaler Console, it is recommended that you validate if your file is compliant with the YAML format. Citrix recommends that you use the built-in YAML validator in StyleBooks to validate and import the YAML content.
For more information, see NITRO APIs documentation.
Anatomy of a StyleBook
Writing StyleBooks requires that you understand the grammar, syntax, and structure of StyleBooks. A typical StyleBook has the following sections:
- Header: This section lets you define the identity of a StyleBook and describe what it does. This is a mandatory section.
- Import StyleBooks: This section lets you declare which other StyleBook you want to refer to from your current StyleBook. Importing NetScaler NITRO configuration StyleBooks or other StyleBooks is required to write a StyleBook. This is a mandatory section.
- Parameters: This section lets you define the parameters you require in your StyleBook to create a configuration. It describes the input that your StyleBook takes. This is an optional section.
-
Components: This section lets you define the entities (configuration objects) that are created by the StyleBook for a specific configuration. This section is considered as the core of a StyleBook. Components generally use the input provided in the parameters section to adapt the configuration generated by the StyleBook. This is an optional section.
A StyleBook may have a parameters section, or a components section, or both. A StyleBook with only the parameters section is useful to define a list of parameters that can be used by other StyleBooks. This promotes reusability of parameter groups across a set of StyleBooks. A StyleBook with only a components section may be used when you want to specify the values for attributes in the StyleBook instead of defining parameters to take user input. - Outputs: While the parameters section defines the inputs of the StyleBook, this optional section defines its outputs. In this optional outputs section, you can specify the components that you want to expose to users creating a configuration from this StyleBook and to other StyleBooks that import this StyleBook. Users and importing StyleBooks can then reference the properties of the exposed components.
- Operations: A StyleBook may contain an optional section to enable Analytics in NetScaler Console on any virtual server that is part of the StyleBook.
The following figure shows a simple outline of a StyleBook.
The following examples help you learn about the grammar and structure of a StyleBook and how to write StyleBooks with increasing levels of complexity.