= Asciidoc Extension

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

The `AsciiDoc` value type is intended to render HTML markup that is authored using https://asciidoctor.org/[AsciiDoc] markup language.

A common use case is to render help pages or technical manuals.


[NOTE]
====
Although properties of this type can be edited, the xref:vw::about.adoc[Wicket viewer] does not provide any specialized authoring environment.
It is therefore most suitable for read-only values.
====

== Setup

=== Dependency Management

In your application's top level `pom.xml`, add a dependency for this module's own bill of materials (BOM):

[source,xml,subs="attributes+"]
.pom.xml
----
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.causeway.valuetypes</groupId>
            <artifactId>causeway-valuetypes-asciidoc</artifactId>
            <scope>import</scope>
            <type>pom</type>
            <version>{page-causewayprevv2}</version>
        </dependency>
    </dependencies>
</dependencyManagement>
----

=== Dependencies / Imports

In those modules where there are domain objects that use the `AsciiDoc` value type:

* add this dependency:
+
[source,xml,subs="attributes+"]
.pom.xml
----
<dependencies>
    <dependency>
        <groupId>org.apache.causeway.valuetypes</groupId>
        <artifactId>causeway-valuetypes-asciidoc-applib</artifactId>
    </dependency>
</dependencies>
----

* and `@Import` this module:
+
[source,java]
.MyModule.java
----
@Configuration
@Import({
    CausewayModuleValAsciiDocApplib.class,
    // ...
})
public class MyModule { ... }
----

In addition, in the webapp module of your application, add the following dependencies:

* for the Wicket viewer:
+
[source,xml]
.pom.xml
----
<dependency>
    <groupId>org.apache.causeway.valuetypes</groupId>
    <artifactId>causeway-valuetypes-asciidoc-ui-wkt</artifactId>
</dependency>
----

* and for persistence:
+
[source,xml]
.pom.xml
----
<dependency>
    <groupId>org.apache.causeway.valuetypes</groupId>
    <artifactId>causeway-valuetypes-asciidoc-xxx</artifactId>   <!--.-->
</dependency>
----
<.> where `xxx` is `jpa` (if using xref:pjpa::about.adoc[]) or `jdo` (if using xref:pjdo::about.adoc[]).

And in your application's xref:userguide::modules.adoc#appmanifest[App Manifest], import the extension's implementation module:

[source,java]
.AppManifest.java
----
@Configuration
@Import({
        CausewayModuleValAsciidocUiWkt.class,
        CausewayModuleValAsciidocPersistenceXxx.class,  <!--.-->
        ...
})
public class AppManifest {
}
----
<.> where `Xxx` is `Jpa` (if using xref:pjpa::about.adoc[]) or `Jdo` (if using xref:pjdo::about.adoc[]).


== Usage

The property can be declared and used in both entities and view models.
If declared in an entity, then it should most likely be mapped to a CLOB:

* if declared in an xref:pjpa::[JPA] entity:
+
[source,java]
----
@Property
@PropertyLayout
@Column(nullable = false) @Lob @Basic(fetch=FetchType.LAZY) // <.>
@Getter @Setter
private AsciiDoc helpText;
----
<.> maps to a (c)lob

* if declared in an xref:pjdo::[JDO] entity:
+
[source,java]
----
@Property
@PropertyLayout
@Column(allowsNull = "false", jdbcType = "CLOB")        // <.>
@Getter @Setter
private AsciiDoc helpText;
----
<.> maps to a CLOB

* if declared in a JAXB view model:
+
[source,java]
----
@Property
@PropertyLayout
@XmlElement(required = true)
@Getter @Setter
private AsciiDoc helpText;
----

