26 August 2018

Knowledge Base

Installation

Follow these instruction to install plugin on your WordPress site:

  1. Download the plugin, find the install.zip file.
  2. Go to WordPress admin area and visit Plugins » Add New page.
  3. Click on the Upload Plugin button on top of the page, choose install.zip file and confirm.
  4. After installation enable plugin, reactions are active by default for posts and comments.

Uninstall

To remove the plugin from your site follow these steps:

  1. Go to WordPress admin area and visit Plugins page.
  2. On the plugin details row click Deactivate link, if the [Delete all data when disable plugin] flag is set a confirm window will appear, click “Confirm”.
  3. On the same row click the red link to delete plugin.

Remove all data

This plugin removes all data on deletion, however there is a way to delete all data without deleting completely the plugin:

  1. Go to WordPress admin area and visit Reactions » General Settings page.
  2. Enable check on Delete all data when disable plugin, should be the last checkbox on bottom. On multisite installation this option is available only on main site settings.
  3. Visit Plugins page.
  4. On the plugin details row click Deactivate link, a confirm window will appear, click “Confirm”.
  5. Now all plugin data is deleted, enable the plugin again to start from scratch with defaults only.

Basic usage

By default this plugin on activation creates six different reactions and enables voting for posts and comments, with no user restrictions.

Once enabled users may instantly start voting your content, and two different widget appears on dashboard showing statistics about Total Reactions and Reactions by content type.

Those are most common settings for many sites, so you may leave default values. If you need some customization continue reading next paragraph.


Customization

This plugin offers some out of the box customization settings, the most important is the first screen in which you may edit icons appearance and properties. To access those settings navigate to Reactions » Reactions Manager page.


Change sort order

A simple drag’n drop interface lets you sort reactions as you wish:

Drag’n Drop to sort Reactions.

Change reaction icon

There are 250 icons included in plugin package, all icons are provided for free – with attribution – by Flaticon.com.

To change image simply click on icon and choose one of the hundreds of provided vector artworks.

Choose among 250 vector icons.

Use your own images [PRO]

If you want you may use your own images from default WordPress media uploader:

Use your own images.

Bitmap images such as JPEG, PNG and GIF cannot be colorized using the color picker widget.

Vector images should be monochromatic to work properly with the color picker widget.

DaReactions does not enable SVG upload through WordPress’ Media Uploader, you should use a third party plugin if you want to use this feature.


Change icon color

You may change the color of provided SVG icons choosing one of 16 millions RGB possible values.

On Reaction Manager page click the Select Color button, use graphic selector or digit a valid HEX color value.

Customize color with simple picker.

The same color you choose for icons will be used also for Charts in widgets. If you want to use different colors for Reactions and Charts please set your preference in General Settings Page.


Rename reaction

Every reaction have a name that is used as label on frontend. Changing reactions label is as simple as typing the new label in a text field.


Create new reaction

Under the reaction list there is a «Add new» button, every click on this button creates a new reaction with a random icon and a random color.

To create your own reactions click on «Add new» button then set icon, color and label.

Add new Reactions.

Delete reaction

To delete a reaction click on the trash icon on the right, then confirm the action.


Reaction settings

The general settings page lets you customize the way in which reactions should work in your site. To access those settings navigate to Reactions » General settings page.

Options are grouped in several tabs


Enable or disable reactions for content

The first field set lets you enable reactions for all registered post types and comment. On a default WordPress installation there are only Post, Page and Media and their comments.


Enable or disable reactions for comments

If a post type have comments enabled will be possible to enable comments for them.


Enable or disable reactions for custom post types [PRO]

On more advanced installations, such as WooCommerce shop or a site with many Custom Post Types will be possible enable reactions to these content too.


Enable reactions for single page view and for archives

Reaction buttons may appear on single page and on archive view, use these checkbox to set your preferences.


Choose different colors for Charts

If you choose similar colors for Reactions you may want to use different colors for Charts, this setting lets you choose between three different options:

  • Use the same colors as Reactions: This is the default value and renders the Charts with the same colors you chose in Reactions Settings Page;
  • Use random generated colors: Generates RGB values from reactions labels, so identical labels will have identical colors;
  • Use default rainbow palette: Uses a default palette with 20 different tints, use this if the previous options does not work for you.

Enable user role restrictions [PRO]

Reactions are visible to all site visitor but you may restrict the voting functionality to specific roles.

If you enable restrictions a list of all user roles will be visible to pick one by one the roles enabled to vote.


User identification settings

According to previous settings there will be scenarios in which we need to recognize unlogged user, this is necessary to avoid duplicates and to let users change their vote (see next paragraph).

To recognize unlogged users there are two ways: via IP address, via cookie or both.

Remember that the plugin will not be able to recognize unlogged users without one of these options set to “on” and that you have to mention this on your privacy policy to fulfill privacy law requirements in some countries.


Let users change their reactions

If you want your visitors to change their previous reactions enable this check.


Add reactions to content using Gutenberg [PRO]

If you enable the new Gutenberg editor you will be able to add multiple Reactions Buttons group to your content.

To add a Reactions Gutenberg block follow those instructions:

  • Click on the top left button to add new block.
  • Select Widget group.
  • Click on Reactions icon.

You may add as many blocks as you want, the result is a page like the one you are reading now: every paragraph has its own reaction buttons group.


Graphic settings

Graphic settings page contains some appearance features. A real time preview helps with settings.


Set reactions size

This is the size of reactions, set a value that best fit your layout.


Choose effect for inactive reactions

When a visitor votes a reactions the other icons may be de-emphasized using one of those effects: Transparence, Desaturate and Blur.

The “amount” slider is used to choose the effect amount.


Set a intro text to be displayed before reactions

You may set a text to be shown before reactions globally.


Widgets

This plugin provides several useful widgets. Some widgets are specific for frontend, others are useful in multisite installation.


Contents with most reactions

To display a list of contents with most reactions navigate to Appearance Widgets page.

Find a widget named Content with most reactions and attach it on a sidebar.

Widget settings.

Widgets settings lets you set some things:

  • Title: the title to display above the list.
  • Reaction: to filter results on a single reactions (most loved, most liked, most grr-ed and so on.)
  • Post Type: select between Post, Page, Media, Comment and every custom post type in your blog.
  • Number of posts to show: a limit number for the list.
  • Display post reaction image? Show the most used reaction icon near the content title.

Total reactions dashboard widget

Total reactions is a widget for the dashboard that shows a real time chart with reaction votes count.


Content types with most reactions

Reactions by content type is another widget for the dashboard and contains real time data about reactions grouped by content type.


Blog reaction summary [PRO]

Reactions by blog is a widget available only on Network dashboard in multisite installation. This widget shows real time statistics for all blogs in the network.


Frontend

If enabled, the plugin displays reactions buttons under every content, according to saved settings.

The buttons are lazy loaded to avoid slow loading of the site, especially if several buttons should be displayed, this happens typically on comments and archives.

Under the buttons there is a number that represent the total count of every reaction for every specific item.’


Responsiveness

On small displays the buttons are hidden ad are shown using the hamburger button navigation. This solution is compatible even with dozens of reactions buttons.

Reactions mobile layout.

Widget

The frontend widget shows the contents with most reactions according to some settings. View widget section for further informations’


Content

This plugin adds some functionalities to default WordPress editors too.


Reaction graph in content list

In content list (for example navigate to Posts » All posts page) there is one more column named reactions that shows a small chart with reactions statistics.

View statistics in content list.

Global settings on content page

Inside the edit page (every time you edit a content) there is a very useful section in which you may change global settings for all contents of the same type. These setting will affect the entire site, not only the current content.

Global settings on content page

Local settings on content page

Even if reactions are disabled for a specific type of content or for the comments to this type of content, inside the edit page there is a widget that allows you to activate reactions for one specific post, or custom type, or whatever you are editing. Those local settings does not affect other contents and are limited to the one you are editing.

Local settings on content page.

Statistics on content page

There is also a chart with real time statistics on reactions for this specific content.


BuddyPress Integration [PRO]

DaReactions works very well with BuddyPress, if you have BuddyPress active on your site you may enable some additional features from General Settings Page.

BuddyPress Integration settings

Use those settings to enable Reactions for BuddyPress’ Profiles, Activities, Comments and Groups.

Starting from version 1.3.0 DaReactions logs every Reaction vote to BuddyPress Members Activity Stream.

Reactions added to Activity Stream

Sources and Credits

This plugin is distributed under GPL 2 license.

Charts are made with ChartJS, a open source JavaScript library. See Chart.js

All vector icons are provided by Flaticon, and are free even for commercial use. See Flaticon


Advanced

This section is reserved to advanced users, if you need to customize this plugin in some ways that are not mentioned above you may find useful the lecture of next paragraphs.


PHP Classes

This plugin is entirely written using object oriented approach with PSR0 convention. All PHP classes are under /classes/, that is PSR0 root for autoload features.

A complete documentation, autogenerated with PHPDoc is included in archive, look for /documentation/ folder.


HTML structure

Frontend markup for this plugin is very simple:

<div class="da-reactions-container-async" data-type="post" data-id="1" data-nonce="df4c50fc98"></div>

This div is the container for the asynchronous loaded buttons, in this way pages are smaller and easier to load and debug.

The lazy loading function inject inside the previous div something like this:

<div class="da-reactions-container ">
    <div class="reactions-toggle"></div>
    <div class="reactions">
        <div class="reaction reaction_1 inactive" data-id="1" data-reaction="1" data-title="Like" data-type="post">
            <img src="/wp-content/plugins/wp-plugin-da-reactions/public/img/1/like-1.png" alt="Like" width="64" height="64">
            <div class="count">2</div>
        </div>
        <div class="reaction reaction_2 inactive" data-id="1" data-reaction="2" data-title="Love" data-type="post">
            <img src="/wp-content/plugins/wp-plugin-da-reactions/public/img/1/love-2.png" alt="Love" width="64" height="64">
            <div class="count">4</div>
        </div>
        <div class="reaction reaction_3 inactive" data-id="1" data-reaction="3" data-title="Ah Ah" data-type="post">
            <img src="/wp-content/plugins/wp-plugin-da-reactions/public/img/1/ah-ah-3.svg" alt="Ah Ah" width="64" height="64">
            <div class="count">5</div>
        </div>
        <div class="reaction reaction_4 inactive" data-id="1" data-reaction="4" data-title="Wow" data-type="post">
            <img src="/wp-content/plugins/wp-plugin-da-reactions/public/img/1/wow-4.svg" alt="Wow" width="64" height="64">
            <div class="count">6</div>
        </div>
        <div class="reaction reaction_5 inactive" data-id="1" data-reaction="5" data-title="Sad" data-type="post">
            <img src="/wp-content/plugins/wp-plugin-da-reactions/public/img/1/sad-5.svg" alt="Sad" width="64" height="64">
            <div class="count">6</div>
        </div>
        <div class="reaction reaction_6 inactive" data-id="1" data-reaction="6" data-title="Grrr" data-type="post">
            <img src="/wp-content/plugins/wp-plugin-da-reactions/public/img/1/grrr-6.svg" alt="Grrr" width="64" height="64">
        <div class="count">7</div>
    </div>
</div>

The final markup depends on settings and may vary from site to site.


Custom tables

This plugin works with two custom tables, all database related functions are in /DaReactions/Data.

The table structure is this:

TABLE %prefix%da_r_reactions

Name       |Type      |Length    |Key    |Default           |Extra
ID         |mediumint |9         |PRI    |                  |AUTO_INCREMENT
label      |varchar   |36        |       |"Reaction"        |
file_name  |varchar   |          |       |""                |
created_at |timestamp |          |       |CURRENT_TIMESTAMP |
color      |varchar   |36        |       |"#006699"         |
active     |smallint  |1         |       |1                 |
sort_order |smallint  |3         |       |0                 |

============================================================================

TABLE %prefix%da_r_votes

Name          |Type       |Length |Key    |Default           |Extra
ID            |mediumint  |9      |PRI    |                  |AUTO_INCREMENT
resource_id   |mediumint  |9      |MUL    |NULL              |
resource_type |varchar    |20     |MUL    |NULL              |
emotion_id    |mediumint  |9      |       |                  |
user_id       |varchar    |32     |MUL    |NULL              |
user_token    |varchar    |32     |       |NULL              |
user_ip       |varchar    |16     |       |NULL              |
created_at    |timestamp  |       |       |CURRENT_TIMESTAMP |

============================================================================

The choice to use own tables for this plugin is functional to some features:

  • The queries to pick most voted reactions, most liked posts and things like those are more simple and less time-consuming for the database.
  • In multisite installations every blog has its own tables that are independent from other blogs.
  • When delete all plugin data, on deactivate or uninstall, those table are dropped and there is no garbage left in database.

Add your own SVG

This plugin comes with 250 included SVG monochromatic vector icons, those kind of icons could be colored in real time using color picker; all other image types, such as JPG, GIF or PNG, cannot be colored in real time, and are not vector.

WordPress blocks SVG upload for very important security reasons, so it is impossible to use your own SVGs, but if you are a graphic designer or a developer and you know that your SVG files are 100 percent safe and don’t contain malicious script you may add your own graphic to this plugin.

  • Inside the plugin folder find /admin/icons/svg/ and create your own folder here. This folder name should not start with a underscore _ because files and folder which names begins with this character will be ignored.
  • Inside your own folder copy all your SVG files, just like all other plugin-provided files.
  • Navigate to Reactions » Reactions manager page and click on one of the icons to change graphic.
  • You SVGs will be listed belong the others, and the colorize function should work too.

Translate plugin

This plugin is entirely written in english, but it is one hudred percent compatible with translations using the common WordPress procedure that involves the use of PO and MO files.

The main POT file can be found inside /languages/ along with a complete italian translation that can be used as model.