flightkit 1.0.1-alpha.0 → 2.0.0-beta.0

package/README.md

@@ -1,310 +1,48 @@
-![flightkit-200](https://user-images.githubusercontent.com/5612789/155478647-ad0f1ce8-0ce6-4396-b8e6-8287897896e5.png)
-# Flightkit
-
-Flightkit is a UI kit for rapidly creating [Flybits](https://flybits.com) enabled web applications.  Composed of [native web components](https://www.webcomponents.org/introduction) you can simply drop pure HTML tags into your application and immediately view curated experiences through the Flybits platform.
-
-## Table of Contents
-1. [Compatibility](#compatibility)
-2. [Dependencies](#dependencies)
-3. [Getting Started](#getting-started)
-4. [Authentication Strategies](#authentication-strategies)
-5. [Component Hierarchy](#component-hierarchy)
-6. [Extensible Content Types](#extensible-content-types)
-    6.1. [Building Your Own Viewable](#building-your-own-viewable)
-
-## Compatibility
-
-All modern browsers are supported however if you would like to support Internet Explorer 11 (not recommended) you must include the polyfill below.
-
-* Webcomponentsjs Polyfill: [webcomponents/webcomponentsjs](https://github.com/WebComponents/webcomponentsjs)
-
-1. Fetch the package
-    
-  ```shell
-  $ npm install @webcomponents/webcomponentsjs --save
-  ```
-
-2. Include the package in your page
-
-    ```html
-    <script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-lite.js" type="text/javascript"></script>
-    ```
-
-## Dependencies
-
-This UI kit requires the core Flybits.js SDK to be present in the global `window` namespace.
-* [Flybits.js](https://www.npmjs.com/package/flybits)
-
-1. Fetch the package
-    
-    ```shell
-    $ npm install flybits --save
-    ```
-
-2. Include the library in your page
-
-    ```html
-    <script src="node_modules/flybits/dist/flybits.js" type="text/javascript"></script>
-    ```
-    
-Alternatively you can simply include the library using a cdn link:
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/flybits@2.6.0/dist/flybits.min.js"></script>
-```
-
-## Getting Started
-
-1. Fetch the package
-    
-    ```shell
-    $ npm install flightkit --save
-    ```
-
-2. Include the library in your page
-
-    ```html
-    <script src="node_modules/flightkit/dist/flightkit.js" type="text/javascript"></script>
-    ```
-
-3. Start using Flybits html components
-
-    ```html
-    <flybits-core projectID="12345678-D5B0-4602-83B4-2EDC10A65838">
-      <flybits-list>
-        <flybits-slot></flybits-slot>
-      </flybits-list>
-    </flybits-core>
-    ```
-
-## Authentication Strategies
-
-By default if only specifying project ID as an attribute on the Core element the Flightkit will facilitate anonymous login to the Flybits platform.
-
-```html
-<flybits-core projectID="12345678-D5B0-4602-83B4-2EDC10A65838">
-  <flybits-list>
-    <flybits-slot></flybits-slot>
-  </flybits-list>
-</flybits-core>
-```
-
-If another identity provider (IdP) protocol/workflow is required, JavaScript is already typically required thus in order set IdP details a little JavaScript is required to be performed on the Core element
-
-```html
-<flybits-core>
-  <flybits-list>
-    <flybits-slot></flybits-slot>
-  </flybits-list>
-</flybits-core>
-```
-
-```javascript
-var flbCore = document.querySelector('flybits-core');
-flbCore.init({
-  idp: new Flybits.idp.ApiKeyIDP({
-    projectID: '12345678-D5B0-4602-83B4-2EDC10A65838',
-    email: 'bob1234',
-    apiKey: 'EAD37756-58B6-4EF7-B5BD-E468D497611A'
-  })
-});
-```
-
-## Component Hierarchy
-
-### FlybitsCore `<flybits-core>`
-
-This component is meant to be the root governing element of your Flybits embedded content.  It is responsible for content API querying and will propagate child native html events outward (including deep linking and data change events).  Think of this element as the brains and data store of anything meant to be rendered as children.
-
-```html
-<flybits-core>
-  ...
-</flybits-core>
-```
-
-### FlybitsLayout `<flybits-layout>`
-
-This is a foundational component meant to be extended/sub-classed.  This type of component must live within a **FlybitsCore** element and is meant to layout the resultant content from the Core.  It has the opportunity to add other structural elements around the main content layout such as headers, tabs, etc.  FlybitsLayout components come with default support for rendering out of the box content types known as Viewables but also support the override and addition of new Viewables.  More info can be found in [Extensible Content Types](#extensible-content-types).
-
-Currently supported out of the box layouts include:
-- FlybitsList `<flybits-list>`
-
-Because layouts can/will have other structural and extension capabiltiies one must use a **FlybitsSlot** to specify where the actual content will be rendered within the layout.
-
-```html
-<flybits-core>
-  <flybits-list>
-    <div class="btn settings" slot="header">Settings</div>
-    <flybits-slot></flybits-slot>
-  </flybits-list>
-</flybits-core>
-```
-
-### FlybitsSlot `<flybits-slot>`
-
-This is a common utility component used to filter/map incoming content instances and their types to available UI component types (Viewables).
-
-### FlybitsViewable `<flybits-viewable>`
-
-This is a foundational component meant to be extended/sub-classed.  It is meant to represent the output of particular content types.  FlybitsViewables are simple components only responsible for rendering JSON data that it has been passed.
-
-Currently supported out of the box Viewables include:
-- CardButtonLink `<card-buttonlink>`
-- CardTextLink `<card-textlink>`
-
-This class of component is not needed to be explicitly used.  As long as they are registered as discussed in [Extensible Content Types](#extensible-content-types), the `<flybits-slot>` will map and render it accordingly.
-
-## A Note About Styling
-
-It has been a conscious design choice to render all rendered children of `<flybits-slot>` outside of the shadow DOM.  This allows for full CSS customization of any child elements instead of a select amount of CSS variables inside the shadow DOM.
-
-## Extensible Content Types
-
-All **FlybitsViewable** components must have a constant known as `TEMPLATETYPE` which is used to map the Viewable to Flybits Content Template types.
-
-This mapping can be updated by inserting Viewable components into the `<flybits-layout>` `viewables` slot component.  
-
-For example the out of the box `<card-buttonlink>` component has a `TEMPLATETYPE = "concierge-card-buttons"`.  If you would like to override this mapping with a new component, like `<unicorn-card>`, first you must ensure that `<unicron-card>` has the same `TEMPLATETYPE = "concierge-card-buttons"`.  Next you can insert the FlybitsViewable subclass into the `viewables` slot of the layout parent.
-
-```html
-<flybits-list>
-  <unicorn-card slot="viewables"></unicorn-card>
-  <flybits-slot></flybits-slot>
-</flybits-list>
-```
-
-Now you can add new content rendering capabilities to your layouts and optionally override the out of the box.
-
-### Building Your Own Viewable
-
-#### 1. Extend Base Class
-
-First you must extend the **FlybitsViewable** base class.  
-
-If you are using modules:
-
-```javascript
-import {FlybitsViewable} from 'flightkit'
-
-class CustomComponent extends FlybitsViewable
-```
-
-if you are not using modules **flightkit** is accessible through the `window` namespace.
-
-```javascript
-class CustomComponent extends flightkit.FlybitsViewable
-```
-
-#### 2. Declare reactive properties
-
-Next you must delcare properties that this viewable will need to be reactive.
-
-```javascript
-class CustomComponent extends FlybitsViewable{
-  static properties = {
-    content: {},
-    TEMPLATETYPE: {
-      type: String
-    }
-  }
-...
-```
-
-#### 3. Initialize and Set Template Type
-
-```javascript
-class CustomComponent extends FlybitsViewable{
-  static properties = {
-    content: {},
-    TEMPLATETYPE: {
-      type: String
-    }
-  }
-  constructor(){
-    super();
-    this.TEMPLATETYPE = 'template-type-id';
-  }
-...
-```
-
-#### 4. Transform Content Data (optional)
-
-```javascript
-class CustomComponent extends FlybitsViewable{
-  static properties = {
-    content: {},
-    TEMPLATETYPE: {
-      type: String
-    }
-  }
-  constructor(){
-    super();
-    this.TEMPLATETYPE = 'template-type-id';
-  }
-  getData(){
-    // get root content data payload
-    var rootObj = super.getData();
-    if(!rootObj){
-      return;
-    }
-
-    // perform necessary transformations 
-
-    return retObj;
-  }
-...
-```
-
-#### 5. Implement Render Function
-
-```javascript
-import {html} from 'flightkit';
-
-class CustomComponent extends FlybitsViewable{
-  static properties = {
-    content: {},
-    TEMPLATETYPE: {
-      type: String
-    }
-  }
-  constructor(){
-    super();
-    this.TEMPLATETYPE = 'template-type-id';
-  }
-  // optional
-  getData(){
-    // get root content data payload
-    var rootObj = super.getData();
-    if(!rootObj){
-      return;
-    }
-
-    // perform necessary transformations 
-
-    return retObj;
-  }
-  render(){
-    // get data object
-    var root = this.getData();
-    if(!root){
-      return '';
-    }
-
-    return html`
-      <!-- custom HTML rendering -->
-    `;
-  }
-  // optionally prevent rendering in shadow DOM
-  createRenderRoot(){
-    return this;
-  }
-}
-```
-
-#### 6. Register Custom Element
-
-Here you can define and register your custome HTML element tag.  You can declare any dasherized string as your HTML element tag and assign your subclassed **FlybitsViewable**.
-
-```javascript
-customElements.define('custom-component', CustomComponent);
-```
+![flightkit-200](https://js.flybits.app/images/Flybits-Header-flightkit-thin.png)
+# Flightkit
+
+v2.0.0-beta.0
+
+Flybits Flightkit is a fully contained, framework agnostic solution for personalized UI and Content within your web applications.  Composed of [native web components](https://www.webcomponents.org/introduction) you can simply drop pure HTML tags into your application and view curated experiences from the [Flybits](https://flybits.com) platform.
+
+## Quickstart
+
+Here is the bare minimum code required to quickly embed a Flybits powered UI container within your existing application.  For more flexible and robust options, read more in the following sections starting with Installation.
+
+1. **Import**
+
+```javascript
+<!-- Import the Flybits.js core SDK -->
+<script src="<!-- coming soon -->"></script>
+<!-- Import the Flightkit library -->
+<script type="module" src="<!-- coming soon -->"></script>
+```
+
+> Note: NPM and CDN deployments will be available once full release is made.
+
+2. **Declare**
+
+```javascript
+<flybits-slot ref-id="homepage-carousel"></flybits-slot>
+```
+
+3. **Authenticate**
+
+```javascript
+<script>
+  // Use existing Flybits.js authentication strategies
+  Flybits.init({
+    HOST: 'https://api.demo.flybits.com'
+  }).then(function(){
+    return Flybits.Session.connect(new Flybits.idp.AnonymousIDP({
+      projectID: '1230D8CA-2173-2226-B70A-96A092348C68'
+    }))
+  })
+</script>
+```
+
+4. **Enjoy Contextual Personalized Content**
+
+![Carousel of curated content](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1furhUrHM7k3yZOnffSu%2Fuploads%2FFmJd3OrB6TWt97pumBDt%2FScreenshot%202024-02-12%20024159.png?alt=media&token=4e0ede9e-0c3c-42ac-a322-4323b37c3bb0)
+
+> Note: Layouts & content must be configured within the Flybits Experience Studio for them to appear within a FlybitsSlot.