Convert to asciidoc

Rename “doc” folder to “docs” to align with individual elements. Remove redundant “index.asciidoc” file.
author: Jouni Koivuviita <jouni@jouni.me> 2016-04-14 17:19:23 +0300
committer: Jouni Koivuviita <jouni@jouni.me> 2016-04-14 17:19:23 +0300
commit: ee80eb2bf5ac4b3644d0a5d852d2fbc010be3b90 (patch)
tree: 94944510fabf701d4ff0f44f5e25a7f388343217
parent: 4bc969e0addb3f299f664f6980cc1300922fa7d9 (diff)
download: vaadin-core-ee80eb2bf5ac4b3644d0a5d852d2fbc010be3b90.tar.gz
vaadin-core-ee80eb2bf5ac4b3644d0a5d852d2fbc010be3b90.zip
5 files changed, 189 insertions, 237 deletions
diff --git a/apidoc/index.html b/apidoc/index.html
deleted file mode 100644
index 00a6234..0000000
--- a/apidoc/index.html
+++ /dev/null
@@ -1,59 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head lang="en">
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>vaadin-core-elements</title>
-  <style>
-    body {
-      font-family: 'Roboto', 'Noto', sans-serif;
-      font-size: 16px;
-      background: #fafafa;
-      color: #212121;
-    }
-    section {
-      width: 50%;
-      margin: 50px auto;
-      background: #fff;
-      border: 1px solid #e5e5e5;
-    }
-    @media (max-width: 700px) {
-      section {
-        width: 100%;
-      }
-    }
-    h1 {
-      font-size: 150%;
-      font-weight: 400;
-    }
-    ul {
-      padding-left: 0;
-      list-style: none;
-      border-bottom: 1px solid #e5e5e5;
-    }
-    li {
-      line-height: 1.4;
-      border-top: 1px solid #e5e5e5;
-    }
-    li p {
-      margin: 0;
-    }
-    h1,
-    li {
-      padding: 14px 24px;
-    }
-  </style>
-</head>
-
-<body>
-  <section>
-    <h1>API documentation for vaadin-core-elements</h1>
-    <ul>
-      <li>
-        <a id="vaadin-grid" href="../../vaadin-grid/index.html">vaadin-grid</a>
-        <p>Data grid for showing large amounts of tabular data.</p>
-      </li>
-    </ul>
-  </section>
-</body>
-</html>
diff --git a/doc/elements-getting-started.md b/doc/elements-getting-started.md
deleted file mode 100644
index 58eaf5e..0000000
--- a/doc/elements-getting-started.md
+++ /dev/null
@@ -1,145 +0,0 @@
----
-title: Getting Started
-order: 2
-layout: page
----
-
-# Getting Started
-
-This page will guide you through the installation of Vaadin Core Elements bundle and help you get started with your first project using these elements.
-
-## Installation
-
-There are three ways to use Vaadin Core Elements in your project: Bower, CDN and a ZIP archive. The only difference between these options is the URL you will use to import the necessary files into your HTML page.
-
-### 1. Create a new folder
-
-Start by creating a new folder for your project and change into the newly created folder.
-
-      $ mkdir my-project
-      $ cd my-project
-
-### 2. Install Vaadin Core Elements
-
-#### Bower
-
-Recommended way to manage your front-end dependencies is using [Bower](http://bower.io). Follow the [Bower installation instructions](http://bower.io/#install-bower), then run the following command inside your project folder to install the most recent stable release.
-
-
-     $ bower install --save vaadin-core-elements
-
-
-This will download Vaadin Core Elements bundle and its dependencies into the `bower_components` folder inside your project's folder.
-
-----
->If you wish to use a development snapshot version of some element, you can install/update that separately. For example:
-
-
-          $ bower install --save vaadin-grid#master
-
-----
-
-#### CDN
-
-You can use Vaadin Core Elements from CDN (see example below). This is especially convenient for services like JSFiddle, Codepen.io, etc.
-
-For example, to import vaadin-grid, use the following URL:
-
-      https://cdn.vaadin.com/vaadin-core-elements/latest/vaadin-grid/vaadin-grid.html
-
-To import all Vaadin Core Elements, use the following URL:
-
-      https://cdn.vaadin.com/vaadin-core-elements/latest/vaadin-core-elements/vaadin-core-elements.html
-
-----
-> You can also use the nightly snapshot versions of any component, e.g. `https://cdn.vaadin.com/vaadin-core-elements/master/vaadin-grid/vaadin-grid.html`
-
-----
-
-#### Download ZIP
-
-1. Download the latest ZIP archive from [vaadin.com/download](https://vaadin.com/download#elements).
-2. Extract the archive under your project folder, for example `deps`.
-
-### 3. Create a HTML file
-
-Create a new HTML file (for example `index.html`) inside your project folder and copy the following code into it.
-
-Pay attention to the following details:
-
- - HTML5 doctype (`<!doctype html>`) is required for everything to work smoothly.
- - You need to adjust how the `webcomponents-lite.min.js` polyfill and `vaadin-core-elements.html` are imported according to the installation option you selected.
- - Notice how the JavaScript logic waits for `WebComponentsReady` event before accessing the elements.
-
-----
-> **Serving the files during development**, when using Bower or the ZIP archive:
-> Due to browser security restrictions, serving HTML imports from a `file:///` URL does not work. You need a web server to view pages where you use custom elements. One simple option is to use the [`serve`](https://www.npmjs.com/package/serve) NPM package.
-
-----
-
-    <!doctype html>
-    <html>
-     <head>
-       <!-- Import Web Component polyfills and all Vaadin Core Elements. -->
-
-       <!-- CDN -->
-       <script src="https://cdn.vaadin.com/vaadin-core-elements/latest/webcomponentsjs/webcomponents-lite.min.js"></script>
-       <link href="https://cdn.vaadin.com/vaadin-core-elements/latest/vaadin-core-elements/vaadin-core-elements.html" rel="import">
-
-       <!-- Bower -->
-       <!-- <script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
-       <link href="bower_components/vaadin-core-elements/vaadin-core-elements.html" rel="import"> -->
-
-       <!-- ZIP archive -->
-       <!-- <script src="deps/webcomponentsjs/webcomponents-lite.min.js"></script>
-       <link href="deps/vaadin-core-elements/vaadin-core-elements.html" rel="import"> -->
-     </head>
-     <body>
-
-       <vaadin-grid selection-mode="multi">
-         <table>
-           <!-- Define the columns and their mapping to data properties. -->
-           <col name="firstName">
-           <col name="lastName">
-           <col name="email">
-
-           <!-- Define the column headings. -->
-           <thead>
-             <tr>
-               <th>First Name</th>
-               <th>Last Name</th>
-               <th>Email</th>
-             </tr>
-           </thead>
-         </table>
-       </vaadin-grid>
-
-       <script>
-         // The Web Components polyfill introduces a custom event we can
-         // use to determine when the custom elements are ready to be used.
-         document.addEventListener("WebComponentsReady", function () {
-
-           // Reference to the grid element.
-           var grid = document.querySelector("vaadin-grid");
-
-           // Add some example data as an array.
-           grid.items = [
-             { "firstName": "Hugo", "lastName": "Romero", "email": "hugo.romero@example.com" },
-             { "firstName": "Nieves", "lastName": "Diez", "email": "nieves.diez@example.com" },
-             { "firstName": "Esteban", "lastName": "Vega", "email": "esteban.vega@example.com" },
-             { "firstName": "Roxane", "lastName": "Diez", "email": "roxane.diez@example.com" }
-           ];
-         });
-       </script>
-
-     </body>
-    </html>
-
-
-After you have created the file and you have a local server serving the files, you should be able to open up the application in your browser at [http://localhost:3000/index.html](http://localhost:3000/index.html) (notice, that the port 3000 may vary depending on the server you use).
-
-<!-- Assumes .w-arrow-button and .blue class names from vaadin.com theme. Will fallback to a plain link. -->
-<a href="vaadin-grid/overview.html" class="w-arrow-button blue" style="display: inline-block">
-  Vaadin Grid<br />
-  <small>Continue to Vaadin Grid documentation</small>
-</a>
diff --git a/doc/index.asciidoc b/doc/index.asciidoc
deleted file mode 100644
index 2dff096..0000000
--- a/doc/index.asciidoc
+++ /dev/null
@@ -1 +0,0 @@
-== Index
-\ No newline at end of file
diff --git a/docs/elements-getting-started.adoc b/docs/elements-getting-started.adoc
new file mode 100644
index 0000000..5e810c8
--- /dev/null
+++ b/docs/elements-getting-started.adoc
@@ -0,0 +1,155 @@
+---
+title: Getting Started
+order: 2
+layout: page
+---
+
+# Getting Started with Vaadin Core Elements
+
+This page will guide you through the installation of Vaadin Core Elements bundle and help you get started with your first project using these elements.
+
+## Installation
+
+There are three ways to use Vaadin Core Elements in your project: Bower, CDN and a ZIP archive. The only difference between these options is the URL you will use to import the necessary files into your HTML page.
+
+### Create a new folder
+
+Start by creating a new folder for your project and change into the newly created folder.
+
+----
+$ mkdir my-project
+$ cd my-project
+----
+
+### Install Vaadin Core Elements
+
+#### Bower
+
+Recommended way to manage your front-end dependencies is using link:http://bower.io[Bower]. Follow the link:http://bower.io/#install-bower[Bower installation instructions], then run the following command inside your project folder to install the most recent stable release.
+
+[source]
+----
+$ bower install --save vaadin-core-elements
+----
+
+This will download Vaadin Core Elements bundle and its dependencies into the `bower_components` folder inside your project's folder.
+
+If you wish to use a development snapshot version of some element, you can install/update that separately. For example:
+
+----
+$ bower install --save vaadin-grid#master
+----
+
+#### CDN
+
+You can use Vaadin Core Elements from CDN (see example below). This is especially convenient for services like JSFiddle, Codepen.io, etc.
+
+For example, to import vaadin-grid, use the following URL:
+
+----
+https://cdn.vaadin.com/vaadin-core-elements/latest/vaadin-grid/vaadin-grid.html
+----
+
+To import all Vaadin Core Elements, use the following URL:
+
+----
+https://cdn.vaadin.com/vaadin-core-elements/latest/vaadin-core-elements/vaadin-core-elements.html
+----
+
+You can also use the nightly snapshot versions of any component, e.g.
+
+----
+https://cdn.vaadin.com/vaadin-core-elements/master/vaadin-grid/vaadin-grid.html
+----
+
+#### Download ZIP
+
+1. Download the latest release ZIP archive from the link:https://github.com/vaadin/vaadin-core-elements/releases[GitHub releases page]
+2. Extract the archive under your project folder, for example `deps`.
+
+### Create a HTML file
+
+Create a new HTML file (for example `index.html`) inside your project folder and copy the following code into it.
+
+Pay attention to the following details:
+
+ - HTML5 doctype (`<!doctype html>`) is required for everything to work smoothly.
+ - You need to adjust how the `webcomponents-lite.min.js` polyfill and `vaadin-core-elements.html` are imported according to the installation option you selected.
+ - Notice how the JavaScript logic waits for `WebComponentsReady` event before accessing the elements.
+
+
+**Serving the files during development**, when using Bower or the ZIP archive:
+
+Due to browser security restrictions, serving HTML imports from a `file:///` URL does not work. You need a web server to view pages where you use custom elements. One simple option is to use the link:https://www.npmjs.com/package/serve["serve" npm package].
+
+[source,html]
+----
+
+<!doctype html>
+<html>
+ <head>
+   <!-- Import Web Component polyfills and all Vaadin Core Elements. -->
+
+   <!-- CDN -->
+   <script src="https://cdn.vaadin.com/vaadin-core-elements/latest/webcomponentsjs/webcomponents-lite.min.js"></script>
+   <link href="https://cdn.vaadin.com/vaadin-core-elements/latest/vaadin-core-elements/vaadin-core-elements.html" rel="import">
+
+   <!-- Bower -->
+   <!-- <script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
+   <link href="bower_components/vaadin-core-elements/vaadin-core-elements.html" rel="import"> -->
+
+   <!-- ZIP archive -->
+   <!-- <script src="deps/webcomponentsjs/webcomponents-lite.min.js"></script>
+   <link href="deps/vaadin-core-elements/vaadin-core-elements.html" rel="import"> -->
+ </head>
+ <body>
+
+   <vaadin-grid selection-mode="multi">
+     <table>
+       <!-- Define the columns and their mapping to data properties. -->
+       <col name="firstName">
+       <col name="lastName">
+       <col name="email">
+
+       <!-- Define the column headings. -->
+       <thead>
+         <tr>
+           <th>First Name</th>
+           <th>Last Name</th>
+           <th>Email</th>
+         </tr>
+       </thead>
+     </table>
+   </vaadin-grid>
+
+   <script>
+     // The Web Components polyfill introduces a custom event we can
+     // use to determine when the custom elements are ready to be used.
+     document.addEventListener("WebComponentsReady", function () {
+
+       // Reference to the grid element.
+       var grid = document.querySelector("vaadin-grid");
+
+       // Add some example data as an array.
+       grid.items = [
+         { "firstName": "Hugo", "lastName": "Romero", "email": "hugo.romero@example.com" },
+         { "firstName": "Nieves", "lastName": "Diez", "email": "nieves.diez@example.com" },
+         { "firstName": "Esteban", "lastName": "Vega", "email": "esteban.vega@example.com" },
+         { "firstName": "Roxane", "lastName": "Diez", "email": "roxane.diez@example.com" }
+       ];
+     });
+   </script>
+
+ </body>
+</html>
+----
+
+After you have created the file and you have a local server serving the files, you should be able to open up the application in your browser at http://localhost:3000/index.html (notice, that the port 3000 may vary depending on the server you use).
+
++++
+<!-- Assumes .w-arrow-button and .blue class names from vaadin.com theme. Will fallback to a plain link. -->
+<a href="vaadin-grid/overview.html" class="w-arrow-button blue" style="display: inline-block">
+  Vaadin Grid<br />
+  <small>Continue to Vaadin Grid documentation</small>
+</a>
++++
diff --git a/doc/elements-introduction.md b/docs/elements-introduction.adoc
index 34cf380..1f61324 100644
--- a/doc/elements-introduction.md
+++ b/docs/elements-introduction.adoc
@@ -4,62 +4,61 @@ order: 1
 layout: page
 ---
 
-# Introduction
+# Vaadin Core Elements
 
-## Vaadin Core Elements
+## Introduction
 
-Vaadin Core Elements is a free and open source set of high quality [Web Components](http://webcomponents.org) for building mobile and desktop web applications in modern browsers. It builds on top of Google’s [Polymer](http://www.polymer-project.org) library, and augments the [Iron, Paper and other element sets of Polymer](https://elements.polymer-project.org) with elements that are needed in building business applications.
+Vaadin Core Elements is a free and open source set of high quality link:http://webcomponents.org[Web Components] for building mobile and desktop web applications in modern browsers. It builds on top of Google’s link:http://www.polymer-project.org[Polymer] library, and augments the link:https://elements.polymer-project.org[Iron, Paper and other element sets of Polymer] with elements that are needed in building business applications.
 
-Although based on Polymer, Vaadin elements can be used together with any other web framework which has support for Web Components. See the "Integrations" section for examples how to use the elements together with different JavaScript frameworks and libraries.
+Although based on Polymer, Vaadin Elements can be used together with any other web framework which has support for Web Components. See the "Integrations" section for examples how to use the elements together with different JavaScript frameworks and libraries, such as Angular 2 and React.
 
-If you wish to use Vaadin elements with [GWT](http://gwtproject.org), you can use [GWT Polymer Elements](https://vaadin.com/gwt)
+If you wish to use Vaadin elements with link:http://gwtproject.org[GWT], you can use link:https://vaadin.com/gwt[GWT Polymer Elements]
 
 Vaadin Core Elements includes the following elements:
 
- - [Combo Box](https://vaadin.com/docs/-/part/elements/vaadin-combo-box/vaadin-combo-box-overview.html)
- - [Date Picker](https://vaadin.com/docs/-/part/elements/vaadin-date-picker/vaadin-date-picker-overview.html)
- - [Grid](https://vaadin.com/docs/-/part/elements/vaadin-grid/overview.html)
- - [Upload](https://vaadin.com/docs/-/part/elements/vaadin-upload/vaadin-upload-overview.html)
+ - link:/docs/-/part/elements/vaadin-combo-box/vaadin-combo-box-overview.html[Combo Box]
+ - link:/docs/-/part/elements/vaadin-date-picker/vaadin-date-picker-overview.html[Date Picker]
+ - link:/docs/-/part/elements/vaadin-grid/overview.html[Grid]
+ - link:/docs/-/part/elements/vaadin-upload/vaadin-upload-overview.html[Upload]
 
-Learn more about the benefits of using Vaadin elements from the [Vaadin elements page »](https://vaadin.com/elements)
+Learn more about the benefits of using Vaadin elements from the link:https://vaadin.com/elements[Vaadin Elements page »]
 
 ## Background
 
 ### Web Components
 
-Web Components is a collection of HTML standards (under development, Dec 2015), which together provide web developers the tools to extend the native web platform with similar tools as the browser vendors have been using for creating the built-in standard elements, such as `<video>`, `<input type="date">` and so on.
+Web Components is a collection of HTML standards (under development, April 2016), which together provide web developers the tools to extend the native web platform with similar tools as the browser vendors have been using for creating the built-in standard elements, such as `<video>`, `<input type="date">` and so on.
 
 The four specifications that together form Web Components are:
 
-- #### Template element
+- **Template element** +
   “The HTML template element `<template>` is a mechanism for holding client-side content that is not to be rendered when a page is loaded but may subsequently be instantiated during runtime using JavaScript.”
 
-- #### Shadow DOM
-  “Shadow DOM provides encapsulation for the JavaScript, CSS, and templating in a Web Component. Shadow DOM makes it so these things remain separate from the DOM of the main document.”
-
+- **Shadow DOM** +
+  “Shadow DOM provides encapsulation for the JavaScript, CSS, and templating in a Web Component. Shadow DOM makes it so these things remain separate from the DOM of the main document.” +
   “Why would you want to keep some code separate from the rest of the page? One reason is that on a large site, for example, if the CSS is not carefully organized, the styling for the navigation can "leak" into the main content area where it was not intended to go, or vice-versa. As a site or an app scales, this kind of thing becomes difficult to avoid.”
 
-- #### HTML Imports
+- **HTML Imports** +
   “HTML Imports is a way to include HTML documents in other HTML documents. You're not limited to markup either. An import can also include CSS, JavaScript, or anything else an .html file can contain. In other words, this makes imports a fantastic tool for loading related HTML/CSS/JS.”
 
-- #### Custom Elements
+- **Custom Elements** +
   “Custom Elements allow web developers to define new types of HTML elements. It's quite possibly the most important as Web Components don't exist without the features unlocked by custom elements.”
 
-Descriptions provided by [MDN](https://developer.mozilla.org/en-US/) and [HTML5 Rocks](http://www.html5rocks.com/en/).
+Descriptions provided by link:https://developer.mozilla.org/en-US/[MDN] and link:http://www.html5rocks.com/en/[HTML5 Rocks].
 
-[Learn more about Web Components »](http://webcomponents.org)
+link:http://webcomponents.org[Learn more about Web Components »]
 
 ### Polymer
 
 The Polymer library is designed to make it easier and faster for developers to create great, reusable components for the modern web.
 
-It provides a declarative syntax that makes it simpler to define custom elements. And it adds features like templating, two-way data binding and property observation to help you build powerful, reusable elements with less code.
+It provides a declarative syntax that makes it simpler to define custom elements, and it adds features like templating, two-way data binding and property observation to help you build powerful, reusable elements with less code.
 
 The Polymer team also builds and maintains a large collection of custom elements, and the most prominent one is the Paper collection. The Paper elements are Google’s reference implementation of Material Design for the web.
 
-[Learn more about Polymer »](https://www.polymer-project.org)
+link:https://www.polymer-project.org[Learn more about Polymer »]
 
-[Browse Polymer Element Catalog »](https://elements.polymer-project.org)
+link:https://elements.polymer-project.org[Browse Polymer Element Catalog »]
 
 ## Browser compatibility
 
@@ -67,29 +66,32 @@ The standards of Web Components are on the cutting-edge of web technologies and
 
 The current set of supported browsers for Vaadin Core Elements is listed on the table below.
 
-| IE / Edge | Firefox | Chrome | Safari | iOS Safari | Chrome Android |
-| :---------: | :---------: | :---------: | :---------: | :---------: | :---------: |
-| IE11, Edge| Latest | Latest | Latest | iOS 9 | Latest
+|===
+| IE / Edge | Firefox | Chrome, desktop | Chrome, Android | Safari, OS X | Safari, iOS
+| IE11 / Latest | Latest | Latest | Latest | iOS 8+ | Latest
+|===
 
 See also
 
- - [Native Web Components support](http://webcomponents.org/)
- - [Browser support of webcomponents.js polyfill](https://github.com/WebComponents/webcomponentsjs#browser-support)
- - [Browser support of Polymer](https://www.polymer-project.org/1.0/resources/compatibility.html)
- 
+ - link:http://webcomponents.org/[Native Web Components support]
+ - link:https://github.com/WebComponents/webcomponentsjs#browser-support[Browser support of webcomponents.js polyfill]
+ - link:https://www.polymer-project.org/1.0/resources/compatibility.html[Browser support of Polymer]
+
 ## Framework support
 
 You can use Vaadin elements together with any JavaScript framework or library which has support for Web Components.
 
 Example integrations for some popular frameworks and libraries:
 
-- [Polymer](/docs/-/part/elements/integrations/polymer.html)
-- [Angular 2](/docs/-/part/elements/integrations/angular2.html)
-- [React](/docs/-/part/elements/integrations/react.html)
+- link:/docs/-/part/elements/integrations/polymer.html[Polymer]
+- link:/docs/-/part/elements/integrations/angular2.html[Angular 2]
+- link:/docs/-/part/elements/integrations/react.html[React]
 
 
++++
 <!-- Assumes .w-arrow-button and .blue class names from vaadin.com theme. Will fallback to a plain link. -->
 <a href="elements-getting-started.html" class="w-arrow-button blue" style="display: inline-block">
   Getting Started<br />
   <small>How to setup a Vaadin elements project</small>
 </a>
++++
author	Jouni Koivuviita <jouni@jouni.me>	2016-04-14 17:19:23 +0300
committer	Jouni Koivuviita <jouni@jouni.me>	2016-04-14 17:19:23 +0300
commit	ee80eb2bf5ac4b3644d0a5d852d2fbc010be3b90 (patch)
tree	94944510fabf701d4ff0f44f5e25a7f388343217
parent	4bc969e0addb3f299f664f6980cc1300922fa7d9 (diff)
download	vaadin-core-ee80eb2bf5ac4b3644d0a5d852d2fbc010be3b90.tar.gz vaadin-core-ee80eb2bf5ac4b3644d0a5d852d2fbc010be3b90.zip