Migrate UsingAJavaSscriptLibraryOrAStyleSheetInAnAddOn

2 files changed, 47 insertions, 0 deletions

diff --git a/documentation/articles/UsingAJavaScriptLibraryOrAStyleSheetInAnAddOn.asciidoc b/documentation/articles/UsingAJavaScriptLibraryOrAStyleSheetInAnAddOn.asciidoc
new file mode 100644
index 0000000000..ee2123b204
--- /dev/null
+++ b/documentation/articles/UsingAJavaScriptLibraryOrAStyleSheetInAnAddOn.asciidoc
@@ -0,0 +1,46 @@
+[[using-a-javascript-library-or-a-style-sheet-in-an-addon]]
+Using a JavaScript library or a style sheet in an add-on
+--------------------------------------------------------
+
+Including style sheets or JavaScript files in your add-ons or as a part
+of your application can now be done by adding a `@StyleSheet` or
+`@JavaScript` annotation to a `Component` or `Extension` class. Each
+annotation takes a list of strings with URLs to the resources that
+should be loaded on the page before the framework initializes the
+client-side `Component` or `Extension`.
+
+The URLs can either be complete absolute urls (e.g. https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js) or
+relative URLs (e.g. _redbutton.css_). A relative URL is converted to a
+special URL that will download the file from the Java package where the
+defining class is located. This means that e.g.
+`@StyleSheet({"redbutton.css"})` on the class `com.example.RedButton` will
+cause the file `com/example/redbutton.css` on the classpath to be loaded
+in the browser. `@JavaScript` works in exactly the same way - see
+link:IntegratingAJavaScriptComponent.asciidoc[Integrating a JavaScript component]
+for a practical example.
+
+[source,java]
+....
+@StyleSheet("redbutton.css")
+public class RedButton extends NativeButton {
+  public RedButton(String caption) {
+    super(caption);
+    addStyleName("redButton");
+  }
+}
+....
+
+In this simple example, the `RedButton` component just adds a `redButton`
+style name to a normal `NativeButton`. _redbutton.css_ is located in the
+same folder as _RedButton.java_ and has this content:
+
+[source,css]
+....
+.redButton {
+  background-color: red;
+}
+....
+
+This new mechanism makes it very easy to include style sheet or
+JavaScript files with add-ons and automatically load them in the browser
+when the add-on is used.
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index 19f999a992..8360662dff 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -46,4 +46,5 @@ are great, too.
 - link:VaadinOnGrailsMultipleUIs.asciidoc[Vaadin on grails - Multiple UIs]
 - link:IntegratingAJavaScriptComponent.asciidoc[Integrating a JavaScript component]
 - link:IntegratingAJavaScriptLibraryAsAnExtension.asciidoc[Integrating a JavaScript library as an extension]
+- link:UsingAJavaScriptLibraryOrAStyleSheetInAnAddOn.asciidoc[Using a JavaScript library or a style sheet in an add-on]
 - link:CreatingAUIExtension.asciidoc[Creating a UI extension]