Current version: 1.5
Date: April, 05, 2017

Thank you for the purchasing of "Enliven 'em" WordPress plugin! If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. If you like these script please rate it with
. Thanks so much!

After downloading you will find the following folders in the archive:

  • animator
  • documentation
  • for_upload

animator: This folder contains the Animation Editor which can help you to prepare your SVG illustrations for using with the Enliven 'em plugin. Please DO NOT upload this Editor to any server (hosting), it's developed for your local use only.

documentation: As title says this is a documentation.

for_upload: This one is for uploading to your server. The folder contains a ZIP file with the plugin itself.


Note: the versions numbers 1.0 - 1.3 are skipped for synchronizing with jQuery version of Enliven 'em script.

In your WordPress Dashboard navigate to Plugins > Add New. Click Upload on top and browse the enlivenem-for-wp.1.4.zip file from for_upload folder and click Install Now. After installation is complete click on Activate Plugin. Plugin is now installed and activated.

Click Settings

After uploading you need to define plugin's settings.


Restricted to Administrators

If this option is checked, only Administrators will be able to upload SVG files.

If not checked, anyone with Media Library access or "upload_files" capability will be able to upload SVG files (usually they are Administrators, Authors and Editors).


Sanitize SVG Uploading

If this option is checked, any SVG files which are uploaded via Media Library will be checked for correct SVG tags and attributes.

Important: <script> tag, contentScriptType attribute and all SVG event attributes like onactivate, onbegin, onclick, etc. will be removed!

It is strongly recommended do not disable this option unless you are absolutely sure about your uploading SVG code. Especially if you allow to use your Media library uploading for Authors and Editors.


Disable SVG thumbnails

Sometimes, in rare cases, there are a conflict with third party plugins, and as a result there is a broken grid view of thumbnails in Media Library. To prevent this you may disable thumbnails for your SVG files by checking this option.


Additional CSS Selectors

In general, all <img> and <svg> elements with class enlivenem can be animated if you add special data attributes and class for their SVG code (see below).

You can define the additional CSS selectors for elements which you want to animate and you don't want or can't add class enlivenem to them (for example in your theme files).

For example you have a <div> with class logo within <img> tag with SVG file as source.

<div class="logo">
  <a href="your_link_is_here">
    <img src="my_cool_logo.svg">
  </a>
</div>
And you prepared your my_cool_logo.svg for animation. In that case you can add the following code: .logo img into the field of this option.

Also you may combine several CSS selectors for different elements with comma separation. For example:
.logo img, #some-id, .some-class, div.with_another_class > img

Please keep in mind that due to security reasons only these characters are allowed: A-Z a-z 0-9 _ - . >  (space) # ,

If you want to remove previously added selectors, simply leave the field blank.


After making any changes please click Save Changes button. Now your site is ready to use Enliven 'em SVG animation engine. How to prepare your SVG code for Enliven' em script is described below.


Use in post (pages)

1) Upload your ready to use SVG file(s) via Media Library.

2) Insert your uploaded file(s) into your post (page) as any other image.

3) Click a "pencil" icon to edit this image.

4) Add class enlivenem into the Image CSS Class field and click Update.

Please keep in mind that Size setting from the screen above will NOT take effect! Both width and height attributes must be set within <svg> tag itself in your SVG file.


Use for theme images

If you can't add class enlivenem (for ex. in theme files or for featured images) simply define additional CSS selectors on a Settings page of this plugin.

You can find out what selectors to use by inspecting elements in developer mode in your browser (F12 key in Google Chrome for example).


Shortcode for wrapper

Sometimes you may need to create a wrapper for your SVG image. In that case you can use the following shortcode:

[enlivenem_wrapper class="some_class" style="width:70%;" source="http://path/to/my/cool-image.svg"]
As the result you will get this code is being inserted in your page (post) HTML:
<div class="some-class" style="width:70%;">
  <img class="enlivenem" src="http://path/to/my/cool-image.svg">
</div>

Of course you can use the above HTML code in any page, post, widget, etc. without using the shortcode.


Advanced usage via JavaScript (for Developers)

You can use any CSS selectors for your <img> tags to start Enliven' em script programmatic.

In that case use my jQuery method: jQuery( 'your_css_selector' ).enlivenEm( callback );

The callback function (if passed) will be invoked when all svg data is ready to start the animation.

Also if you want to invoke 'click' event programmatic on your SVG illustration you can use special method jQuery( 'your_css_selector' ).svgClick(); because jQuery method .trigger('click') doesn't work with SVG.


Bonus

The script will convert any SVG image from <img> tag with class enlivenem to its in-line form automatically.

So if you even don't use any animation you can convert SVG to in-line form and control CSS styles of its shapes (path, circles, polygons, etc.) via external style sheets.


Before upload to a server an SVG image MUST be prepared.

The main: All the animation data and global options are included in SVG code itself via class name and HTML5 data attributes. The script finds all these data in your SVG code (file) and produces animations and applies options.

You can add these data and options by hand writing in a code or, the better way, use the Animation Editor for doing that in a WYSIWYG mode. Look for the Editor in the animator folder.

You can animate the following SVG tags only:
circle, ellipse, g, image, line, path, polygon, polyline, rect, text and use.

Using animations on any other tag may cause an unexpected results.

Also please keep in mind that the drawLines effect will not work for image, text and use tags.


Here is an example of SVG code (for "Infinity" icon), which is ready to use with my script:

<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="100" height="100" viewBox="0 0 100 100" data-global-elvn="enableViewport, enableClick, full, startInvisible, responsive, 0, notLoop, 500">
  <circle id="loop-background" class="elvn-layer" data-elvn="expandY, in, 0, 800, bounce" fill="#E74C3C" cx="50" cy="50" r="50"></circle>
  <path id="loop-sign" class="elvn-layer" data-elvn="drawLines, 800, 800, #065462, 6, notRandom" fill="none" stroke="#F0C419" stroke-width="8" stroke-linecap="square" stroke-miterlimit="10" d="M12.5,50.5c0,10,7,17,17,17c17,0,26-34,43-34c10,0,18,7,18,17s-8,17-18,17c-17,0-26-34-43-34C19.5,33.5,12.5,40.5,12.5,50.5z"></path>
  <path id="loop-shade" class="elvn-layer" data-elvn="fade, in, 1400, 200, linear" opacity="0.15" d="M45.938,50.5l5.046,6.516c0,0-2.141,2.797-3.5,4.25c0,0-3.547-3.609-5.477-5.88C43.316,53.983,45.938,50.5,45.938,50.5z"></path>
</svg>

Important: You must have width, height and/or viewBox attributes are defined in an svg tag. Also the script work only with pixel units! You can't use em, %, etc., only px. Think of your SVG illustration like any other image which has its own width and height. If you want to make your SVG responsive, simply define responsive option in data-global-elvn attribute.

If you want to use not px but em, %, etc., you can wrap your Enliven 'em image with additional <div> (with help of [enlivenem_wrapper] shortcode for example) or <span> and apply to them styles in em, %, etc..


Global (for this file) SVG option

This option are added to svg tag itself to data-global-elvn attribute.

The order of options are very important! Please do not mix them.

Example: data-global-elvn="enableViewport, enableClick, full, startInvisible, responsive, 0, notLoop, 500"

option value description
1 enableViewport
disableViewport
If value is "disableViewport", animations will NOT start when SVG appears in users browser viewport.
2 enableClick
disableClick
If value is "enableClick", animations can be repeated when a user clicks SVG.
3 none
oneFourth
oneThird
oneHalf
twoThird
full
Take effect when "enableViewport". It means that animation starts only if SVG is in a viewport at least the given value, calculated from SVG height.
4 startInvisible
startVisible
if "startInvisible" the SVG becomes invisible when page is loaded. Suitable for "in" animations.
5 responsive
notResponsive
If "responsive", SVG will be wrapped with the special container and responsive styles will be applied from enlivenem.css file. Also width and height attributes will be removed and viewBox one will be added.
6 integer from 0 The global delay in milliseconds before animation starts
7 loop
notLoop
If "loop", SVG animation will be repeated infinity, repetition on "click" will be disabled and not take affect.
8 integer from 500 The time of pause in milliseconds between every animations repetitions. Strongly recommended to set this value no less that 1000 - 2000 ms.

Animation options for each SVG primitive

As I said earlier you can animate the following tags:
circle, ellipse, g, image, line, path, polygon, polyline, rect, text and use.

You can do this by adding class elvn-layer and data-elvn attribute to those tags. For custom animation you need to add one more attribute: data-elvncustom. For morph animation you need to add one more attribute: data-elvnmorph.

And again: the order of options are very important! Please do not mix them.


There are six (6) different types of animation. Each type has its own options and the order of these options in data-elvn attribute.

"Various" animations

Example: class="elvn-layer" data-elvn="fadeLongR, in, 700, 1000, easein"

option value description
1 Name of effect (one of the following):

expandB, expandL, expandR,
expandT, expandX, expandY,
fade, fadeLongB, fadeLongBL,
fadeLongBR, fadeLongL, fadeLongR,
fadeLongT, fadeLongTL, fadeLongTR,
fadeShortB, fadeShortBL, fadeShortBR,
fadeShortL, fadeShortR, fadeShortT,
fadeShortTL, fadeShortTR, flipX, flipY,
flyC, flyRotateC, flyScaleC,
rubberX, rubberY,
scaleB, scaleBL, scaleBR, scaleC, scaleL,
scaleR, scaleT, scaleTL, scaleTR, stamp,
wheelB, wheelL, wheelR, wheelT, wheelC
The better way is to play with these values in Animation Editor.
Nevertheless, the capital letters mean:
TL - top-left,
T - top,
TR - top-right,
R - right,
BR - bottom-right,
B - bottom,
BL - bottom-left,
L - left,
C - center,
X - horizontal,
Y - vertical
2 in
out
If "in", the animation will go to neutral position. If "out", the animation will go from neutral position.
3 integer from 0 The delay in milliseconds before an animation starts.
4 integer from 0 The duration in milliseconds of an animation.
5 backin
backout
bounce
easein
easeinout
easeout
elastic
linear
The name of easing function. Default is "linear".

"Masks" animations

Example: class="elvn-layer" data-elvn="maskClockOne, in, 1000, 1500, easeinout"

option value description
1 Name of mask effect (one of the following):

maskCircle, maskClockOne, maskClockTwo,
maskCross, maskCrossRotate, maskEllipse,
maskExpand, maskGradB, maskGradL, maskGradR,
maskGradT, maskLouversX, maskLouversY,
maskPanX, maskPanY, maskPlus, maskPlusRotate,
maskRect, maskRhomb, maskSlideB, maskSlideBL,
maskSlideBR, maskSlideL, maskSlideR,
maskSlideT, maskSlideTR, maskSlideTL,
maskStackX, maskStackY, maskTighten
The better way is to play with these values in Animation Editor.
Nevertheless, the capital letters mean:
TL - top-left,
T - top,
TR - top-right,
R - right,
BR - bottom-right,
B - bottom,
BL - bottom-left,
L - left,
X - horizontal,
Y - vertical
2 in
out
If "in", the animation will go to neutral position. If "out", the animation will go from neutral position.
3 integer from 0 The delay in milliseconds before an animation starts.
4 integer from 0 The duration in milliseconds of an animation.
5 backin
backout
bounce
easein
easeinout
easeout
elastic
linear
The name of easing function. Default is "linear".

"Gaussian Blur" animation

Example: class="elvn-layer" data-elvn="gaussBlur, in, 0, 1000, 16"

option value description
1 gaussBlur Name must be exactly gaussBlur
2 in
out
If "in", the animation will go to neutral position. If "out", the animation will go from neutral position.
3 integer from 0 The delay in milliseconds before an animation starts.
4 integer from 0 The duration in milliseconds of an animation.
5 Integer from 0 The value of standard deviation for Gaussian blur SVG filter.

"Line Drawing" animation

Example: class="elvn-layer" data-elvn="drawLines, 0, 2000, red, 3, random"

option value description
1 drawLines Name must be exactly drawLines
2 in
out
If "in", the animation will go to neutral position. If "out", the animation will go from neutral position.
3 integer from 0 The delay in milliseconds before an animation starts.
4 integer from 0 The duration in milliseconds of an animation.
5 HEX, RGB or HTML name The color value for drawing line.
6 random
notRandom
Take affect when drawLines is applied for <g> tag. All shapes (primitives) in this group will be drawn with random duration within the limit of duration option above if this value is set to "random".

"Custom" animation

Example: data-elvn="custom, in, 0, 1000, 100, easeinout" data-elvncustom="t100,0s2,2r-270"

Please pay attention that "custom" animation must have one more data-elvncustom attribute.

option value description
1 custom The name must be exactly custom
2 in
out
If "in", the animation will go to neutral position. If "out", the animation will go from neutral position.
3 integer from 0 The delay in milliseconds before an animation starts.
4 integer from 0 The duration in milliseconds of an animation.
5 integer from 0 to 100 The percent based opacity value.
6 backin
backout
bounce
easein
easeinout
easeout
elastic
linear
The name of easing function. Default is "linear".

Option for data-elvncustom attribute:

value description
transform string Here you can define your own transformation string. Here is an explanation by Dmitry Baranovsky, the author of Snap.svg:

Transform string can be for example: "t100,100r30,100,100s2,2,100,100r45s1.5"

Each letter is a command. There are four commands: t is for translate, r is for rotate, s is for scale and m is for matrix.

There are also alternative "absolute" translation, rotation and scale: T, R and S. They will not take previous transformation into account. For example, T100,0 will always move element 100 px horizontally, while t100,0 could move it vertically if there is r90 before. Just compare results of r90t100,0 and r90T100,0.

So, the example line above could be read like "translate by 100, 100; rotate 30° around 100, 100; scale twice around 100, 100; rotate 45° around center; scale 1.5 times relative to center". As you can see rotate and scale commands have origin coordinates as optional parameters, the default is the center point of the element. Matrix accepts six parameters.

"Morph" animation

Important: "morph" effect can be applied for path elements only!

Example: class="elvn-layer" data-elvn="morph, in, 0, 1000, easeinout" data-elvnmorph="M171.207611,110.342499c39.094391,-97.125
192.262817,0 0,124.875c-192.263035,-124.875 -39.094742,-222 0,-124.875z"

Please pay attention that "morph" animation must have one more data-elvnmorph attribute.

option value description
1 morph The name must be exactly morph
2 in
out
If "in", the animation will go to neutral (initial) path's shape form. If "out", the animation will go from neutral (initial) path's shape form.
3 integer from 0 The delay in milliseconds before an animation starts.
4 integer from 0 The duration in milliseconds of an animation.
6 backin
backout
bounce
easein
easeinout
easeout
elastic
linear
The name of easing function. Default is "linear".

Option for data-elvnmorph attribute:

value description
The string of path's shape. Equivalent of d attribute of path tag

Let's look at the following piece of SVG code:

<path 
    id="rabbit"
    fill="#ecf0f1"
    stroke="#95a5a6"
    stroke-width="1.5"
    d="m181.40759,251.27267c-7.9451,-3.58209 2.42215,-10.74704 6.34988,-13.91507c2.64214,-2.4407 -15.1562,0.34122 -7.64163,-8.13013c8.24553,-6.92123 5.12946,-18.63034
... code here is cut for this documentation example ...
-8.97668,18.74234 -19.42767,21.05322c-4.69867,1.30383 -9.52798,2.34979 -14.33823,0.93234l0,0l0,-0.00002z"
    class="elvn-layer"
    data-elvn="morph, out, 500, 1600, linear"
    data-elvnmorph="m374.13251,58.42095c-8.47952,-13.53757 -26.15018,-11.09409 -39.30161,-14.16914c-10.92059,-4.52627 -27.64563,-8.86669 -35.41534,4.08142c-10.37021,12.08472
... code here is cut for this documentation example ...
19312,-21.79065 23.9285,-20.94555c6.86792,-0.95702 13.76114,-1.75237 20.5882,-2.99516l0,0l0,-0.00003z">
</path>

Here you see the path tag. The value of the d attribute of this path represents a "rabbit" shape.

On the other side the value of data-elvnmorph contains data for "crow" shape.

So my script changes the d value from "rabbit" to "crow" if the direction of animation is "out". And it also can change from "crow" to "rabbit" when the direction is "in".

On the other words you need to prepare 2 shapes path's data in your vector graphic software, so they can be morphed from one into another.

"Morph" effect doesn't control an opacity! So the path element with this effect will be visible when page is loaded. If you need to control the opacity of your "morphed" path(s) please wrap it(them) in an additional g tag and apply the "fade" effect to that added group. Also you can try for that group the "custom" effect with desired opacity value and with neutral transform string in Snapsvg format - "t0,0".

Basically, after any changes of animation options you need to re-upload your SVG file(s). To edit them on your server without leaving WP Dashboard you can use a free WP plugin - WPide. This WordPress code editor allows to edit any files on a server including SVG ones from your wp-content/uploads/ folder.
When you or your freelancer prepare(s) a vector illustration, try to give meaningful names to elements and groups which you want further animate. It will help you to find those elements in the Editor's tree with easy.
After taken a result SVG code from Adobe Illustrator, Inkscape or Sketch, you can optimize this code via this SVG editor by Peter Collingridge especially if you use Inkscape, because it adds too many its own tags which are not necessary for web. But please be careful with optimization options.
If you want to make several animations on one basic element, wrap it with additional g tags as many as you need animation steps and apply different animation options for these groups.
Try to avoid to apply animations for elements in defs. One exception is elements for use tags. But be carefully with use elements, sometimes they give unexpected results.
Please remember that "morph" effect works only with path elements.
Please be careful with global loop option. Users don't like inappropriate annoying effects.

The Animation Editor, which you can find in the animator folder can help you to prepare your SVG code for Enliven 'em script with easy.

It's impossible to describe all working aspects with Editor in this documentation file, so here is a screen-shot with some interface description.

Explanations:

  1. Source tab. Here you paste your initial SVG code.
  2. Editor tab. Main tab with the Editor itself.
  3. Result tab. From there you can copy the resulting code with embedded animation options and paste it into your HTML code or a new SVG file.
  4. Global options settings.
  5. Animation options
  6. Buttons (from left to right): "Add animation", "Copy animation", "Paste animation", "Remove animation", "Play animation for current element", "Play all animations"
  7. The tree of your SVG document
  8. The work area
  9. Status bar
  10. Applied animation for selected element

Video Tutorial

For details of how to work in the Editor please watch the video tutorial, which you can find on my demo site and/or on my Youtube page.


Internet Explorer 9 restriction

gaussBlur effect doesn't work in IE9 because that browser doesn't support SVG filters at all (Works fine in IE10 and IE11). Fall-back to fade effect is provided for IE9.

You will be informed in your WordPress dashboard when any update will be available.

To update the plugin, login to CodeCanyon, head over to your Downloads section and re-download the plugin like you did when you bought it.

Deactivate and delete the current version of Enliven 'em! plugin. Please do not worry, all your settings stay in your database.

Install and activate the new version of the plugin as usual and click Save Changes button on a plugin's setting page.


Once again, thank you so much for purchasing this item. As I said at the beginning, I'd be glad to help you if you have any questions relating to this package. No guarantees, but I'll do my best to assist. If you have a more general question relating to Enliven 'em plugin, you might contact me via my user page contact form here. And again if you like these app please rate it with
Thanks You!

Best regards,
Dee