2.0 api documentation

Shapeshift Options

All of these are the default options and more in depth information can be found further down the page.

$('.container').shapeshift
    # The Basics
    selector: "*"

    # Features
    enableDrag: true
    enableCrossDrop: true
    enableResize: true
    enableTrash: false

    # Grid Properties
    align: "center"
    colWidth: null
    columns: null
    minColumns: 1
    autoHeight: true
    maxHeight: null
    minHeight: 100
    gutterX: 10
    gutterY: 10
    paddingX: 10
    paddingY: 10

    # Animation
    animated: true
    animateOnInit: false
    animationSpeed: 225
    animationThreshold: 100

    # Drag/Drop Options
    dragClone: false
    deleteClone: true
    dragRate: 100
    dragWhitelist: "*"
    crossDropWhitelist: "*"
    cutoffStart: null
    cutoffEnd: null
    handle: false

    # Customize CSS
    cloneClass: "ss-cloned-child"
    activeClass: "ss-active-child"
    draggedClass: "ss-dragged-child"
    placeholderClass: "ss-placeholder-child"
    originalContainerClass: "ss-original-container"
    currentContainerClass: "ss-current-container"
    previousContainerClass: "ss-previous-container"

The Basics

Option	Description	Type	Acceptable Values	Default
Selector	Use a CSS selector to specify which child elements should be Shapeshifted.	String	Any CSS selector, such as ".amelia" or "#pond"	"*"

Extra Features

Option	Description	Default
enableDrag	Allows for the child items to be dragged in the container and to other containers that have drop enabled. See Drag and Drop options for more customization.	true
enableCrossDrop	Allows for children to be dropped from *other* containers into this one.	true
enableResize	Shapeshift will listen for the window resize event and rearrange the child elements if the parent container has also changed.	true
enableTrash	When an item is dropped into a container that has trash enabled, it will destroy the dropped element.	false

Grid Properties

Option	Description	Acceptable Values	Default
align	Align / justify the grid.	"left", "center", "right"	"center"
colWidth	Manually set the column width. Column width is automatically determined by Shapeshift, however it is required to be set if the container has no initial children to calculate it from.	Any Integer >= 1	1
columns	Force the grid to have a specific number of columns. Setting this to null will automatically determine the maximum columns for the width of the container.	Any Integer >= 1	null
minColumns	This will prevent the grid from ever going below a set number of columns. If using multiwidth then this must be set to the highest colspan child element.	Any Integer >= 1	1
autoHeight	Automatically sets the height of the container according to the height of the contents within it. If set to false, then the "height" option must also be specified.	true, false	true
maxHeight	If "autoHeight" is turned on, maxHeight will never allow the container height to go above this number.	Any Integer >= 1	null
minHeight	If "autoHeight" is turned on, minHeight will never allow the container height to go below this number.	Any Integer >= 1	100
gutterX	The number of pixels horizontally between each column.	Any Integer	10
gutterY	The number of pixels vertically between each element.	Any Integer	10
paddingX	Sets the horizontal padding of the grid between the left and right sides of the container.	Any Integer >= 0	10
paddingY	Sets the vertical padding of the grid between the top and bottom sides of the container.	Any Integer >= 0	10

Animation Settings

Option	Description	Acceptable Values	Default
animated	When children shift around via the resize or drag and drop features, they will animate into place.	true, false	true
animateOnInit	Animates the children into position upon page load.	true, false	false
animationSpeed	The speed at which the children will animate into place.	Any Integer >= 0	225
animationThreshold	If there are too many elements on a page then it can get very laggy during animation. If the number of children exceed this threshold then they will not animate when changing positions.	Any Integer >= 0	100

Drag and Drop Settings

Option	Description	Acceptable Values	Default
dragClone	When an element is dragged it will create a clone instead.	true, false	false
deleteClone	If a cloned item is dropped into its original container, delete the clone that was made.	true, false	true
dragRate	The number of milliseconds that Shapeshift will attempt to find a target pisition for a dragged item.	Any Integer >= 0	100
dragRate	The number of milliseconds that Shapeshift will attempt to find a target pisition for a dragged item.	Any Integer >= 0	100
dragWhitelist	A CSS selector specifying the elements which can be dragged.	Any CSS selector, such as ".river" or "#song"	"*"
crossDropWhitelist	A CSS selector specifying the elements which can be dropped into this container from *other* containers.	Any CSS selector, such as ".martha" or "#jones"	"*"
cutoffStart	Items cannot be dragged to an index position below this number.	Any Integer >= 0	null
cutoffEnd	Items cannot be dragged to an index position past this number.	Any Integer >= 0	null
handle	If specified, restricts dragging from starting unless the mousedown occurs on the specified element(s).	Any CSS selector, such as ".jack" or "#harkness"	false

Customize CSS

Certain elements will have CSS classes attached to them for specific events. Customize those CSS classes if needed.

Option	Affected Element	Description	Default
activeClass	Child Elements	Every active Shapeshift child item will have this class applied to them.	ss-active-child
cloneClass	Cloned Child Element	If the "dragClone" option is used, this is the CSS class applied to the clone that is created.	ss-cloned-child
draggedClass	Dragged Child Element	The class applied to an element while it is being dragged.	ss-dragged-child
placeholderClass	Placeholder Element	When an item is dragged, a placeholder element is created to show the new target position.	ss-placeholder-child
originalContainerClass	Container Element	When an item is dragged, this is the class applied to the container it originated from.	ss-original-container
currentContainerClass	Container Element	When an item is dragged, this is the class applied to the container it currently is in.	ss-current-container
previousContainerClass	Container Element	When an item is dragged between containers, this is the class applied to the container it was previously in.	ss-previous-container

Detecting Changes

Changes to the grid will trigger several different events on the container element and important objects will be returned with it. Here are a list of events that can be listened to, with some examples following.

Event Name	Triggered When	Triggered On	Variables Returned
ss-rearranged	When an item is dropped into the container it originated from.	original container element	selected element
ss-removed	When an item is dropped into a container it didn't originate from.	original container element	selected element
ss-added	When an item is dropped into a container it didn't originate from.	new container element	selected element
ss-trashed	When an item is dropped into a container that has trash enabled and therefore is removed from the DOM.	trash enabled container element	selected element
ss-drop-complete	When an item is dropped into a container, this gets called when it has stopped moving to its new position.	new container element	none
ss-arranged	When an item is dragged around in a container, arranged is triggered every time items are shifted.	current container element	none

Event Listening Examples

When an item has begun being dragged, it will trigger the "ss-event-dragged" on the container element. You can then write out some code to be fired off when that event occurs. The object that was just selected is also passed back to you. For example,

  $containers = $(".ss-container")

  $containers.on "ss-rearranged", (e, selected) ->
    console.log "This container:", $(this)
    console.log "Has rearranged this item:", $(selected)
    console.log "Into this position:", $(selected).index()

  $containers.on "ss-removed", (e, selected) ->
    console.log "This item:", $(selected)
    console.log "Has been removed from this container:", $(this)

  $containers.on "ss-added", (e, selected) ->
    console.log "This item:", $(selected)
    console.log "Has been added to this container:", $(this)

  $containers.on "ss-trashed", (e, selected) ->
    console.log "This item:", $(selected)
    console.log "Has been removed from the DOM"

  $containers.on "ss-drop-complete", (e) ->
    console.log "This container:", $(this)
    console.log "Has finished rearrangement after a drop."

  $containers.on "ss-arranged", (e) ->
    console.log "This container:", $(this)
    console.log "Has just rearranged items but no drop has occurred."

Triggering a Rearrange

If you add, remove, hide, or show elements through your own code then you may need to rearrange the items into their new positions. Triggering "ss-rearrange" on the target container will do so.

  $(".ss-container").trigger("ss-rearrange")

Triggering a Shuffle

A feature added by Cauli, to randomly shuffle all the child elements just use "ss-shuffle".

  $(".ss-container").trigger("ss-shuffle")

Destroying Shapeshift

Simply trigger the event "ss-destroy" on the container.

  $(".ss-container").trigger("ss-destroy")