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.

a graphic showing copying and pasting a SoulMagic component into a layout.

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.

Beaver Builder users can add SoulMagic components to the Soul HTML tab in their Global Settings. Code entered in this tab will be added to the footer of every BB-powered layout.

After you paste the animation component, you connect the component to targets in your layout that you wish to animate.

An example component: ‘fades’

Here’s an example SoulMagic component that we’ll use as a reference in the element definitions below. It’s called ‘fades,’ and it fades content in (and up) when you scroll the page.

<!-- 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).