Creating a static guide in the multipane layout
Add the file includes in the asciidoc for files that you want to appear on the right column, with role="code_column" specified for each file. The files included with role="code_column" will be shown in full screen view while the files included already in the guide will be shown in the mobile/single column view where there is no code column. The code column on the right is exactly 90 characters per line and remains a constant width when resizing the width of the browser, so that the code can be written once and always work. The guide column grows and shrinks according to the width of the browser.
The file name should be provided above the file include. The linenums attribute is important for the hotspots (described below) to work.
SystemApplication.java
[source,java,linenums,role='code_column']
-----
include::finish/src/main/java/io/openliberty/guides/rest/SystemApplication.java[tags=**;!comment]
-----
For code blocks that are a command, use role='command':
[role="command"]
-----
git clone https://github.com/openliberty/guide-rest-intro.git
cd guide-rest-intro
-----
For code blocks that are a command referring to creating the code file on the right, use role='code_command':
[role="code_command"]
-----
Create the JAX-RS application class in the src/main/java/io/openliberty/guides/rest/SystemApplication.java file:
-----
Code on the right can be highlighted when hovering over certain "hotspots" in the guide. These hotspots can be just text or also a code command, and can be specified using the role='hotspot'. Hotspots can be specified to highlight either a range of lines or to highlight a tag in the file.
To specify what lines to highlight when hovering over the hotspot, use the role="hotspot=<start line>-<end line>" in the attributes of the code block:
Text hotspot example:
[role="hotspot=1-12"]
-----
EndpointTest.java
-----
Code command hotspot example:
[role="code_command hotspot=1-12"]
-----
Edit the `src/main/liberty/config/server.xml` file to update the placeholder text to be:
-----
Inline hotspot example:
----
The [hotspot=1-5]@Inject annotation indicates a dependency injection.
You are injecting your InventoryManager bean into the InventoryResource class.
This injects the bean in its specified context (application-scoped) and makes all of its functionalities
available without the need of instantiating it yourself.
----
This will highlight the lines 1-12 on the right column when hovering over this block. In mobile view, instead of the code column on the right being shown, these lines will be shown instead (right after where the hotspot is).
To highlight code surrounded by tags in the included code file, just put the name of the tag on the hotspot. For example:
----
The [hotspot=dependencies file=1]`dependencies` section defines what is needed to compile and
test the code.
----
This will highlight all of the lines between the open tag: // tag::dependencies[] and the closing tag: // end::dependencies[] in the file.
To enable tag hotspots in the guide, you will need to make sure that the tags are not limited in the include statement in the README.adoc file. As you see below, the brackets after build.gradle in the include statement are empty which enables the UI to load the tags and allow them to be highlighted.
build.gradle
[source, gradle, linenums, role='code_column']
----
include::finish/build.gradle[]
----
If you wish to still omit a tag from showing up in the guide but want to use hotspots that highlight a tag, then you can add hide_tags=<tag_name1,tag_name2> to the role of the included source:
----
server.xml
[source, xml, linenums, role='code_column hide_tags=simple-config,preflight-config']
----
include::finish/src/main/liberty/config/server.xml[]
----
This will load the server.xml file into the guide but hide the simple-config tag and the preflight-config tag.
You can also specify a hotspot to switch to a file but not highlight it, by just adding hotspot instead of hotspot=<start line>-<end line>.
For example:
----
The [hotspot]@Inject annotation indicates a dependency injection.
You are injecting your InventoryManager bean into the InventoryResource class.
This injects the bean in its specified context (application-scoped) and makes all of its functionalities
available without the need of instantiating it yourself.
----
By default the hotspots will switch to the first file in its section, to override this behavior add file=<file number>.
For example:
Each test case tries to first assert that with a valid authorization header, it can get a [hotspot=39-40 file=1]`Status.OK` code from the response.
The test fails if the response returns a [hotspot=`Status.FORBIDDEN` message, which means the authorization header is invalid.
You can specify one hotspot to highlight multiple ranges of code by adding multiple hotspot tags:
You have just added roles-based access control to the `InventoryResource` class.
Similarly, for each specific service, the [hotspot=25 hotspot=49]`@RolesAllowed` annotation sets which roles are allowed to access it. Therefore, the inventory service is properly secured, as well.
For the Getting started / Maven and other included asciidocs that need to be styled, add [role='command'] above it to style it as a command.
-----
[role="command"]
include::{common-includes}/gitclone.adoc[]
-----
Add include::{common-includes}/attribution.adoc[subs="attributes"] at the bottom of the guide somewhere to include the common guide attribution. Specify who the guide is attributed to in the guide-author front-matter variable. By default use :guide-author: Open Liberty
At the end of the guide, there are various links to different related documentation in the design. These can be specified in a section named "Related Links" in the asciidoc.
== Related Links Dive into the MicroProfile config.
https://github.com/microprofile[See MicroProfile Config specs (GitHub)]