@brikcss/ds-webalias v0.3.1

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*

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

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.

Creating or modifying webalias properties

You can modify any of these webalias properties, or create your own by doing the following:

// Create a custom webalias property.
WebAlias.propsMap.customProp = function() {
    return `Custom property for ${this.user.name()}!`;
};
// Modify an existing webalias property.
WebAlias.propsMap.name = function() {
    return `${this.user.last}, ${this.user.first}`;
};

These are used in the markup as usual:

<web-alias prop="customProp"></web-alias>

which, for the user "John Doe", will display the following in the UI:

Custom property for Doe, John!

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.