Seite 3: Zusätzliche Parameter

Angesichts der flexiblen Fähigkeiten von Asciidoctor sind unterschiedliche Ansätze denkbar, zusätzliche Optionen beizusteuern. Für das einfache Beispiel soll der optionale Parameter ?pdf=true hinter der URL kennzeichnen, dass das Servlet die Datei nach PDF transformieren soll. Der Code dafür ist in der Methode processRequest umgesetzt:

String pdf = request.getParameter(PDF);

if(null != pdf && 
   pdf.equalsIgnoreCase(Boolean.TRUE.toString())) 
{
  File pdffile = new File(adocfile.getParentFile(), 
                          fname + DOT + PDF);
  if(!pdffile.exists() || adocfile.lastModified() 
     > pdffile.lastModified()) 
  {
    transform(absname, PDF);
  }
}

// .. die transformierte Datei ausgeben ..

Der folgende Code überlädt die Methode transform, um den optionalen Parameter für das Backend verarbeiten zu können:

private void transform(String fileName) {
  transform(fileName, null);
}

private void transform(String fileName, String backend) {
  Map<String, Object> attributes = new HashMap<>();
  attributes.put("no_footer", false);
  attributes.put("source_highlighter", "highlightjs");

  Map<String, Object> options = new HashMap<>();
  options.put("attributes", attributes);
  options.put("in_place", false);
  if(null != backend) {
    options.put("backend", backend);
  }
   Asciidoctor asciidoctor = create();
  asciidoctor.convertFile(new File(fileName), options);
}

Die Transformation erfolgt wahlweise nach HTML oder PDF. In beiden Fällen gibt das Servlet im Anschluss den umgewandelten Inhalt an den Browser zurück. Auf dem Server liegt nach der Umwandlung zusätzlich die HTML- oder PDF-Version der .adoc-Datei mit der Endung .html oder .pdf, die der Server bei weiteren Aufrufen derselben URL ohne erneute Wandlung ausgibt.

Auf die Startrampe

Die Tomcat-Dokumentation beschreibt das Element Context als Repräsentation einer Webanwendung, die innerhalb eines bestimmten virtuellen Host läuft. Jede Webanwendung basiert auf einer .war-Datei oder einem zugehörigen Verzeichnis, das die entpackten Inhalte enthält.

Die Funktion des Asciidoctor-Servlets lässt sich im Deployment Descriptor der Datei web.xml eines Context mit folgendem Eintrag aktivieren:

<servlet>
  <servlet-name>AdocServlet</servlet-name>
  <servlet-class>de.uhilger.wbx.web.AdocServlet
  </servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>AdocServlet</servlet-name>
  <url-pattern>*.adoc</url-pattern>
</servlet-mapping>

Alle Aufrufe von Inhalten mit der Endung .adoc für diesen Context landen auf die Weise beim Servlet. Die gesamte Funktion von Asciidoctor ist damit in der betreffenden Webanwendung aktiviert und an Inhalte mit der Endung .adoc gebunden.

Eine Frage des Stils

Mit Asciidoctor erzeugte Dokumente erhalten ihre Gestaltung von einem Cascading Stylesheet (CSS). Dem Installationspaket liegt, wie anfangs erwähnt, ein vorgefertigtes Stylesheet bei. Wenn Asciidoctor eine HTML-Datei erstellt, enthält diese den Standardverweis ./asciidoctor.css. Damit erwartet der Browser das Stylesheet am selben Ort wie die HTML-Datei.

Asciidoctor erstellt jedoch kein eigenes Stylesheet beim Generieren der HTML-Datei. Entwickler müssen dafür sorgen, dass es an geeigneter Stelle zu finden ist. Gewöhnlich ist das Stylesheet zentral gespeichert, damit alle HTML-Dokumente es verwenden können. Liegt das Stylesheet beispielsweise im Stammverzeichnis / einer Domain, können es alle Dokumente dieser Domain unabhängig von ihrem Ablageort einbinden. Entwickler können auf solch ein Stylesheet mit den Parametern stylesheet und stylesdir folgendermaßen verweisen:

:stylesheet: asciidoctor.css
:stylesdir: /

Aus den Parametern im Header der Dokumente bezieht Asciidoctor den Pfad zum Stylesheet, das für die HTML-Ausgabe zum Einsatz kommt. Auf Tomcat wäre der Ablageort des Stylesheets im konkreten Fall CATALINA_BASE/webapps/ROOT/asciidoctor.css.

Mit den beschriebenen Schritten ist Asciidoctor auf dem Server in Betrieb. Der Server wandelt aus jedem Context, für den das Servlet wie beschrieben aktiviert ist, .adoc-Dateien in HTML um:

http://example.com/contextname/pfad/zum/textbeitrag.adoc

Der zusätzliche Parameter ?pdf=true bewirkt, dass der Server ein PDF statt einer HTML-Datei erzeugt:

http://.../textbeitrag.adoc?pdf=true

Die .adoc-Dateien können auf unterschiedliche Weise auf den Server gelangen. Nutzer können sie zunächst offline mit einem Texteditor oder einer anderen Anwendung erstellen und anschließend auf den Server kopieren. Alternativ verwenden sie einen Editor wie Codemirror in einer Webanwendung.

Unabhängig davon wandelt das Servlet die Dateien automatisch beim Aufruf in HTML um. Das Asciidoctor-Servlet lässt sich auf dieselbe Weise mit anderen Java-Webservern wie Jetty, Glassfish, Wildfly, JBoss, Geronimo, TomEE, Websphere, Weblogic oder Payara einsetzen.