kux
The kwaeri user experience library.
The kwaeri user experience library is part of the kwaeri suite of developer tools, which contribute a standardization for developing applications in a browser.
kwaeri user experience (kux, for short) implements and extends Material Design, adding several components and features, and simplifies development of modern applications. By leveraging asynchronous technologies and making use of responsive interface design practices, kux presents an innovative experience to end users.
Getting Started
Prepare for Installation
The following section covers the prerequisites for working with @kwaeri/user-experience.
cd ~/workspaces/kwaeri
mkdir kux-demo
Next, you'll need a file for holding markup that you will demo as you go though this document. Let's go ahead and get that ready:
[out] ...
cd kux-demo
touch index.html
That's it! You've got a basic project structure you can use while following along with this walk-through.
Boilerplate
A kwaeri application is a HTML5 document. The following is boilerplate markup for a HTML5 document which you can use to follow along through this walk-through and try out the many features listed through out the API section.
Installing the Sources
Before you can include the kwaeri user experience library in your HTML5 document, you'll need to download the distribution sources. The following section covers methods by which to obtain the library
npm install @kwaeri/user-experience
[out] ...
#### Direct Download
If you're building a custom project, you can also download kux using the dropdown menu (download icon) in the **topAppBar** at the top of this document. The files are offered in several different archive formats for your convenience.
Building the Library
While the kwaeri user experience library is distributed such that it is ready to use out of the box, if you are using npm to obtain the sources - theme values may be modified and distribution files rebuilt for a custom look and feel.
cd ~/workspaces/kwaeri/kux-demo/node_modules/@kwaeri/user-experience
npm install
[out] ...
That should do it, but if you have trouble installing the devDependencies (perhaps because you have `NODE_ENV=production` set?), you can try:
npm install --only=dev
[out] ...
#### Customizing the Theme
Browse to the **scss** directory of the @kwaeri/user-experience library (found in `node_modules/@kwaeri/user-experience/`), open the **kux_md--comprehensive.scss** file, and additionally the **core/variables/_base.scss** file.
By modifying the **theme**, **font**, and other settings at the top of each file, it is possible to completely customize the look and feel of your application. For deeper customization you could also override any of the styles you'd like, and even provide your own, by working in the **core/customize.scss** file.
You'll undoubtedly play with the styles until you are satisfied with the look and feel. When you've made some changes that you're ready to try, run the following command in your terminal/command prompt:
[out] ...
gulp
[out] ...
If you have worked with a kwaeri-platform application before, you'll likely already know how to include the scss into your main application's source - and furthermore, how the JavaScript is included into your application via Webpack. This documentation, however, will not go into the details of doing so - though we've already ensured that you're demo application is properly linked to the sources required, even if you've rebuilt them.
Including the Library
Including the kwaeri user experience libary in your application is as simple as referencing the proper link and script tags in your HTML5 document.
Examples
How it works
The following section covers how the tutorials section works
Sample Documentation
The following section describes the sample documentation offered in this walkthrough.
Navigation 101
The following section covers adding a topAppBar to a HTML5 document, and provides the markup for one with numerous options enabled.
Navigation 102
The following section covers the Drawer component from Material Design, and further covers transforming one into a full-fledged side-menu.
Articles
The following section covers content flow post-navigation, complimenting the walkthrough after adding the topAppBar and sideMenu.
Sections
The following section covers sections, or blocks of markup which represent a single topic supporting the focus of an article.
` tags, which yeild a horizontal line. The next section, while more complex than what we've seen so far - will wrap up our documentation flow.
Fragments
The following section covers the final piece of the example documentation fow - fragments.
API
buttons()
This section covers how to implement - and make use - of Material Design Buttons through kux.
chartables()
This section covers how to implement - and make use - of Chart.js through kux.
checkboxes()
This section covers how to implement - and make use - of the Material Design checkbox component through kux.
collapsibles()
This section covers how to implement - and make use - of the collapsible feature from kux.
collapsibles()
This section covers how to implement - and make use - of the collapsible feature from kux.
controls()
This section covers the controls() method of the kux library.
destroy()
This sections covers the destroy() method of the kux library.
draggables()
This section covers the draggables method offered by the kux library.
This is a draggable element.
drawers()
This section covers how to implement - and make use - of Material Design Drawers through kux.
dropdowns()
This section covers how to implement - and make use of - Material Design dropdowns through kux.
expandables()
This section covers how to implement - and make use of - Material Design Expandables through kux.
floatingLabels()
This section covers how to implement - and make use of - Material Design floating-labels through kux.
form()
This section covers how to implement - and make use of - the form method provided by kux.
formFields()
This section covers how to implement - and make use of - Material Design form-fields through kux.
iconToggles()
This section covers how to implement - and make use of - the Material Design Components for web form control component [icon toggles] provided by kux.
lineRipples()
This section covers how to implement - and make use of - the Material Design Components for web form control component [line ripples] provided by kux.
lytebox()
The lytebox() method initializes an application lytebox [modal].
parallaxes()
The parallaxes() method initializes parallax configurations.
receive()
The receive() method eases interpreting the response to asynchronous requests.
request()
The request() method eases making asynchronous requests.
scrollToTarget()
The scrollToTarget() method handles automatically scrolling content.
scrollToX()
The scrollToX() method handles automatically scrolling content.
sidebars()
The sidebars() method initializes application sidebars.
systemMessage()
The systemMessage().method displays a message to the application user.
toolbar()
The toolbars() method initializes any application toolbars.
topAppBars()
The topAppBars() method initializes TopAppBars for an application.