= Macros
:doctitle:    Macros
:description: http://asciidoc.org/userguide.html#_macros
include::attributes.asciidoc[]
:navinfo2:


== Linking to Local Documents

[role="lead"]
Hypertext links to files on the local file system are specified using the link inline macro.

  link:<target>[<caption>]

The 'link' macro generates relative URLs. The link macro `<target>` is
the target file name (relative to the file system location of the
referring document). The optional `<caption>` is the link's displayed
text. If `<caption>` is not specified then `<target>` is displayed.

====
----
link:get-started.html[]
----
====
Renders:

link:get-started.html[]

====
----
link:get-started.html[Start]
----
====
Renders:

link:get-started.html[Start]

If you want more enhancement and focus on specific link, you want probably to use buttons links
as provided by Bootstrap.

It's now possible with this major version 3 of AsciiDoc-Bootstrap backend.

Let's restart our example, with the single link, and apply it a button style.

====
----
link:get-started.html[role="primary"]
----
====
Renders:

ifdef::basebackend-bootstrap[]
link:get-started.html[role="primary"]
endif::[]


Change the text

====
----
link:get-started.html["Start Tour",role="primary"]
----
or with alternative
----
link:get-started.html[caption="Start Tour",role="primary"]
----
====
Renders:

ifdef::basebackend-bootstrap[]
link:get-started.html["Start Tour",role="primary"]
endif::[]

NOTE: You have certainly understood that all button color style may be applied with the `role` attribute.
(*inverse*, *default*, *primary*, *info*, *success*, *warning*, *danger*).

You want probably more than just a button. Adding an icon will improve again more the look and feel !

====
----
link:get-started.html["Start Tour",role="info",icon="glyphicon-play-circle"]
----
====
Renders:

ifdef::basebackend-bootstrap[]
link:get-started.html["Start Tour",role="info",icon="glyphicon-play-circle"]
endif::[]

And finally, choose what side you want to put your icon.

====
----
link:get-started.html["Whats wrong",role="danger",icon="glyphicon-remove-circle",options="right,white"]
----
====
Renders:

ifdef::basebackend-bootstrap[]
link:get-started.html["Whats wrong",role="danger",icon="glyphicon-remove-circle",options="right,white"]
endif::[]

== Images

[role="lead"]
Inline images are inserted into the output document using the 'image' macro.

  image:<target>[<attributes>]

The contents of the image file `<target>` is displayed.

.Image macro attributes
- The optional 'options' attribute with value *responsive* provides a way for [label label-info]#Bootstrap 3#
to fluid IMG size. Images are not responsive by default.

====
----
image::screenshots/navbar-default-sample.png[role="thumbnail",options="align,responsive"]
----
====
Renders:

ifdef::basebackend-bootstrap[]
image::screenshots/navbar-default-sample.png[role="thumbnail",options="align,responsive"]
endif::basebackend-bootstrap[]

ifdef::basebackend-docbook[]
image:screenshots/navbar-default-sample.png[scale="50"]
endif::basebackend-docbook[]

Try several resolution and see what happens with or without responsive option.

== Icons

[role="lead"]
AsciiDoc-Bootstrap backend 3.1.0 introduces a new inline macro
for inserting an icon at an arbitrary place in paragraph content.

NOTE: Credit to AsciiDoctor https://github.com/asciidoctor/asciidoctor/issues/529[GH-529 issue].

IMPORTANT: AsciiDoc-Bootstrap backend 4.0 has dropped this icon inline macro, to keep a better compatibility
with other backends. Use then the image inline macro with additional attributes.

Right now we are blessed with many icon fonts that continue to grow with every release,
like http://glyphicons.com/[Glyphicons], http://fontawesome.io[Font-Awesome],
http://ionicons.com/[Ionicons], and more again ...

AsciiDoc-Bootstrap backend 4.0 support these three icon fonts.
Valid `iconsfont` attribute values are : *glyphicon*, *font-awesome*, and *ionicons*.

[CAUTION]
=====================================================================
Our inline image macro is similar to the standard Asciidoc inline image macro with one exception:

* If the `iconsfont` attribute is set, the macro will translate image to a font-based icon result.
=====================================================================

  image:<target>[<attributes>]

The contents of the image `<target>` is displayed.

.Our Image macro attributes
- The required 'iconsfont' attribute tells which icons font to use.
Possibles values are : *glyphicon*, *font-awesome*, *ionicons*.
- The optional 'size' attribute scales the icon.
Possible values are : *lg* (33% increase), *2x*, *3x*, *4x*, *5x*, *6x*, *7x*, *8x*, *9x*.

.Standard Image macro attributes
- The optional 'title' attribute provides a title for the icon.
- The optional 'width' and 'height' attributes scale the icon (image in png format)
size and can be used in any combination. The units are pixels and default values are 48.

Here is an example that inserts a calendar icon in front of a blog entry and its published date.
====
----
image:icons/font-awesome/calendar.png[alt="calendar",icon="calendar",size="4x",iconsfont="font-awesome"] by Laurent Laville, published on November 21, 2013
----
====
Renders:

image:icons/font-awesome/calendar.png[alt="calendar",icon="calendar",size="4x",iconsfont="font-awesome"] by Laurent Laville, published on November 21, 2013

WARNING: AsciiDoc-Bootstrap 4.0 did not used anymore the open block to simulate multi-columns.
We used now the standard Bootstrap classes `col-md-*` and so on.

Here is another example that display two columns on medium device (greater than 992 pixels)

.AsciiDoc Code
....
include::macros.columns-1.asciidoc[]
....
unfloat::[]
include::macros.columns-1.asciidoc[]

And another example with three columns on medium device (greater than 992 pixels)

.AsciiDoc Code
....
include::macros.columns-2.asciidoc[]
....
unfloat::[]
include::macros.columns-2.asciidoc[]


WARNING: All icon fonts do not support same icon names. Be carefull if you switch to another icons font.

== Progress bars

[role="lead"]
AsciiDoc-Bootstrap backend 4.0.0 introduces a new inline macro
that implement the Bootstrap Progress Component.

WARNING: Stacked progress bar is not supported.

    progess:<target>[<attributes>]

The contents of the progress `<target>` is used to draw percent of progress bar completed
(Must be numeric and between 0 and 100).

.Progress macro attributes
- The optional 'caption' attribute is the progress bar label.
- The optional 'role' attribute is used as contextual class. Should be either `info`, `success`, `warning`, or `danger`.
- The optional 'striped' attribute, with an empty content, is used to display http://getbootstrap.com/components/#progress-striped[striped effect progress bar].
- The optional 'animated' attribute, with an empty content, is used to display http://getbootstrap.com/components/#progress-animated[animated effect progress bar].

WARNING: There is no fallback strategy to build a progress bar with `html5` or any other backends.

ifdef::basebackend-bootstrap[]

Here are few examples :

.Default progress bar at 55% complete
progress:55[]

.Progress bar with label
progress:60[caption="60%"]

.Progress bar with contextual class
progress:50[role="success"]

See link:progress.html[more] examples.

endif::basebackend-bootstrap[]