Closes #133

před 6 roky · 3b6bb697ca
--- a/docs/elements-getting-started.adoc
+++ b/docs/elements-getting-started.adoc
@@ -1,150 +0,0 @@
 ---
 title: Getting Started
 order: 2
 layout: page
 ---

 # Getting Started with Vaadin Core Elements

 This page will guide you through the installation of the 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 that you 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 to the folder.

 [subs="normal"]
 ----
 [prompt]#$# [command]#mkdir# [replaceable]#my-project#
 [prompt]#$# [command]#cd# [replaceable]#my-project#
 ----

 ### Install Vaadin Core Elements

 #### Bower

 The recommended way to manage your front-end dependencies is to use 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.

 [subs="normal"]
 ----
 [prompt]#$# [command]#bower# install --save [replaceable]#vaadin-core-elements#
 ----

 This will download the Vaadin Core Elements bundle and its dependencies into the [filename]#bower_components# folder under your project's folder.

 If you wish to use a development snapshot version of some element, you can install and update that separately. For example:

 [subs="normal"]
 ----
 [prompt]#$# [command]#bower# install --save [replaceable]#vaadin-grid##master
 ----

 #### CDN

 You can use Vaadin Core Elements from our link:https://en.wikipedia.org/wiki/Content_delivery_network[CDN] server. This is especially convenient for services like JSFiddle, Codepen.io, etc.

 For example, to import [vaadinelement]#vaadin-grid#, use the following URL:

 ----
 <link href="https://cdn.vaadin.com/vaadin-core-elements/latest/vaadin-grid/vaadin-grid.html" rel="import">
 ----

 To import all Vaadin Core Elements, use the following URL:

 ----
 <link href="https://cdn.vaadin.com/vaadin-core-elements/latest/vaadin-core-elements/vaadin-core-elements.html" rel="import">
 ----

 You can also use the nightly snapshot versions of any component, e.g.

 ----
 <link href="https://cdn.vaadin.com/vaadin-core-elements/master/vaadin-grid/vaadin-grid.html" rel="import">
 ----

 #### Download as a 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 in a [filename]#deps# folder.

 ### Create a HTML file

 Create a new HTML file (for example [filename]#index.html#) inside your project folder and copy the code below into it.

 Pay attention to the following details:

 - HTML5 doctype [elementname]#!doctype html# is required for everything to work smoothly.
 - You need to adjust how the [filename]#webcomponents-lite.min.js# polyfill and [filename]#vaadin-core-elements.html# are imported according to the installation option you selected.
 - Notice how the JavaScript logic waits for [classname]#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>

    <vaadin-grid-column>
      <template class="header">First Name</template>
      <template>[[item.firstName]]</template>
    </vaadin-grid-column>

    <vaadin-grid-column>
      <template class="header">Last Name</template>
      <template>[[item.lastName]]</template>
    </vaadin-grid-column>

    <vaadin-grid-column>
      <template class="header">Email</template>
      <template>[[item.email]]</template>
    </vaadin-grid-column>

   </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 number may vary depending on the server you use).
--- a/docs/elements-introduction.adoc
+++ b/docs/elements-introduction.adoc
@@ -1,92 +0,0 @@
 ---
 title: Introduction
 order: 1
 layout: page
 ---

 # Vaadin Core Elements

 ## Introduction

 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 that has support for Web Components. See the  link:integrations/polymer.html[Integrations] section for examples how to use the elements together with different JavaScript frameworks and libraries, such as React and Vue.js.

 There's also 3rd party utilities available for integrating Vaadin Core Elements (and Polymer elements in general) with link:https://github.com/platosha/angular-polymer[Angular] and link:https://github.com/manolo/gwt-polymer-elements[GWT]

 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, 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 [elementname]#video#, [elementname]#input type="date"#, and so on.

 The four specifications that together form Web Components are:

 *Template element*::
  "The HTML template element [elementname]#template# is a mechanism for holding client-side content that is not rendered when a page is loaded. But it may be instantiated in runtime"

 *Shadow DOM*::
  "Shadow DOM provides encapsulation for the JavaScript, CSS, and templating in a Web Component. Shadow DOM allows keeping them 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 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 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 link:https://developer.mozilla.org/en-US/[MDN] and link:http://www.html5rocks.com/en/[HTML5 Rocks].

 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 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.

 link:https://www.polymer-project.org[Learn more about Polymer]

 link:https://elements.polymer-project.org[Browse Polymer Element Catalog]

 ## Browser compatibility

 The standards of Web Components are on the cutting-edge of web technologies and as such they are not yet fully supported in all browsers. Vaadin elements rely on polyfills to fill the gap and can therefore support the latest versions of all major browsers.

 The current set of supported browsers for Vaadin Core Elements is listed on the table below:

 |===
 | IE / Edge | Firefox | Chrome, desktop | Chrome, Android | Safari, OS X | Safari, iOS
 | IE11 / Latest | Latest | Latest | Latest | iOS 9 | Latest
 |===

 See also

 - 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/2.0/docs/browsers[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:

 - link:/docs/-/part/elements/elements-getting-started.html[Polymer]
 - link:/docs/-/part/elements/integrations/integrations-react.html[React]
 - link:/docs/-/part/elements/integrations/integrations-vuejs.html[Vue.js]

 For more information, check link:https://custom-elements-everywhere.com[custom-elements-everywhere.com], which tracks the support status of various frameworks.


 +++
 <!-- 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>
 +++
--- a/docs/integrations/img/react-integration.png
+++ b/docs/integrations/img/react-integration.png
--- a/docs/integrations/integrations-react.adoc
+++ b/docs/integrations/integrations-react.adoc
@@ -1,121 +0,0 @@
 ---
 title: React Integration
 order: 1
 layout: page
 ---

 # React Integration

 The link:https://facebook.github.io/react/[React] library from Facebook easily integrates with web components.
 As long as you import required polyfills and add HTML imports for the elements you are using, you can simply start adding these custom elements to your JSX markup.

 ifdef::web[]
 ====
 See also the link:https://facebook.github.io/react/docs/webcomponents.html[Web Components page] in React documentation.
 ====
 endif::web[]


 ## Grid Example

 [[figure.vaadin-grid.react]]
 .React integration example using [vaadinelement]#vaadin-grid#
 image::img/react-integration.png[]

 The example consists of two React components: [classname]#UserApp# and [classname]#UserGrid#.
 The [classname]#UserGrid# component wraps the [vaadinelement]#vaadin-grid# element and does all necessary initialization to display a list of random users.
 As React does not support link:https://facebook.github.io/react/docs/jsx-gotchas.html#custom-html-attributes[custom attributes] on standard elements, [vaadinelement]#vaadin-grid# DOM API cannot be fully utilized in the initialization.
 Fortunately, [vaadinelement]#vaadin-grid# also provides corresponding JavaScript APIs.

 Selecting an item in the [classname]#UserGrid# is handled by the [classname]#UserApp# component.
 The selection is handled by displaying the photo of the selected user below the [vaadinelement]#vaadin-grid#.

 The code below can be run and forked as a JSFiddle at https://jsfiddle.net/pw1nLaL8/2/.

 [source, javascript]
 ----
 // Create the UserGrid class
 var UserGrid = React.createClass({
  render: function(){
    return (
      '<vaadin-grid></vaadin-grid>';
    )
  },

  componentDidMount: function() {
    var _this = this;
    var vGrid = ReactDOM.findDOMNode(this);

    // Let the mounted <vaadin-grid> upgrade
    (function wait() {
      if (vGrid.selection) {
        // Assign the data source
        vGrid.items = _this.items;
        vGrid.size = 1000;

        // Bind selection listener
        vGrid.addEventListener("selected-items-changed", _this.onRowSelect);

        var pictureRenderer = function(cell) {
          cell.element.innerHTML = "<img style='width: 30px' src='" + cell.data + "'></img>";
        };

        // Define columns
        vGrid.columns = [
          {name: "user.picture.thumbnail", width: 100, renderer: pictureRenderer},
          {name: "user.name.first"},
          {name: "user.name.last"},
          {name: "user.email"},
        ];

      } else {
        setTimeout(wait, 50);
      }
    })();
  },

  items: function(params, callback) {
    var url = 'https://randomuser.me/api?index=' + params.index + '&results=' + params.count;
    getJSON(url, function(data) {
      callback(data.results);
    });
  },

  onRowSelect: function(e) {
    var onUserSelect = this.props.onUserSelect;
    var index = e.target.selection.selected()[0];
    e.target.getItem(index, function(err, data) {
      onUserSelect(err ? undefined : data.user);
    });
  }
 });

 var UserApp = React.createClass({

  render: function() {
    var userImage;
    if (this.state.selected) {
      userImage = <img className="user-image" src={this.state.selected.picture.large} ></img>;
    }

    return (
      <div>
        <UserGrid onUserSelect={this.userSelect}></UserGrid>
        {userImage}
      </div>
    );
  },

  getInitialState: function() {
    return {};
  },

  userSelect: function(user) {
    this.setState({selected: user});
  }
 });

 HTMLImports.whenReady(function(){
  ReactDOM.render('<UserApp></UserApp>', document.getElementById('container'));
 });
 ----
--- a/docs/integrations/integrations-vuejs.adoc
+++ b/docs/integrations/integrations-vuejs.adoc
@@ -1,107 +0,0 @@
 ---
 title: Vue.js Integration
 order: 2
 layout: page
 ---

 # Vue.js Integration

 link:https://vuejs.org/[Vue.js] is a library for building interactive web interfaces with JavaScript.
 Vue's components can be link:https://vuejs.org/v2/guide/comparison.html#Polymer[loosely compared] to Vaadin Elements and both provide a very similar development style.


 == Quick Start

 . Before installing Vaadin Elements, you first have to install and initialize your application with Bower.
 Vaadin Elements uses link:http://bower.io/[Bower] for package management.
 +
 [source,subs="normal"]
 ----
 [prompt]#$# [command]#npm# install bower -g
 [prompt]#$# [command]#bower# init
 ----

 .  By default, Bower installs dependencies to the [filename]#bower_components# directory.
 But if you are using Webpack or Vue CLI, it expects static files to be in the [filename]#static# directory.
 Thus, create the [filename]#.bowerrc# file in the root directory, with the following content:
 +
 [source,json]
 .&#46;bowerrc
 ----
 {
  "directory" : "static/bower_components"
 }
 ----

 . Now, you can install all the Vaadin elements that you need in your application.
 For instance, to install [elementname]#https://vaadin.com/elements/-/element/vaadin-date-picker[vaadin-date-picker]# element, run the following:
 +
 [source,subs="normal"]
 ----
 [prompt]#$# [command]#bower# install --save [replaceable]#vaadin-date-picker#
 ----

 . For better browser support, you need to add the Web Components polyfill to the [elementname]#head# section of your [filename]#index.html#.
 This will allow the use of Vaadin Elements in all evergreen browsers.
 +
 [NOTE]
 Web Components are natively supported in Chrome and Opera and the polyfill is not required.
 +
 [source, html]
 .index.html
 ----
 <script src="static/bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
 ----

 . Now you can import and use Vaadin Elements in your Vue Component.
 +
 [source,html,subs="normal"]
 .src/components/DateSelect.vue
 ----
 <template>
  <div class="date-select">
    <link rel="import" href="static/bower_components/vaadin-date-picker/vaadin-date-picker.html">
    <vaadin-date-picker
        class="custom-theme"
        :label="label"
        :value="date"
        v-on:value-changed="onDateChange">
    </vaadin-date-picker>
  </div>
 </template>

 <script>
 export default {
  data () {
    return {
      label: 'Select a date',
      date: '2016-12-31'
    }
  },
  methods: {
    onDateChange: function (e) {
      console.log('date changed: ' + e.detail.value)
    }
  }
 }
 </script>
 ----
 +
 [NOTE]
 Importing elements directly in the component facilities a lazy loading of elements, and they are imported only when they are actually used.
 Otherwise, you might import the element in your [filename]#index.html#.

 . Custom styling does not work inside a Vue component.
 To style an element, create custom style tags in your [filename]#index.html#.
 +
 [source, html]
 .index.html
 ----
 <style is="custom-style">
  vaadin-date-picker {
    --primary-color: red;
    --primary-text-color: green;
    --secondary-text-color: yellow;
  }
 </style>
 ----