Docs: Updating documentation

Author: jarrodek

docs/cors.md

@@ -38,192 +38,9 @@ This configuration changes the request endpoint from `http://domain.com/path/?qu
 
 The proxy URL won't be visible by the user. The user can't do anything to change this behavior unless your application includes a custom UI that supports such a change.
 
-## Handling HTTP request by the hosting website / application
+## Handling HTTP request by the hosting application
 
-When the user runs the request from the "try it" screen, API Console fires the `api-console-request` [custom event](https://developer.mozilla.org/en/docs/Web/API/CustomEvent). If your application can handle the transport (by providing a proxy, for example), listen for this event, and cancel it by calling `event.preventDefault()`. If the event is cancelled, API Console listens for the `api-console-response` custom
+When the user runs the request from the "try it" screen, API Console fires the `api-request` [custom event](https://developer.mozilla.org/en/docs/Web/API/CustomEvent). If your application can handle the transport (by providing a proxy, for example), listen for this event, and cancel it by calling `event.preventDefault()`. If the event is cancelled, API Console listens for the `api-response` custom
 event that should contain response details. Otherwise, the console uses the build in fallback function to get the resource using Fetch API / XHR.
 
-#### api-console-request custom event
-
-The Event `detail` object contains following properties:
-
-Property | Type | Description
-----------------|-------------|----------
-`url` | `String` | The request URL. If proxy is set, it will be the final URL with the proxy value.
-`method` | `String` | The HTTP method
-`headers` | `String` | HTTP headers string to send with the message
-`payload` | `String` | Body to send
-
-#### api-console-response
-
-This event must be fired when the hosting app finishes the request. It must contain a generated Request
-and Response object as defined in the [Fetch specification](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch). API Console includes a polyfill for the Fetch API.
-
-Property | Type | Description
-----------------|-------------|----------
-`request` | `Request` | The request object as defined in the Fetch API spec. See [Request docs](https://developer.mozilla.org/en-US/docs/Web/API/Request) for more information.
-`response` | `Response` | The response object as defined in the Fetch API spec. See [Response docs](https://developer.mozilla.org/en-US/docs/Web/API/Response) for more information.
-`isXhr` | `Boolean` | Default is `true`. Indicates that the transport method doesn't support advanced timings and redirects information. See [request-panel](https://elements.advancedrestclient.com/elements/raml-request-panel) documentation for more information.
-`error` | `Error` | When the request / response encounters an error (`request.ok` equals `false`), the error object is set with the human readable message for the user.
-
-#### Example with handling request / response events
-
-```javascript
-// Start time of executing the request
-var startTime;
-// Initial request data passed by the event.
-var requestData;
-/**
- * Creates a Headers object based on the HTTP headers string.
- *
- * @param {String} headers HTTP headers.
- * @return {Headers} Parsed headers object.
- */
-function createHeaders(headers) {
-  if (!headers) {
-    return new Headers();
-  }
-  var result = new Headers();
-  var list = headers.split('\n').map(function(line) {
-    var _parts = line.split(':');
-    var _name = _parts[0];
-    var _value = _parts[1];
-    _name = _name ? _name.trim() : null;
-    _value = _value ? _value.trim() : null;
-    if (!_name || !_value) {
-      return null;
-    }
-    return {
-      name: _name,
-      value: _value
-    };
-  }).filter(function(item) {
-    return !!item;
-  });
-  list.forEach(function(item) {
-    result.append(item.name, item.value);
-  });
-  return result;
-}
-/**
- * Creates a request object from the event's request data.
- *
- * @param {Object} data Latest request data as in the `api-console-request` object event.
- * @return {Request} The Request object.
- */
-function createRequest(data) {
-  var init = {
-    method: data.method,
-    mode: 'cors'
-  };
-  if (data.headers) {
-    init.headers = createHeaders(data.headers);
-  }
-  if (['GET', 'HEAD'].indexOf(data.method) !== -1) {
-    data.payload = undefined;
-  } else {
-    if (data.payload) {
-      init.body = data.payload;
-    }
-  }
-  return new Request(data.url, init);
-}
-/**
- * Creates a response object from the response data.
- * If the response is invalid then returned Response object will be errored.
- *
- * @param {XMLHttpRequest} xhr The XHR object used to make a connection.
- * @return {Response} The response object.
- */
-function createResponse(xhr) {
-  var status = xhr.status;
-  if (!status || status < 200) {
-    return Response.error();
-  }
-  var init = {
-    status: status,
-    statusText: xhr.statusText
-  };
-  var headers = xhr.getAllResponseHeaders();
-  if (headers) {
-    init.headers = createHeaders(headers);
-  }
-  try {
-    return new Response(xhr.responseText, init);
-  } catch (e) {
-    return Response.error();
-  }
-}
-// General error handler.
-function errorHandler(e) {
-  var loadTime = performance.now() - startTime;
-  var request = createRequest(requestData);
-  var detail = {
-    request: request,
-    response: Response.error(),
-    loadingTime: loadTime,
-    isXhr: true,
-    error:  new Error('Resource is unavailable')
-  };
-  var event = new CustomEvent('api-console-response', {
-    cancelable: false,
-    bubbles: true,
-    composed: true,
-    detail: detail
-  });
-  document.body.dispatchEvent(event);
-}
-// Handler for load event
-function loadHandler(e) {
-  var loadTime = performance.now() - startTime;
-  var request = createRequest(requestData);
-  var response = createResponse(e.target);
-  var detail = {
-    request: request,
-    response: response,
-    loadingTime: loadTime,
-    isXhr: true
-  };
-  if (!response.ok) {
-    detail.error = new Error('Resource is unavailable');
-  }
-  var event = new CustomEvent('api-console-response', {
-    cancelable: false,
-    bubbles: true,
-    composed: true,
-    detail: detail
-  });
-  document.body.dispatchEvent(event);
-}
-// Handler to the event, sends the request
-function consoleRequestHandler(e) {
-  requestData = e.detail;
-  var xhr = new XMLHttpRequest();
-  xhr.open(requestData.method, requestData.url, true);
-  if (requestData.headers) {
-    requestData.headers.split('\n').forEach(function(header) {
-      var data = header.split(':');
-      var name = data[0].trim();
-      var value = '';
-      if (data[1]) {
-        value = data[1].trim();
-      }
-      try {
-        xhr.setRequestHeader(name, value);
-      } catch (e) {
-        console.log('Can\'t set header ' + name ' in the XHR call.');
-      }
-    });
-  }
-  xhr.addEventListener('load', loadHandler);
-  xhr.addEventListener('error', errorHandler);
-  xhr.addEventListener('timeout', errorHandler);
-  try {
-    startTime = performance.now();
-    xhr.send(requestData.payload);
-  } catch (e) {
-    errorHandler(e);
-  }
-}
-window.addEventListener('api-console-request', consoleRequestHandler);
-```
+See https://github.com/advanced-rest-client/api-components-api/blob/master/docs/api-request-and-response.md for detailed documentation of the request events.

docs/gh-pages.md

@@ -6,17 +6,9 @@ This example shows how to use Travis-CI to push API Console with the API documen
 
 ## Overview
 
-[docs/gh-pages/.travis.yml](gh-pages/.travis.yml) file contains a set of directives that Travis understands and executes. This file contains a minimal setup for the API console generation but you can change it.
+[docs/gh-pages/.travis.yml](gh-pages/.travis.yml) file contains a set of directives that Travis understands and executes. This file contains a minimal setup for the API console generation.
 
-First, Travis installs node dependencies, which in this case is the
-[api-console-builder](https://www.npmjs.com/package/api-console-builder) module as defined in the [docs/gh-pages/package.json](gh-pages/package.json) file:
-
-```yaml
-before_script:
-- npm install
-```
-
-Next, Travis executes [docs/gh-pages/deploy.sh](gh-pages/deploy.sh) that processes your private key associated with a GitHub account, as discussed below. Finally, Travis checks out the latest version of your API, creates the console, and publishes the console in `gh-pages` branch.
+Travis executes [docs/gh-pages/deploy.sh](gh-pages/deploy.sh) that processes your private key associated with a GitHub account, as discussed below. Finally, Travis checks out the latest version of your API, creates the console, and publishes the console in `gh-pages` branch.
 
 ```yaml
 script: bash ./deploy.sh
@@ -44,7 +36,7 @@ If you already have generated keys, go to step 5.
 ```
   Enter a file in which to save the key (/Users/you/.ssh/id_rsa): /Users/you/.ssh/gh-travis_rsa
 ```
-  We use this filename in the build script.  
+  We use this filename in the build script.
 
 4. Do _not_ set a password. When Travis runs the script there's no way to respond to a password prompt. Consequently, do not use this key for any other purpose. Doing so would be unsafe. Also, keep the key in a location that nobody can access.
 

docs/gh-pages/.travis.yml

@@ -1,8 +1,6 @@
 language: node_js
 node_js:
 - stable
-before_script:
-- npm install
 script: bash ./deploy.sh
 before_install:
 # Will be filled by travis CLI command

docs/gh-pages/build.js

@@ -1,15 +1,17 @@
 /**
- * This file runs the API Console builder node module to create a bundled file of sources.
+ * This file runs the API Console builder node module to create
+ * a bundled file of sources.
  */
+
 const builder = require('api-console-builder');
-const fs = require('fs');
 
 builder({
-  src: 'https://github.com/mulesoft/api-console/archive/release/4.0.0.zip',
-  dest: 'build',
-  raml: 'api/api.raml', // note that the deploy.sh script will clone the repo to api/ folder.
-  useJson: true,
-  verbose: true
+  verbose: true,
+  destination: 'build', // Optional, default to "build"
+  // note that the deploy.sh script will clone the repo to api/ folder.
+  api: 'api/api.raml',
+  apiType: 'RAML 1.0',
+  tagName: '5.0.0-preview' // builds the console from specific version
 })
 .then(() => {
   console.log('Build complete');

docs/gh-pages/deploy.sh

@@ -9,7 +9,7 @@ chmod 600 gh-travis_rsa
 eval `ssh-agent -s`
 ssh-add gh-travis_rsa
 
-# Just an example, you can build the console for any branch. We will buil for master only.
+# Just an example, you can build the console for any branch. We will build it for master only.
 if [ "$TRAVIS_PULL_REQUEST" != "false" -o "$TRAVIS_BRANCH" != "$SOURCE_BRANCH" ]; then
     echo "Skipping deploy."
     exit 0
@@ -20,7 +20,7 @@ REPO=`git config remote.origin.url`
 SSH_REPO=${REPO/https:\/\/github.com\//git@github.com:}
 SHA=`git rev-parse --verify HEAD`
 
-# Cclone the repo a foler. We'll use api/ as a working dir.
+# Clone the repo to current location. We'll use "api/" as a working dir.
 git clone $REPO api
 
 # Build the console out of the latest API release.