reveal-basis
v0.12.4
Published
Reveal Basis UI Kit
Downloads
8
Readme
Reveal Basis
Reveal Basis is a 'no dependencies' UI Kit which provides a set of tools to ease the front end developer job.
It aims to help with DOM elements that have to be shown/hidden (spinner, modals, notifications, etc.) by providing basis toggling and triggering mechanism.
You can have a look at some code samples on the library examples page.
Components are built to be the less opinionated possible. For example, at the 'core' level an .above element does nothing but appear on top of the page content.
The real benefits come from the 'modifier' layer where you can define some custom behaviour, constrain width or position, etc.
This separation of concerns allows you to benefit from the core mechanism of the library as a basis, a starting point from which you can add whatever fits your needs.
Reveal Basis supplies a few common modifiers, like modals or notification transitions. They can be used as examples to create your own and can easily be overridden if need be.
Table of Content
Installation
Install with regular <link> and <script> tags
Reveal Basis stylesheet and script file contain core mechanisms for toggling components and are needed for the library to work.
As you would do with a lot of other libraries, you can install it by inserting a <link> tag in your page's <head> and a <script> tag just before the body closing tag </body>:
Copy the reveal-basis.min.js and the reveal-basis.css files (both found in the dist folder) into your own project structure (eg. lib/js/reveal-basis.min.js) and insert them into your page template:
<!-- index.html -->
<head>
[...]
<link rel="stylesheet" href="lib/css/reveal-basis.css">
</head>
<body>
[...]
<script src="lib/js/reveal-basis.min.js"></script>
</body>You can test if the library is correctly set up with an above component:
<!-- index.html -->
<head>
<link rel="stylesheet" href="lib/css/reveal-basis.css">
</head>
<body>
<button data-toggle="above" data-target="#test-above">Show a modal-ipsum</button>
<div class="above --type-modal --position-top" id="test-above">
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aut beatae, ex maiores minus nesciunt provident quos vitae voluptatem. Distinctio dolor, explicabo iste minus molestiae ullam vero! Adipisci provident reiciendis veniam.
</div>
<script src="lib/js/reveal-basis.min.js"></script>
</body>Install with NPM
Reveal Basis is also available as a Node package.
To download and install it locally in your node_modules folder, just type this command within your project root folder:
npm install --save reveal-basis
You will then be able to use it the ES6 way, in your own script files:
// script.js
import * as reveal from 'reveal-basis';
reveal.notification.create({
message: "Hello World!",
duration: 3000 // in milliseconds
});Override default styles
One of the advantages of installing Reveal Basis via NPM is that you can change library style defaults with Sass.
You can find all the variables names used by the library in the src/style/components/_variables.scss file.
As the Sass keyword !default is used, you can override those values within your own Sass build process, as you would do with Bootstrap variables for example.
Let's see an example:
// _myOwnVariables.scss
$overlay-background-color: red;// main.scss
@import 'myOwnVariables'; // import your custom file first
@import '~reveal-basis/src/style/components/_variables.scss'; // the `~` stands for the node_modules folder
And now you can display your beautiful red overlay:
// script.js
import * as rb from 'reveal-basis';
rb.overlay.show();
Components
Above
above component's purpose is to display an element above the current page content (imagine a modal dialog box or a drawer type sliding menu).
Above: Usage
The triggering element (button or anchor) needs to contain data-toggle="above" attribute.
An eventual closing element needs to have the .dismiss class and to be inside the .above element. It can only be triggered with a 'click' event.
Above: Options
.--no-overlay
By default, triggering an .above element will also trigger the page's #overlay element. This behaviour can been changed by adding a .--no-overlay class on the .above element.
<div class="above --no-overlay">Lorem ipsum...</div>
.--lock-overlay
The .above element is dismissed when the page's #overlay is clicked. To change this behaviour, just add a .--lock-overlay class on the .above element.
<div class="above --lock-overlay">Lorem ipsum...</div>
Let's see some 'core' examples (just wait for the 'modifier' section for funnier stuff):
Trigger an .above with a button, through a [data-target] attribute
<!-- this button will toggle an '.above' element which 'id' is 'targeted-above' -->
<button data-toggle="above" data-target="#targeted-above">Show</button>
<!-- this is the '.above' element that will be triggered -->
<div id="targeted-above" class="above">
<button class="dismiss">Hide</button>
<p>Lorem ipsum dolor sit amet...</p>
</div>Trigger an .above with an anchor, through a [href] attribute
<!-- this anchor tag will toggle an '.above' element which 'id' is 'targeted-above' -->
<a data-toggle="above" href="#targeted-above">Show</a>
<!-- this is the '.above' element that will be triggered -->
<div id="targeted-above" class="above">
<button class="dismiss">Hide</button>
<p>Lorem ipsum dolor sit amet...</p>
</div>Trigger an .above with a button inside an .above-group element
<div class="above-group">
<!-- trigger and '.above' are enclosed by an '.above-group' element,
no need for a [data-target] or a [href] attributes here -->
<button data-toggle="above">Show</button>
<div class="above">
<button class="dismiss">Hide</button>
<p>Lorem ipsum dolor sit amet...</p>
</div>
</div>Above: Modifiers
Default .above behaviour can be extended by adding some modifier classes.
Transitions
Reveal Basis has a few bonus classes to make an .above element slide from one side of the view: .--transition-top, .--transition-right, .--transition-bottom, .--transition-left:
<div class="above --transition-left">
There is also a .--transition-scale modifier:
<div class="above --transition-scale">
Modal dialog box
The .--type-modal class constrains the .above element to the center of the view (horizontally and vertically).
Its dimensions are shrinked to half its width by default:
<div class="above --type-modal">
It can also leverage a transition modifier:
<div class="above --type-modal --transition-top">
Drawer
An 'drawer' type above (.--type-drawer) could be used to toggle a side menu, for example.
It has to use a static positioning modifier (eg. .--position-left) or a transition one (eg. .--transition-right).
Notes:
if no positioning modifier is used, an drawer type above (.--type-drawer) will behave the same as a simple .above element.
if you are overriding default variables, you can change the default dimension set by $above-drawer-dimension variable.
Customization examples
You can build upon the .above element and its modifiers to create your own custom elements.
Above: Note
If you are overriding default variables, be aware that global padding of above component has to be explicitly given through $above-padding variable as it is needed for positioning calculation.
The visibility state modifier class for an .above element is .is-visible.
Notification
notifications are alerting components types.
For example, a notification can be displayed as a feedback when the website user has performed an operation (eg. successful login).
Notification: Usage
Notifications can be used either after a page load (.notifications already on DOM) or triggered manually (eg. after a user has clicked on something)
Static notifications
The typical use for a static .notification is when a user has just been redirected to a new page after some kind of event.
eg. User is welcomed on their profile page after a successful login validation:
<div class="notification">Welcome on your profile page</div>
To display a notification on page load, just add the .notification class on one of your template's element.
It will 'convert' it to a notification along with all its content, including buttons, links, images, etc.
options:
To make it dismissible (with a click), just add the .dismiss class directly on the notification or on a trigger element inside it.
<div class="notification dismiss">Click anywhere to dismiss me</div>
<div class="notification">Click <span class="dismiss">here</span> to dismiss me</div>
To make the notification stick, add the .--sticky class, it will remove the default duration.
<div class="notification --sticky">I won't disappear... like ever...</div>
Static notifications: modifiers
A simple block appearing on top of your content being kind of limited, Reveal Basis supplies some useful modifiers.
position and width (--position-right, --width-auto):
transition - slide (--transition-slide):
transition - fade (--transition-fade):
Scripted notifications
The typical use for a scripted .notification is to give a direct feedback to the user (without redirection or page reload).
eg. User tried to submit a form but didn't fill a required field in.
The notification is triggered via javascript, using the library rb (reveal basis) global variable, along with its notification.create method.
<script>
[... (failed form validation)]
rb.notification.create("Please fill in all the required fields");
</script>Notification options
The create method accepts an option object as an optional second parameter:
<script>
[...]
rb.notification.create("Please fill in all the required fields", {
classes: [],
position: 'left',
width: 'auto',
transitions: ['slide', 'fade'],
duration: 6000,
speed: 300,
dismissOnClick: true,
});
</script>classes: an array of classes (eg. classes: ["error", "small"])
default: empty array
Just pass the css classes you want for your notification (eg. "my-warning-notification").
position: a string, either 'left' or 'right'
default: "left"
This option is used with width and/or transitions options.
Used with width: 'auto', the notification will stick on the position side of the screen (if its content isn't already screen wide).
Used with transitions: ['slide'], the notification will appear on screen from the position-hand side.
width: a string, either 'full' or 'auto'
default: "auto"
By default a notification will be displayed on the entire device screen width ('full').
If this option is set to 'auto', the notification with only be as wide as its content.
transitions: an array of transition modifiers (eg. transitions: ["slide", "fade", "insert-your-own"])
default: ["slide", "fade"]
Those two transitions are set by default because you will likely want them on your typical notification.
You can get rid of them by passing an empty array transitions: [] or your own custom transition(s).
Reveal Basis ships with a few transition modifiers:
"slide" will make your notification slide in and out of the screen.
"fade" will make it fade in and out.
You totally can combine all the transitions to achieve the effect you want.
To create your own transition, you will have to follow some simple rules:
its class name has to start with
.--transition-define the 'normal' and the 'is-visible' state
/* my custom transition */
.--transition-custom {
transform: rotateZ(0deg);
width: 100%;
}
.--transition-custom.is-visible {
transform: rotateZ(720deg);
width: 25%;
}duration: an int
default: 6000
Duration is set in milliseconds (1000 equals 1 second) and represents the time the notification will be displayed.
A duration of 0 will keep the notification indefinitely on screen.
speed: an int
default: 300
Speed is the transition speed. It will have no effect if no transitions are set transitions: [].
dismissOnClick: a boolean
default: true
As its name implies, if dismissOnClick option is passed, the notification will be dismiss when user click on it.
The library add a dismiss class on the notification. You can take advantage on this to add custom style to differentiate between dismissible notifications and non-dismissible ones.
Drop
drop component's purpose is to display a hidden element near the triggering element (eg. a dropdown menu).
Drop: Usage
Similarly to an .above, the triggering element (button, anchor, span or whatever) needs to contain data-toggle="drop" attribute.
To hide back the .drop element, just click again on the trigger button or move your mouse outside a .--trigger-hover .drop's trigger.
Let's see some 'core' examples:
Trigger a .drop with a button, through a [data-target] attribute
<!-- button triggered drop -->
<button data-toggle="drop" data-target="#button-trigger">Trigger drop with a button</button>
<div id="button-trigger" class="drop bg-gray">
<p>This drop has been triggered by <b>a button</b></p>
</div>Trigger a .drop with an anchor, through a [href] attribute
<!-- anchor triggered drop -->
<a data-toggle="drop" href="#anchor-trigger">Trigger drop with an anchor</a>
<div id="anchor-trigger" class="drop bg-gray">
<p>This drop has been triggered by <b>an anchor</b></p>
</div>Trigger a .drop with a button inside a .drop-group element
<!-- trigger and '.drop' are enclosed in an '.drop-group' element, no need for a [data-target] or a [href] attributes here -->
<div class="drop-group">
<button data-toggle="drop">Trigger drop within a group</button>
<div class="drop bg-gray">
<p>This drop has been triggered within <b>a drop-group</b>, without being specifically targeted</p>
</div>
</div>Drop: Modifiers
.--type-block
By default, a .drop element will appear above the page's content. Adding the .--type-block modifier will get the element inside the content flow, as a block type would.
<div class="drop --type-block">Lorem ipsum...</div>
.--trigger-hover
This option allow a .drop element to be triggered via an hover event on the trigger element.
Both trigger and .drop elements has to be inside the same .drop-group container:
<!-- drop is triggered by hovering the drop-group trigger element -->
<div class="drop-group">
<div data-toggle="drop">Trigger drop on hover</div>
<div class="drop --trigger-hover bg-gray">
<p>This drop has been triggered by an hover event</p>
</div>
</div>Overlay
On page load, Reveal Basis creates and appends an #overlay element on the DOM.
This #overlay is used for Above and Spinner components but is also available in your own code if you need it.
Overlay: Usage
Overlay: access via es6 modules
If you have installed Reveal Basis via NPM, you can access the component by importing the library and creating a new instance of the overlay:
// script.js
import * as reveal from 'reveal-basis';
let overlay = new reveal.overlay();Overlay: access via rb global variable
As long as you have imported the library with a <script> tag before using it, you have access to its global rb variable:
<!-- index.html -->
<head>
<link rel="stylesheet" href="lib/css/reveal-basis.css">
</head>
<body>
[...]
<script src="lib/js/reveal-basis.min.js"></script>
<script>
let overlay = new rb.overlay();
</script>
</body>Overlay: API
Whether you import the library or you include it via a <script> tag, you have now access to its API:
Overlay: show()
Nothing really fancy here, the overlay will appear on screen:
overlay.show();
Overlay: hide()
Hide the overlay:
overlay.hide();
Overlay: lock()
You can add the .is-locked class to the overlay by calling overlay.lock() before showing it:
overlay.lock();
overlay.show();
It is the default behaviour of an Above's Overlay when the option --lock-overlay is used.
By default it will use a 'not-allowed' icon cursor on mouse hovering, but you can take advantage of this class, eg. you can't dismiss an .above element if the #overlay is locked.
Spinner
On page load, Reveal Basis creates and appends a #spinner element on the DOM.
Spinner is a utility component that can display a loading animation.
Its usage is similar to Overlay's one:
Spinner: Usage
Spinner: access via es6 modules
If you have installed Reveal Basis via NPM, you can access the component by importing the library and creating a new instance of the Spinner:
// script.js
import * as reveal from 'reveal-basis';
let spinner = new reveal.spinner();Spinner: access via rb global variable
As long as you have imported the library with a <script> tag before using it, you have access to its global rb variable:
<!-- index.html -->
<head>
<link rel="stylesheet" href="lib/css/reveal-basis.css">
</head>
<body>
[...]
<script src="lib/js/reveal-basis.min.js"></script>
<script>
let spinner = new rb.spinner();
</script>
</body>Spinner: API
Whether you import the library or you include it via a <script> tag, you have now access to Spinner's component API:
Spinner: show()
The #spinner element will simply appear on screen:
spinner.show();
Spinner: hide()
And, I know you got it, the #spinner element will be hidden with:
spinner.hide();