npm package: @ryannerd/toggle-button
Description: Ember CLI toggle-button component add-on
Author: Ryan Jentzsch
Latest version: 0.2.2
Deprecated: Whole thing dumped into the rubish heap because JS designers are idiots with the MutationObserver being a useless piece of crap.

# Toggle-button

This is an Ember add-on for a simple yet powerful toggle button. 
See the screen shot below for what this looks like.

## Installation

* To use this add-on in an Ember project it is recommended you use npm:
	- add `"@ryannerd/toggle-button": "0.2.2"` to your `package.json`
	- adjust the version number of the above to the latest.
	- run `npm install`
	- run `bower install`
	Note: bower install is needed because font awesome is a dependency (for now).

* You can of course `git clone` this repository

## Screen shots
![Alt text](/../screen-shots/screen-shots/toggle-button1.png?raw=true "toggle-button open")

![Alt text](/../screen-shots/screen-shots/toggle-button2.png?raw=true "toggle-button open")

## Using

* Properties
	- targetId (string) [optional] Indicates a unique id for the target element
	- buttonId (string) [optional] Indicates a inique id for the button element
	- collapsedWidth (string) [optional] Specifies the width the target should go to when collapsed. CSS attribute values are used (e.g. "15px") 
	- leftOffset (float) [optional] Tweaks the button position in px. (e.g. a value of -2 will move the button 2px to the left)
	- topOffset (float) [optional] Tweaks the button position in px vertically.
	- toggleState (bool) [optional] Indicates the state of the toggle (true=open, false = collapsed)
	- fontLeft (string) [optional] Currently this is Font Awesome's ("fa fa-chevron-left"), override this if you want a different font.
	- fontRight (string) [optional] Currently this is Font Awesome's ("fa fa-chevron-right"), override this if you want a different font.
	- animationSpeed (integer) [optional] Delay in ms between animation cycles.
	- doToggleAction (bool) [optional] Defaults to true. If set to false when the toggleState changes the target element **will not** be collapsed or expanded. See _Advanced Usage_ below. 
* Actions
	- targetStateChanged(state, target) - This fires when the toggle button is clicked. The state argument indicates the new state. The target is the target Jquery element

* Notes:
	toggle-button uses the `MutationObserver` to react to changes to the target elements in the DOM.
	If other logic changes the state of the target but does not change the attributes of the target you can issue:
		`Ember.$('.toggle-button-target').toggleClass('data-toggle-button');` 
	this will trigger the observer forcing the toggle-button to reposition itself to the right side of the target element.

## Simple Example

```
<!-- example.hbs -->
{{#toggle-button
	buttonId="btn-1"
	targetId="target-1"
	collapsedWidth="15px"
	toggleStateChanged=(action "toggleStateChanged")
}}
    <button>This button is the target</button>
{{/toggle-button}}
```

```
// example.js
actions:
{
   toggleStateChanged(state, target)
   {
      // Do something when the toggle button is clicked.
   }
}
```


## Advanced Usage - If you want to substitute different behavior when the toggle button is clicked on.
```
<!-- advanced.hbs -->
{{#toggle-button
	doToggleAction=false
	toggleStateChanged=(action "toggleButtonClicked")
}}
	<-- Target element goes here (can be a div, table, button, bootstrap panel, etc.) -->
{{/toggle-button}}
```

```
// advanced.js
originalHeight: null,

actions:
{
	toggleButtonClicked(isOpen, target)
	{
		// Save the original height of the target element.
		if (this.get('originalHeight') === null)
		{
			this.set('originalHeight', target.outerHeight());
		}

		let self = this;
		if (isOpen)
		{
			target.animate({height: self.get('originalHeight').toString() + 'px'}, 150, null, function()
			{
				// Trigger observer to know the target element(s) have been changed.
				Ember.$('.toggle-button-target').toggleClass('data-toggle-button');
			});
		}
		else
		{
			target.animate({height: '15%'}, 150, null, function()
			{
				Ember.$('.toggle-button-target').toggleClass('data-toggle-button');
			});
		}
	}
}
```


## Contributing

You are encouraged to fork this repo and make a pull request.
Please use tabs (not spaces) for indentation, and this brace format in your JavaScript code:

```
function function(parms)
{
	// code
}

if (bool)
{
	// code
}
else
{
	// code
}
```

## Known issues
1. If there is more than one toggle button both buttons **MUST** set the `toggleId` and `buttonId` properties to unique values (this is by design).
2. If the web page is zoomed the positions will be wrong (there isn't anything that can be done as **no** browesers expose an API for zoom). 

## Roadmap

1. Toggle is only for right side of target elements. Add support for toggle buttons on left and right.
2. Add support for top and bottom toggle buttons.
3. Optionally interface with sass instead of embedded css.
4. More finite control over the look of the toggle button via sass.
5. Figure out how to get rid of the font awesome dependency and allow the user to pick their own font-set. 
6. Create a new project that is pure Jquery/JavaScript so other frameworks and libraries such as Angular and React can use this component.