Flipper

Flipper is a front end web component that flips things in style. Flipper can flip an element in place or flip it open to a modal dialog.

1. Install
2. Usage
   1. Quick start
   2. How to include flipper dependencies
   3. How to set up and configure flipper
   4. How to create a flipper instance
3. Flipper API
   1. Flipper options
   2. Flipper methods and properties
      1. flipper.init( options )
      2. flipper.create( element, options )
         1. element
         2. options
      3. flipper.open( flipperId ) and instance.open()
      4. flipper.close( flipperId ) and instance.close()
      5. flipper.toggle( flipperId ) and instance.toggle()
      6. flipper.all
   3. AngularJS flipper directives
      1. flipper directive
      2. open-flipper directive
      3. close-flipper directive
      4. toggle-flipper directive
4. Questions, comments, concerns

Install

npm install @brikcss/flipper

Usage

Quick start

1. Pick your JS and CSS flavors and include their dependencies.
2. Configure flipper.
3. Create flipper instances.

Note: Flipper JS follows the Universal Module Definition pattern (UMD), which gives you flexibility to load it as an ES2015 module or as a global variable. See how to include flipper for details.

How to include flipper dependencies

You must include dependencies for both JS and CSS flavors of your choice.

CSS flavors:

• SASS (recommended):

   /* main.scss */
   @import 'src/sass/flipper';
  
   /**
    * NOTE: Flipper is created in SASS as a mixin, which allows you to
    * configure the class names when you `@include` the flipper mixin.
    * This gives you a high level of flexibility with how you use flipper.
    */

• Vanilla CSS:

   <!-- index.html -->
   <link rel="stylesheet" type="text/css" href="dist/css/flipper-vanilla.min.css">

JS flavors:

• ES2015 (recommended):

   // Any js script.
   import flipper from 'dist/js/vanilla/flipper-vanilla';
  
   /**
    * NOTE: To use this JS flavor you will need a compiler
    * to convert this to browser supported JS. We use and recommend
    * `webpack` and `babel`.
    */

• Vanilla JS:

   <!-- index.html -->
   <script src="dist/js/vanilla/flipper-vanilla.min.js"></script>

• AngularJS:

   <!-- index.html -->
   <script src="dist/js/angularjs/flipper-angularjs.min.js"></script>

How to set up and configure flipper

• SASS is the only flavor that requires setup...
• ...unless you change the default $base class in SASS; in which case you must also set up your JS flavor to use the same base class.
• Vanilla CSS has no configuration.
• All other setup is optional.

SASS:

/* my-flipper-styles.scss */
@include flipper(
	/* Put your mixin settings here. These are the defaults: */
	$base: flipper, // Base class flipper will use. Make sure to set this up in the JS as well if you change the default.
	$flipFromRight: true, // Whether it will flip from right or left.
	$duration: 0.3s, // Duration of transition.
	$modal: (
		width: 400px, // width of flipper modal.
		height: 400px // height of flipper modal.
	),
	$bg: (front: #ccc, back: #aaa) // background-colors used in flipper.
);

ES2015 or Vanilla JS:

// Call `flipper.init` to update its configuration.
// Configuration can be an object or function that returns an object.
flipper.init(function (instance) {
	// Using a function gives you access to the flipper `instance`,
	// which gives details about the element being created.
	return {
		// This sets the flipper `type` for each element
		// to the value of its data attribute: `flipper-type`.
		type: instance.$element.dataset.flipperType
	};
});

Note: Calling flipper.init() configures defaults for all future flipper instances. You can further configure a flipper instance with the flipper.create() method.

AngularJS:

// Make sure to inject `brikcss.flipper` into your app.
angular.module('myApp', ['brikcss.flipper'])
	// And inject `flipperService` wherever you want to use that.
	.run(function (flipperService) {
		// `flipperService.init` lets you configure defaults
		// for all future flipper instances. You can pass a configuration
		// object or function that returns an object.
		flipperService.init({...});
	});

How to create a flipper instance

Important: The only requirement for your HTML structure is that each flipper element must contain exactly two children elements. The first child will be the flipper's front side and the second child is the back side. There is no other requirement for markup structure.

ES2015 or Vanilla JS:

<!-- HTML: -->
<div class="my-flipper">
	<!-- This will be flipper's front side. -->
	<div>...</div>
	<!-- This will be flipper's back side. -->
	<div>...</div>
</div>

// JS:
flipper.create('.my-flipper', options);

// or:
flipper.create(document.querySelectorAll('.my-flipper'), options);

/**
 * Note: Any options passed to the `flipper.create` method
 * will be merged with any default configuration.
 */

AngularJS:

Note: The AngularJS flavor uses the same UMD version of flipper as other JS flavors, only it is wrapped around a thin AngularJS service. This makes the API exactly the same in all JS flavors. The AngularJS flavor also provides directives for added convenience, allowing you to flexibly interact with flipper in HTML templates or in AngularJS controllers and services.

AngularJS templates:

<!-- This instantiates flipper with all flipper defaults. -->
<div flipper>
	<!-- Flipper's front side. -->
	<div>...</div>
	<!-- Flipper's back side. -->
	<div>...</div>
</div>

<!-- OR -->

<!-- You can also pass the options object directly to flipper
(see flipper's API below for details about options). -->
<div flipper="{...}">...</div>

Flipper API

The flipper API is exactly the same for the vanilla JS plugin as it is for the AngularJS flipper service. The only difference is how flipper is referenced. In vanilla, flipper is referenced by the global flipper variable, whereas in AngularJS it is referenced by flipperService. But the API is the same.

Flipper options

Option	Type	Values (default first) / description
id	string	('') Give a flipper instance an ID if you need to reference the instance from the flipper plugin or service. This is an alternative to caching the object returned by the `flipper.create()` method.
type	string	('inline'|'modal') Sets the type of flipper. An inline flipper flips in place, while a modal flipper flips open as it transitions to a modal dialog.
addDimensions	boolean	(false|true) When true, adds height and width to main flipper $element. This is helpful for flipper modals, to keep main $element in place while flipper modal is open.
openElements	string	('.flipper__front') Binds an open click event to all matching element(s) inside the flipper element.
closeElements	string	('.flipper__close') Binds a close click event to all matching element(s) inside the flipper element.
animationTime	number	(300) In milliseconds. Must match the CSS transition duration.
innerClass	string	('') When set, string will be added to the class attribute of the inner $container (or $modal) DOM element. This allows for more custom styling.
flipperClass	string	('flipper') Sets the base class prefix. You will need this if you changed the base class in the mixin in `flipper.scss`.
classes	object	This object allows you to modify the classes for each flipper DOM element individually. Due to the number of classes, the available classes will not be documented here. Take a look at the plugin itself for more information.

Flipper methods and properties

Flipper attaches the open, close, and toggle methods both to the flipper plugin itself, as well as to each flipper instance. When calling one of these methods on the actual instance, you do not need to pass the flipperId. In the examples below, the word instance is used to refer to the flipper instance returned by flipper.create().

flipper.init( options )

Re-initializes the flipper plugin with custom default settings. This means each new flipper instance will be created with these default settings.

Note: This methods sets global default settings for all flipper instances. These global defaults may still be overridden with the flipper.create(element, options) method, which applies settings to each flipper instance.

// All new flippers will have these as default settings.
flipper.init({
	type: 'modal',
	addDimensions: true
});

The options can also be a function which returns the options object:

// Apply custom default settings to each new flipper instance.
flipper.init(function (instance) {
	return {
		addDimensions: instance.type === 'modal'
	};
});

flipper.create( element, options )

Creates a new flipper instance, which returns the flipper instance.

flipper.create(element, options);

element

HTMLElement or string

If you pass a string, flipper will grab element(s) with document.querySelectoAll(string).

options

If you pass a function, you must return the options as an object. Using a function gives you the advantage of having access to the element being instantiated, as well as other flipper options. For example:

// Even though this instantiates many .my-flipper elements, each is configured individually.
flipper.create('.my-flipper', function (flipper) {
	// The flipper object gives you access to flipper.$element and other flipper settings.
	return {
		id: flipper.$element.getAttribute('flipper-id'),
		type: flipper.$element.getAttribute('flipper-type') || 'inline',
	};
});

flipper.open( flipperId ) and instance.open()

Opens the corresponding flipper.

flipper.close( flipperId ) and instance.close()

Closes the corresponding flipper.

flipper.toggle( flipperId ) and instance.toggle()

Toggles the corresponding flipper.

flipper.all

A map of all flipper instances, organized by their flipperId.

AngularJS flipper directives

The directives that the AngularJS flavor provides should typically be all you need to interact with flipper. However, you may also interact with flipper more programmatically by using flipperService directly.

For documentation on the AngularJS flipperService, refer to the vanilla flipper API, which is exactly the same as the AngularJS flipperService. The only difference is that the angularJS service is called flipperService instead of flipper.

flipper directive

The flipper directive automatically creates an instance of flipper for you, allowing you to optionally pass flipper options via the [flipper] attribute. This may typically be the only directive you need.

<!-- HTML -->
<div flipper></div>

<!-- Pass options to flipper. -->
<div flipper="{...}"></div>

See available options.

open-flipper directive

Use the openElements option to bind an open click event to any elements inside of a flipper element. Use the open-flipper directive when you need to bind an open click event to any elements outside of a flipper element.

<div flipper="{id: 'my-flipper'}">...</div>
...
<button open-flipper="my-flipper" type="button">Open my-flipper</button>

close-flipper directive

Use the closeElements option to bind a close click event to any elements inside of a flipper element. Use the close-flipper directive when you need to bind a close click event to any elements outside of a flipper element.

<div flipper="{id: 'my-flipper'}">...</div>
...
<button close-flipper="my-flipper" type="button">Close my-flipper</button>

toggle-flipper directive

Use the toggle-flipper directive to bind a toggle click event to any DOM elements.

<div flipper="{id: 'my-flipper'}">...</div>
...
<button toggle-flipper="my-flipper" type="button">Toggle my-flipper</button>

Questions, comments, concerns

Pull requests and bugs are more than welcome, as are questions and feedback. Please include as much information as possible with each bug, pull request, and other inquiries. Your help is much appreciated!