Skip navigation links

Package org.kohsuke.stapler.framework.adjunct

JavaScript/CSS packaging mechanism.

See: Description

Package org.kohsuke.stapler.framework.adjunct Description

JavaScript/CSS packaging mechanism.

A part of writing a web application involves reusing JavaScript libraries that are developed by 3rd parties. Such JavaScript libraries often come in a package of js files, CSS, images, and so on. To integrate those libraries to your application, you often need to do:

This tediousness hurts the small-scale reusability of JavaScript libraries. The adjunct framework in Stapler attempts to solve this by allowing libraries/components to express dependencies among themselves, and grouping CSS and JavaScript together, so that a single "inclusion" would include everything that a JavaScript library needs.

What packagers do

  1. Package JavaScript libraries as a jar file, including CSS and asset files, typically through Maven. CSS (*.css), JavaScript (*.js), and HTML (*.html) that are only different by their extensions are grouped into "adjunct", which becomes the unit of dependency management. All three aspects of an adjunct is optional. More about what these files do later.
  2. If this library depends on other libraries, use Maven's dependency management to have the resulting jars express dependencies.
  3. Express dependencies among adjuncts.

What webapp developers do

  1. Include adjunct jar files into WEB-INF/libs either directly or indirectly, typically via Maven.
  2. Bind AdjunctManager to URL by using Stapler. This object serves adjunct JavaScript, CSS, images, and so on.
  3. Use <st:adjunct> tag to load adjunct into the page. This tag expands to the <script> and <link> tags for the adjunct itself and all the dependencies. It also remembers what adjuncts are already loaded into the page, so when multiple <st:adjunct> tags are used to load different libraries, it won't repeatedly load the same script.

Adjunct

Name

Adjuncts are identified by their fully qualified names, which is the package name + base name of the file name (this is just like how a Java class gets its FQCN.)

Expressing dependencies

Lines of the following form in JavaScript and CSS are interpreted by the adjunct framework to express dependencies to other adjuncts. They have to start at the beginning of the line, without a leading whitespace.


 // @include fully.qualified.adjunct.name
 /* @include fully.qualified.adjunct.name
 

HTML file can have the following line to indicate a dependency.

 <@include fully.qualified.adjunct.name>

Page injection

Stapler loads an adjunct into a page by generating a link tag and a script tag to load the JS and CSS files, respectively. The URLs these tags point to are served by AdjunctManager. If an HTML file is a part of an adjunct, its content is just included inline along with script and link tags. This is useful to write a glue to load a large 3rd party JavaScript libraries without modifying them or changing their names.

Skip navigation links

Copyright © 2017. All rights reserved.