SoulMagic Documentation
Installation
Once you purchase SoulMagic, download the zip file that was emailed to you (or grab it from your Account page), upload that zip to a WordPress site, and activate the plugin.
After you’ve activated SoulMagic, copy the SoulMagic license key from your purchase receipt and enter it in DashBoard › Soul Plugins in the SoulMagic tab.
Activating your license key ensures that your plugin will be kept up to date with bug fixes and new features.
First Steps
Once you’ve installed SoulMagic, you’re ready to start animating.
The easiest way to animate an element (or group of elements) with SoulMagic is to copy an animation component – a snippet of HTML code that’s like a ‘recipe’ – and paste it into the same WordPress layout that contains your animation targets.
You can place the component wherever you can place HTML: in a module/block, in your theme, or via a plugin like Simple Custom CSS/JS.
After you paste the animation component, you connect the component to targets in your layout that you wish to animate.
An example component: ‘fades’
<!-- create component, define users -->
<soulmagic id="fades" users=".fades-row">
<!-- set initial styles -->
<set targets=".fades-target">
<y>60</y>
<opacity>0</opacity>
</set>
<!-- define the event -->
<event type="scroll"></event>
<!-- execute the animation timeline -->
<timeline>
<to targets=".fades-target">
<y>0</y>
<opacity>1</opacity>
<stagger>.1</stagger>
</to>
</timeline>
</soulmagic>
Elements
soulmagic
The <soulmagic>
element represents the entire animation/behavior defined within it. It’s the outermost element in a SoulMagic component.
<soulmagic id="fades" users=".fades-row">
<!-- sets, event, timelines go in here -->
</soulmagic>
The <soulmagic>
element has two attributes:
- the id, which helps you label the component and keeps its code separate from other components, and
- the users, which is a set of elements, specified by a class/ID/tag selector, to which the component will be connected (and to which its animation targets will be scoped).
Another way to think about SoulMagic users is: these are the elements that are using this particular component. With our example scroll animation, the users are any element with the class of fades-row
.
By assigning users in the <soulmagic>
element, you can activate/deactivate an animation component that affects multiple targets from one place—instead of painstakingly configuring animations on every target in your site.
set
The <set>
element is used to apply styles to animation targets before an animation takes place. For example, if you want to fade targets in, you’d need to <set>
the targets to be ‘faded out’ initially.
<set targets=".fades-target">
<y>60</y>
<opacity>0</opacity>
</set>
<set>
elements have two attributes:
- targets, which accepts one or more selectors (ID, class, tag, etc), and
- scope, which defaults to the users of this component, but can be set to any element in your layout.
Targets are elements that you’re setting styles on (in this case, elements with the class of fades-target
).
Scope defaults to .fades-row
, so you’re setting styles on all .fades-target
elements within .fades-row
elements.
Setting style properties
Within a <set>
element, you can list CSS properties and their values as elements like <opacity>0</opacity>
, where the property is opacity and the value is 0. These property tags need to be closed, as shown.
<set targets=".fades-target">
<y>60</y>
<opacity>0</opacity>
</set>
The <y>60</y>
element in this example is a shorthand for transform: translateY(60px)
, which will shift the targets down 60px.
event
The <event> element tells the component when it should fire an animation timeline: when the page is scrolled, or when a specific element is clicked/hovered.
timeline
SoulMagic animations are structured as timelines that contain animation steps. Timelines describe how animations will take place.
Components using <event type="scroll">
have one timeline. Components using <event type="click">
or <event type="hover">
have two timelines: one for the 'in' animation (like opening a dropdown/modal or moving your cursor over an element), and one for the 'out' animation (closing a dropdown/modal or moving your cursor off an element).