org.kohsuke.stapler.framework.adjunct.package-info Maven / Gradle / Ivy
Show all versions of stapler-jelly Show documentation
/*******************************************************************************
*
* Copyright (c) 2004-2010 Oracle Corporation.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
*
* Kohsuke Kawaguchi
*
*******************************************************************************/
/**
* 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:
*
*
* - Copy files into the webapp resource directories.
*
- If the JavaScript library depends on other JavaScript libraries, copy those, too.
*
- For each page where you use them, write script and link tags to load images and CSS, as well as their dependencies.
*
*
*
* 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
*
* -
* 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.
*
*
-
* If this library depends on other libraries, use Maven's dependency management to have the resulting jars
* express dependencies.
*
*
-
* Express dependencies among adjuncts.
*
*
*
*
* What webapp developers do
*
* -
* Include adjunct jar files into WEB-INF/libs either directly or indirectly, typically via Maven.
*
*
-
* Bind {@link AdjunctManager} to URL by using Stapler. This object serves adjunct JavaScript, CSS, images, and so on.
*
*
-
* 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:adjunt> 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 {@link 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.
*/
package org.kohsuke.stapler.framework.adjunct;