A utility to create relationships between elements without writing any custom Javascript.
Control the visual state of related Interface Elements using class-based CSS properties.
<button>Button</button><div>Target</div>div {
width: 100px;
height: 100px;
background: black;
}
div.active {
background: yellow;
}
<button st-group="demo">Button</button><div st-group="demo">Target</div><button st-group="demo" st-role="trigger">Button</button><div st-group="demo" st-role="target>Target</div>
<button st-group="demo" st-role="trigger" st-state="active">Button</button>
It is a routine situation to have an Interface that features two or more interface elements that have an effect on each other.
Click this element, and something happens to that element.
Think:
- lightboxes
- dropdown menus
- tooltips
In order to facilitate these common interactions, there are a number of utilities and plugins that can be used, but the interesting thing is that there is a common interaction to all of these situations:
When a user interacts with element a, something happens to element b
State Toggle remedies this situation by providing a single declarative solution that works for all of these scenarios without needing to write any Javascript.
All you need to do is:
- create your HTML as you normally would
- prepare your CSS for your 'before' and 'after' states
- implement some State Toggle attributes
... and let the State Toggle tool look after the rest.
Behind the scenes, State Toggle handles:
- event binding of click events
- management of the state of the toggled element
- management of whether the trigger of the toggled element has been activated
- provision of hooks to control the appearance of triggers that have been activated
- scope control to be able to create multiple instances in an interface, or contain the scope of interaction for whatever reason
- ability to control the default state of a toggle group
| Attribute | Function |
|---|---|
| st-group | Declares elements are in a related group. Elements in the same group must have the same value set to this attribute. |
| st-role | Declares the role that the element plays in the interactive group. Value can be set to either trigger or target. |
| st-state | Declares the state that should be toggled as a class attribute on the target. This can be set to any value valid for a class |
| Attribute | Function |
|---|---|
| st-remove | Declares which class attribute state should be removed from other elements in the interface when an element is triggered. This should be set to any relevant class attribute. |
| st-contain | Declares whether a State Toggle relationship has been scoped or contained (other elements not within the declared scope will not be affected). This can be set to any value (or left with no value). |
| st-ready | Declares whether or not the trigger is 'active' (if the trigger is able to toggle the target). This attribute can be set to the 'trigger' element and set to false if disabled, or true if enabled. |
| st-restrict | This can be applied to a trigger to declare whether the trigger is only able to toggle a target to either the 'off' or 'on' state. Valid values that this attribute can be set to are on or off. |
| st-default | This can be set to the trigger element to declare whether the trigger should be in its activate or inactive state by default. Active triggers have the class attribute set to st-activated. |
Declares elements are in a related group. Elements in the same group must have the same value set to this attribute.
Declares the role that the element plays in the interactive group. Value can be set to either trigger or target.
Declares the state that should be toggled as a class attribute on the target. This can be set to any value valid for a class attribute.
Declares which class attribute state should be removed from other elements in the interface when an element is triggered. This should be set to any relevant class attribute.
Declares whether a State Toggle relationship has been scoped or contained (other elements not within the declared scope will not be affected). This can be set to any value (or left with no value).
Declares whether or not the trigger is 'active' (if the trigger is able to toggle the target). This attribute can be set to the 'trigger' element and set to false if disabled, or true if enabled.
This can be applied to a trigger to declare whether the trigger is only able to toggle a target to either the 'off' or 'on' state. Valid values that this attribute can be set to are on or off.
This can be set to the trigger element to declare whether the trigger should be in its activate or inactive state by default.
There are a few things on the roadmap right now:
- finish the detailed version of these docs
- see if Zach wants to improve the logo
- get rid of the dependency on jQuery (even though we like jQuery)
- add a minified version of the latest code to the repo
- support events other than 'click'
- assess touch events vs click events for touchscreens
- continue testing performance of event binding
- assemble more literature around planning interactive states in interfaces
- more demos
The crew at BNOTIONS put this together. We build a lot of Interfaces, and this tool got us all excited and has saved us boatloads of time.
This tool was born from a perfect storm of sorts:
- we are always looking faster ways to build prototypes
- we got tired of using a bunch of slightly different tools and implementations for things like lightboxes, tooltips, dropdowns, tabs, modals, etc that all fundamentally did the same thing - we were looking for one solution that could handle everything
- our product designers are not shy about getting their hands in the code, and we like to provide them with more ways to express themselves
- we do a lot of Hackathons, and we like the idea of building a tool that could excel in both a Hackathon and Production environment
- AngularJS brought some thoughts about how else we could take advantage of the declarative power of attributes on HTML elements
- we run a lot of workshops and recognize that people who want to build cool, interactive stuff may not need to learn Javascript (gasp)
Big ups to Shawn Connors, Zach Forrester, Peter Organa, Azhar Khan, Andy Fang, Nick Karch, Liane Reale, Solomon Hsu, and Mark Reale for putting this together, kicking the tires, building demos, and providing insights.
If you are using this tool, we would love to hear your thoughts and feedback.
State-Toggle is available under the MIT License.
Please see the LICENSE for full details.