options.adoc 3.74 KB
Newer Older
1
= Options Attribute
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

The `options` attribute is a versatile xref:positional-and-named-attributes.adoc#named[named attribute] that can be assigned one or more values.
It can be defined globally as document attribute as well as a block attribute on an individual block.

== Assign options to blocks

You can assign one or more options to a block using the shorthand or formal syntax for the `options` attribute.

=== Shorthand options syntax for blocks

To assign an option to a block, prefix the value with a percent sign (`%`) in an attribute list.
The percent sign implicitly sets the `options` attribute.

.Sidebar block with an option assigned using the shorthand dot
[source#ex-block]
----
[%value]
****
This is a sidebar with an option assigned to it.
****
----

You can assign multiple options to a block by prefixing each value with a percent sign (`%`).

.Sidebar with two options assigned using the shorthand dot
[source#ex-two-options]
----
[%value%value]
****
This is a sidebar with two options assigned to it.
****
----

For instance, consider a table with the three built-in option values, `header`, `footer`, and `autowidth`, assigned to it.
<<ex-table-short>> shows how the values are assigned using the shorthand notation.

38
.Table with three options assigned using the shorthand syntax
39
40
[source#ex-table-short]
----
41
[%header%footer%autowidth,cols=2*~]
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|===
|Cell A1 |Cell B1

|Cell A2 |Cell B2

|Cell A3 |Cell B3
|===
----

=== Formal options syntax for blocks

Explicitly set `options` or `opts`, followed by the equals sign (`=`), and then the value in an attribute list.

.Sidebar block with an option assigned using the formal syntax
[source#ex-block-formal]
----
[options="value"]
****
This is a sidebar with an option assigned to it.
****
----

Separate multiple option values with commas (`,`).

.Sidebar with three options assigned using the formal syntax
[source#ex-three-roles-formal]
----
[options="value,value,value"]
****
This is a sidebar with three options assigned to it.
****
----

Let's revisit the table in <<ex-table-short>> that has the three built-in option values, `header`, `footer`, and `autowidth`, assigned to it using the shorthand notation (`%`).
Instead of using the shorthand notation, <<ex-table-formal>> shows how the values are assigned using the formal syntax.

78
.Table with three options assigned using the formal syntax
79
80
[source#ex-table-formal]
----
81
[cols=2*~,options="header,footer,autowidth"]
82
83
84
85
86
87
88
89
90
91
92
93
|===
|Cell A1 |Cell B1

|Cell A2 |Cell B2

|Cell A3 |Cell B3
|===
----

== Using options with other attributes

Let's consider `options` when combined with other attributes.
94
The following example shows how to structure an attribute list when you have style, role, and options attributes.
95
96
97
98
99
100
101
102

.Shorthand
[source]
----
[horizontal.properties%step] <.> <.> <.>
property 1:: does stuff
property 2:: does different stuff
----
103
104
<.> xref:blocks:styles.adoc[The block style attribute], declared as `horizontal` in this example, is a positional attribute.
A block style value is always placed at the start of the attribute list.
105
106
107
108
109
110
111
112
113
114
115
116
117
118
<.> `properties` is prefixed with a dot (`.`), signifying that it's assigned to the xref:roles.adoc[role attribute].
The role and options attributes can be set in either order, i.e., `[horizontal%step.properties]`.
<.> The percent sign (`%`) sets the `options` attribute and assigns the `step` value to it.

When you use the formal syntax, the positional and named attributes are separated by commas (`,`).

.Formal
[source]
----
[horizontal,role="properties", options="step"] <.>
property 1:: does stuff
property 2:: does different stuff
----
<.> Like in the shorthand example, named attributes such as `role` and `options` can be set in any order in the attribute list once any xref:positional-and-named-attributes.adoc#positional[positional attributes] are set.