@brikcss/ds-webalias

DirectScale WebAlias Replication Plugin

About

[ IMPORTANT ]: Brikcss follows semantic versioning. Since this package is currently at major version zero, "anything may change at any time", and it "should not be considered stable".

This webalias module connects with the DirectScale, Inc. webalias API to help turn any website into a replicated solution. The plugin can either check the URL to auto-detect the webalias and client/company, or they can be manually configured.

This solution is built on Brikcss Element, a native Web Components library.

Contributing

We ❤️❤️❤️ contributions of any kind, whether it's bug reports, questions or feature requests, pull requests, and especially spreading some love about this project to your friends and co-workers!

Read our contributing guidelines and get involved to support this project.

Browser Support*

Chrome	Firefox	Safari	Edge	IE
✓	✓	✓	✓	11**

*With the proper polyfills.
**IE11 can be supported with a transpiled build for legacy browsers.

Install

From NPM:

npm install -D @brikcss/ds-webalias

From GitHub:

Download the latest release.

Note: File paths are written for NPM installs. If you use the GitHub release, make sure to remove node_modules/@brikcss/ds-webalias from any file paths.

Quick Start

Build your component in less than 5 minutes:

1. Include Web Components polyfills.

2. Include the ESM Browser bundle and define your element:

   // app.js
   import { WebAlias } from 'node_modules/@brikcss/ds-webalias/dist/esm/webalias.browser.js';
   WebAlias.define('my-element');
   // or window.customElements.define('my-element', WebAlias)

3. Use your element:

   in HTML:

   <!-- index.html -->
   <my-element prop="name" before="Hello, " after="!"></my-element>

   If the webalias user's name is "John Doe", the UI will display "Hello, John Doe!".

   in JS:

   console.log(WebAlias.user.name); // John Doe

4. Tada! Check out the examples if you run into issues.

   Important: While the Browser ESM bundle works great for rapid development and prototyping, or if you only need to support modern browsers. For greater browser support, once your app is ready for production, replace the Browser ESM with the Vanilla ESM (or UMD bundle).

WebAlias element attributes

The web-alias HTML element can have the following attributes:

prop

Type: String (required)

Indicates the WebAlias property (from WebAlias.propsMap) to use.

before

Type: String

String to insert before the webalias property.

after

Type: String

String to insert after the webalias property.

API

WebAlias.webalias

Type: String Default: undefined (required)

The webalias passed to the webalias API. This -- along with the WebAlias.client and WebAlias.env properties -- will return the webalias user.

WebAlias.client

Type: String Default: undefined (required)

The client ID passed to the webalias API.

WebAlias.env

Type: String Default: undefined (required)

Environment to use. Can be dev, stage, or '' (live). This determines which database is checked.

WebAlias.urlCheck

Type: String[]|Boolean Default: ['webalias']

This value determines if and how WebAlias will automatically pull data from the URL. This is a String Array, with possible values of webalias, client, and env. For each property listed, WebAlias will automatically fetch that data property from the URL. By default, only the webalias property is checked for. Setting this value to true will check all three properties.

Note: For each property listed, WebAlias calls WebAlias[get${propertyName}FromUrl](host). This means, if you want to customize how WebAlias gets each piece of data, simply override the corresponding method. For example, to override how WebAlias gets the webalias property from the URL:

WebAlias.getWebaliasFromUrl = function (host) {...}

WebAlias.user

Type: Object Default: undefined

The webalias user data. The WebAlias.webalias, WebAlias.client, and WebAlias.env properties are used to fetch webalias data from DirectScale's replicated site webalias API, and then normalizing it as follows:

• first {String}: First name.
• last {String}: Last name.
• name {String}: First and last name.
• email {String}: Email address.
• phone {String}: Alias for phone1.
• phone1 {String}: Phone 1.
• phone2 {String}: Phone 2.
• city {String}: City.
• state {String}: State.
• country {String}: Country.
• about {String}: About the user.
• company {String}: Company.
• language {String}: Language.
• imageUrl {String}: URL for user's profile image.
• image {String}: User's profile <img />.
• imageData {String}: Image data.
• facebook {String}: Facebook handle.
• facebookLink {String}: Facebook anchor tag hyperlink.
• twitter {String}: Twitter handle.
• twitterLink {String}: Twitter anchor tag hyperlink.
• pinterest {String}: Pinterest handle.
• pinterestLink {String}: Pinterest anchor tag hyperlink.
• youTube {String}: YouTube handle.
• youTubeLink {String}: YouTube anchor tag hyperlink.
• linkedIn {String}: LinkedIn handle.
• linkedInLink {String}: LinkedIn anchor tag hyperlink.
• enrollmentUrl {String}: URL to user's enrollment site.
• enrollmentLink {String}: Enrollment anchor tag hyperlink.
• officeUrl {String}: URL to user's back office.
• officeLink {String}: Back office anchor tag hyperlink.
• shoppingUrl {String}: URL to user's shopping site.
• shoppingLink {String}: Shopping cart anchor tag hyperlink.
• replicatedSiteUrl {String}: URL to user's replicated site.
• replicatedSiteLink {String}: Replicated/marketing site anchor tag hyperlink.
• webalias {String}: User's webalias.
• customerId {String}: User's customer ID.
• backOfficeId {String}: User's back office ID.
• customerTypeId {String}: User's customer type ID.
• status {String}: User status.

WebAlias.propsMap

Type: Object Default: (see source)

WebAlias.propsMap maps out how WebAlias.user values are created. You can create new WebAlias.user properties by adding a new property to WebAlias.propsMap, and you can modify how any existing WebAlias.user[prop] is created by overriding the corresponding property in WebAlias.propsMap.

For example:

// Modify an existing webalias property.
WebAlias.propsMap.name = function() {
    return `${this.user.last}, ${this.user.first}`;
};
// Create a custom webalias property.
// NOTE: Since HTML markup is being created, use the render function provided (`r`) to correctly render your markup template.
WebAlias.propsMap.avatar = function(r) {
    return r`<img src="${this.user.imageUrl}" alt="User avatar for: ${
        this.user.first
    } ${this.user.last}" />`;
};

These are used in the markup as usual:

<web-alias prop="name"></web-alias> <web-alias prop="avatar"></web-alias>

which, for the user "John Doe", will display the following in the UI (along with the user's image):

Custom property for Doe, John!

WebAlias.shadowProps

Type: Array Default: ['facebookLink', 'twitterLink', 'pinterestLink', 'youTubeLink', 'linkedInLink', 'enrollmentLink', 'officeLink', 'shoppingLink', 'replicatedLink']

Some default properties in WebAlias.propsMap render with <slot> elements, which is part of the Shadow DOM specification. Shadow DOM encapsulates elements, but also prevents global CSS from being applied to children elements.

By default, Shadow DOM is not used, which allows global styles to be applied. However, if the prop attribute matches a value in WebAlias.shadowProps, shadow DOM will be created.

NOTE: You may always override properties of WebAlias.propsMap to control any of this behavior.

WebAlias.sourceUrl

Type: String|Function Default: https://${WebAlias.webalias}.${WebAlias.client}.directscale${WebAlias.env}.com

Passed in the headers (as the ApplicationUrl parameter) to the webalias API.

License

See License.