src/site/markdown/usage.md.vm

#set($h1 = '#')
#set($h2 = '##')
#set($h3 = '###')
#set($h4 = '####')


$h2 Usage

The plugin can be used either as a regular Maven plugin or as a BND plugin.

No matter which approach you choose, the plugin will by default look for scripts in two project directories:

  1. `src/main/scripts` - this folder will contain scripts that will be pre-compiled
  2. `src/main/resources/javax.script` - this folder will contain scripts that will be embedded as is

The structure in these source directories should then follow the normal way of structuring scripts in an Apache Sling application. For more
details, check the [URL to Script Resolution](https://sling.apache.org/documentation/the-sling-engine/url-to-script-resolution.html#script-locations)
page. In addition to the normal way of structuring scripts in the file tree, the plugin provides some additional features:

  1. Resource Type Versioning<br/>
     This works by putting the scripts in a folder that follows this simple naming convention: `<resourceType>/<version>/`. The `<version>`
     should be a valid semantic version (e.g. `1.0.0`)

  2. Defining explicit extends relationships (similar to the `sling:resourceSuperType` property)<br/>
     An `extends` file in the resource type folder (versioned or not) allows defining this explicit relationship. This file must contain a
     single line with the `resourceType` used for the `extends` capability attribute followed by a `;version=<version-range>`; in this
     case, the plugin will set the `extends` attribute to the given `resourceType` and generate a `Require-Capability` for that
     `resourceType` with the given version range.

  3. Defining an explicit requirement, without an inheritance relationship (e.g. delegation to another resource type)<br/>
     A `requires` file (assuming the same conventions and syntax as for the `extends` file) will generate a `Require-Capability` for each
     line based on the given `resourceType` and version range.

  4. The Resource Type can have the form of a path or of a Java package name (e.g. `com.mydomain.components.image`). When the resource type
     is defined as a package name, the resource type label will be the last subpackage (i.e. for `com.mydomain.components.image`, the
     resource type label will be `image`).

$h3 Defining scripts
As an example, let's assume the following layout:
```
src/main/resources/javax.script/
    org.foo/1.0.0
        foo.POST.html
```

This will generate following `Provide-Capability`:

```
sling.servlet;
    sling.servlet.resourceTypes:List<String>="org.foo";
    sling.servlet.methods:List<String>=POST;
    version:Version="1.0.0"
```

For more complex examples head over to https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/tree/master/examples.

$h3 So how do I use the plugin?

$h4 Maven Plugin

When used as a Maven plugin, the generated `Require-Capability` and  `Provide-Capability` headers values are made available via
properties:

```
${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability}
${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability}
```

That makes it reasonably straightforward to use the plugin by just adding it into your build and use the two properties in the manifest
writing instructions of another plugin like the `maven-bundle-plugin`:

```
<plugin>
    <groupId>${project.groupId}</groupId>
    <artifactId>${project.artifactId}</artifactId>
    <version>${project.version}</version>
    <executions>
        <execution>
            <phase>prepare-package</phase>
            <goals>
                <goal>metadata</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <extensions>true</extensions>
    <configuration>
        <instructions>
            <Provide-Capability>
                ${org.apache.sling.scriptingbundle.maven.plugin.Provide-Capability}
            </Provide-Capability>
            <Require-Capability>
                osgi.extender;filter:="(&amp;(osgi.extender=sling.scripting)(version>=1.0.0)(!(version>=2.0.0)))",
                ${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability}
            </Require-Capability>
        </instructions>
    </configuration>
</plugin>
```

The `osgi.extender` requirement is mandatory to have the bundle wired up to the Apache Sling Servlets Resolver, but this should be manually
defined by the developers, so that their bundle is correctly wired up to whatever version of the Servlets Resolver is available on the
destination platform.

$h4 BND Plugin

Starting with version `0.3.0`, the JAR also provides a BND plugin. The simplest configuration (where the defaults are used)
would look like:
```
<plugin>
    <groupId>biz.aQute.bnd</groupId>
    <artifactId>bnd-maven-plugin</artifactId>
    <dependencies>
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>${project.artifactId}</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
</plugin>
```

and the following instructions added to your project's `bnd.bnd` file:
```
Require-Capability:             osgi.extender;filter:="(&(osgi.extender=sling.scripting)(version>=1.0.0)(!(version>=2.0.0)))"
-plugin:                        org.apache.sling.scriptingbundle.plugin.bnd.BundledScriptsScannerPlugin
```

The BND plugin supports the same configuration options as the Maven `metadata` goal, using the exact same name for its configuration
properties. Multiple values need to be provided as a quoted comma separated values list (e.g.
`sourceDirectories="src/main/scripts,src/main/resources/javax.script"`, `scriptEngineMappings="html:htl,js:rhino"`).