“Enliven 'Em! for WordPress” Documentation

Overview of the pack

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

• animator
• documentation
• examples
• 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.

examples: This folder contains some ready to use animated SVG files. Look at them as a starting point.

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

Setup

Update from v.1.5 and earlier

If you make an update from version 1.5 or earlier please deactivate and completely delete currently installed version of the plugin and follow the install steps mentioned below for new version 1.9.

Update from v.1.6 and up

If you activate your Envato purchase code inside the plugin, then automatic updates will be available on Plugins page of your WordPress dashboard.

New install (v.1.9)

In your WordPress Dashboard navigate to Plugins > Add New. Click Upload on top and browse for the enlivenem-1.9.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

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 to or can't add the class enlivenem to them (for example in your theme files).

For example you have a <div> with class logo with <img> tag inside it with SVG file as source:

<div class="logo">
  <a href="may_be_some_link_here">
    <img src="my_cool_logo.svg">
  </a>
</div>

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.

Delete All Options on Uninstall

If checked, completely remove all the Enliven 'Em data from the disk and the database when using the Delete link on the main plugins page.

Import and Export

This tab allows you easily import and export plugin settings.

Activate product

By activating Enliven 'Em! license you will get access to direct plugin updates.

How to use (integration)

1) Via the Classic editor in posts/pages

• Upload your ready to use SVG file(s) via Media Library.
• Insert your uploaded file(s) into your post (page) as any other image.
• Click a pencil icon to edit this image.
  
• 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.

2) Via the Gutenberg block editor in posts/pages

• Go to the General Settings page of Enliven 'em plugin.
• Add a custom CSS selector for a container where your animated SVGs will be placed, say enlivenem-container
  In that case your CSS selector should be .enlivenem-container img:
  
  You should do such setting only once.
• Upload your ready to use SVG file(s) via Media Library.
• Insert your uploaded SVG into your post (page) as image block:
  
• Add class enlivenem-container into the Additional CSS Class field at the right Image block settings panel:
  
  Important! Please do not use any alignments for the image if you have set responsive option inside data-global-elvn attribute of your SVG (see the details below in the "Make SVG enlivened" section).

3) With Elementor (https://elementor.com) plugin

• Go to the General Settings page of Enliven 'em plugin.
• Add a custom CSS selector for a container where your animated SVGs will be placed, say enlivenem-container
  In that case your CSS selector should be .enlivenem-container img:
  
  You should do such setting only once.
• Upload your ready to use SVG file(s) via Media Library.
• Add your animated SVG via Image widget as any other regular images like png, jpg, etc.:
  
• Click the Advanced tab of the Edit Image widget:
  
• Add class enlivenem-container into the CSS Classes field at the left sidebar:
  
• Click Update button

4) with WPBakery Page Builder (formally known as Visual Composer) plugin

• Upload your ready to use SVG file(s) via Media Library.
• The best way for Enliven 'Em images inside WPBakery Page Builder is to use them via standard text block:
  
  Click a pencil icon to edit this image.
• Add class enlivenem into the Image CSS Class field and click Update
  
  
• After that click Save changes button of WPBakery text block and update your post/page.

5) With Revolution Slider plugin

IMPORTANT: The plugin doesn't have and will not have a purpose to work inside any sliders. So, Enliven 'em plugin doesn't compatible with Revolution Slider and there is no guaranties that it will work inside the slider. Furthermore, Enliven 'em animations may work in the very first slide only! It will not work in second, third, etc. slides.

• Go to the General Settings page of Enliven 'em plugin.
• Add a custom CSS selector for a container where your animated SVGs will be placed, say enlivenem-container
  In that case your CSS selector should be .enlivenem-container img:
  
  You should do such setting only once.
• Upload your ready to use SVG file(s) via Media Library.

If you set notResponsive global option for your SVG

• Add your animated SVG via Add Layer > Image:
  
• Select just added image and click Attributes tab
• Add class enlivenem-container into the Classes field:
  
• Click Save slide button

If you set responsive global option for your SVG

• Add your animated SVG via Add Layer > Image:
  
• On Style tab set cover mode Full Width:
  
• Click Save slide button
• Select SVG image and click Attributes tab
• Add class enlivenem-container into the Classes field:
  
• Click Save slide button

IMPORTANT: There is no way Enliven 'em plugin works correctly inside Revo slider if cover mode is set to values other then Full Width for responsive animated SVG. Please pay attention on this feature while creating your SVG in a part of its width.

NOTE: As it was said above: "Formally, Enliven 'em plugin doesn't compatible with Revolution Slider". So the support does not cover any issues with this part of functionality.

6) Via wrapper shortcode

You can use your animated SVG via special shortcode:

[enlivenem_wrapper source="http://your_site.com/path/to/your-animated-image.svg"]

<div>
  <img class="enlivenem" src="http://your_site.com/path/to/your-animated-image.svg">
</div>

Also the shortcode can take two options: class and style, if needed. The class one can hold additional class name for wrapper div and the style one can contains additional styles for that wrapper.

[enlivenem_wrapper class="some_custom_class" style="width:42%;" source="http://your_site.com/path/to/your-animated-image.svg"]

<div class="some_custom_class" style="width:42%;">
  <img class="enlivenem" src="http://your_site.com/path/to/your-animated-image.svg">
</div>

7) Via pure HTML code

Of course you can use a pure HTML code in any page, post, widget, etc without using the shortcode or any WYSIWYG options. Please do not forget to add enlivenem class to your img tag:

<img class="enlivenem" src="http://your_site.com/path/to/your-animated-image.svg">

8) Via pure SVG code

As you know, SVG code is XML markup language. So you can simply use it on your site as a part of your HTML (PHP) directly instead of using the img tag. The other benefit of this mode is that it reduces a page's loading time, and HTTP requests.

Especially it's easy to add direct SVG code inside Custom HTML block of Gutenberg editor. Here is the code of a small animated icon. Please do not forget to add enlivenem class to your svg tag:

<svg class="enlivenem" 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 class="elvn-layer" data-elvn="expandY, in, 0, 800, bounce" fill="#E74C3C" cx="50" cy="50" r="50"></circle>
  <path 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 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>

Here is how it looks in the Gutenberg editor:

9) Use for theme's images

If you can't add class enlivenem and use a shortcode (for example in PHP theme files) simply define Additional CSS selectors on a General 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 or FireFox).

In the example above, a hypothetical theme contains a div with class logo which contains img tag with animated company's logotype. So in that case, the additional CSS selector should be .logo img

10) 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 the custom 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 animated SVG, you can use special method jQuery( 'your_css_selector' ).svgClick(); because the standard jQuery .trigger('click') one doesn't work with SVG.

11) 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 your SVG into in-line (SVG code will be embedded to a page's one) form and control CSS styles of that SVG shapes (path, circles, polygons, etc.) via external style sheets.

Make SVG enlivened

The main: Before upload to a server, a SVG image MUST be prepared. 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 (of Infinity icon), which is ready to use with my script. Please try to copy-paste it into the Animation editor:

<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 for svg tag. Also the script work only with pixel units! You can't use em, %, etc, only px. Think about 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 other units then px like em, %, etc., you can wrap your Enliven 'Em image with additional <div> (with a 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 in 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"

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. For alongPath animation you need to add one more attribute: data-elvnalongpath.

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

There are seven (7) 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"

"Masks" animations

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

"Gaussian Blur" animation

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

"Line Drawing" animation

Example: class="elvn-layer" data-elvn="drawLines, 0, 2000, red, 3, 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 for data-elvncustom attribute:

"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 for data-elvnmorph attribute:

<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>

"Along a Path" animation (from v1.6)

Example: class="elvn-layer" data-elvn="alongPath, end, 0, 2000, -90, easeinout" data-elvnalongpath="M181 127h1c2.6 ... 125v-10"

Please pay attention that "along a path" animation must have one more data-elvnalongpath attribute.

Value for data-elvnalongpath attribute:

Tips (please pay attention on them)

1. When you or your freelancer prepare(s) a vector illustration, try to give meaningful names to elements and groups which you want further to animate. It will help you to find those elements in the Editor's tree with easy.
2. If you use Adobe Illustrator for creation, please try to avoid using classes like ".st0, .st1, .st2, etc." in your ready SVG code. It might cause a conflict when you use more then one animated SVG on the same page.
   It will be better to use "Presentation attributes" option.
   To do that, save your SVG in Adobe Illustrator according the following: In "SVG Options" dialog box click "More Options". Look at "Advanced Options" section > CSS Properties. Set it to "Presentation Attributes". As a result all your styles will be set as attributes for every element like:
   <rect fill="..." stroke="..." stroke-width="..." opacity="..."></rect>
3. 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.
4. 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 those groups.
5. Try to avoid to apply animations for elements in defs. One exception is use tag. But be carefully with use elements, sometimes they give unexpected results.
6. Please remember that "morph" effect works only with path elements.
7. Please be careful with global "loop" option. Users don't like inappropriate annoying effects.

Enliven 'Em Animation Editor

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

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.

Updates

From version 1.6 there is an automatic updates mechanism. Please activate your copy of the plugin by using your Envato purchase code on the plugin setting page inside your WordPress dashboard.

Special thanks to

• To Dmitry Baranovskiy, the author of Snap.svg library
• Ryan Van Etten, the author of Verge script