UVisualize! Tutorial

An easy to use yet powerful visualization tool for WordPress

 
 

What is UVisualize?

UVisualize! is a Wordpress plugin that enables you to add posts into playlists and present these playlists by creating visualizations.

Get a complete feature overview on the plugin homepage.

Requirements

  • The plugin needs WordPress 4.0+ to work
  • To use the map module you need to have a geo plugin installed for adding locations to posts. We recommend using "Geo-Tag Simple". Download it here

Content

Overview

WordPress installation and setup

Add content to your site

Set up UVisualize!

How to use

Playlists
Visualizations
Widgets

Developer documentation

Theme functions

Create your own module

Additional action hooks

Overview

Posts

We assume that you are already familiar with the Wordpress basics. Therefore, you know what a post  is and what types of information it can contain. In this tutorial, we’ll focus on the following attributes of posts:

  • Title
  • Content 
    HTML text, may include attachments from the media library such as images, sounds and videos
  • Publishing date
  • Geo data
    Geographical data is not a standard attribute of a post, meaning it’s not available without extending the functionality of Wordpress by installing a plugin.

Playlists

UVisualize! enables you to organize posts in the form of playlists, meaning that a playlist is actually a collection of references to single posts.

The term references is important here: If you change a post’s attributes after adding it to a playlist (e.g. by adding pictures from the media library), you don’t need to refresh the playlist that this post appears in by hand - UVisualize! will take care of using its “freshest” content.

Visualizations

A visualization is a way of presenting a playlist’s content.

There are 3 different types of visualizations available in UVisualize!:

  1. Layers: displays posts along an axis, that is either 3D, horizontal or vertical
  2. Map: shows markers based on posts’ geo data on a customizable map
  3. Timeline: organizes posts into a horizontal time line




WordPress installation & setup

We will explore the installation of WordPress in form of a step-by-step walk-through. Just follow the steps mentioned below to recreate this scenario using your own Wordpress installation.

First of all, we’ll need to do some preparations before being able to step through our test scenario:

Video tutorial



Set up a MySQL database

  1. Wordpress needs a database for storing its data, so create a new database on your web server (or localhost, in the case of this tutorial).
  2. Make sure you have the database name, its user name and password for accessing it and the database host available, we’ll need this in the next step.


Install & set up Wordpress

  1. Download the latest version of Wordpress here: https://wordpress.org/download 
  2. Extract the .zip file to a folder on your web server (or localhost, in our case)
  3. Rename this folder to “uvisualizetut”
  4. Open this folder in a browser to begin configuring your Wordpress installation (the link should be something like http://www.yourserver.com/uvisualizetut or http://localhost/uvisualizetut  (in our case)
  5. Enter all the required information until the installation is finished (you’ll need the information about your database we created in step 2)
  6. Log in to your dashboard
  7. Make sure you use the theme TwentyFifteen by navigating to “Appearance” > “Themes”

How your dashboard should look after installing & setting up Wordpress


Set up UVisualize!

Navigate to UVisualize!’s main page (“UVisualize!” > “UVisualize!”)

UVisualize!’s plugin main page Follow the instructions listed on top:

Download & activate plugin

Install the following plugins (you should be able to find them when you search for plugins in the section “Plugins” > “Add New” in your dashboard).
Otherwise download them here, unzip them and put the two folders "uvis" and "geo-tag-simple" into your directory /wp-content/plugins/.
  1. UVisualize!
  2. Geo Tag Simple
    This is the recommended plugin for adding geographical data to your posts.
Activate these 2 plugins by navigating to “Plugins” > “Installed Plugins” and clicking “Activate”

How your dashboard should look after installing the UVisualize! and the Geo Tag Simple Plugin  

Activate plugin modules

Activate every plugin module you want to use. The modules "Visualizer" and "Playlist function" are required for the plugin to work. Use the "Example" module for learning how to create your own visualization module.
Click on “Go to page” and click “Activate” for all listed modules.

Check the plugin settings

Click on “Go to page” and find the 3 tabs “General Settings”, “Playlist” and “Map”. We can actually leave everything as it is for the purposes of this tutorial, but here’s a short explanation of the different settings:

  1. Enable the dropdown menu in frontend?
    Enables us to add a dropdown button into our frontend next to posts that only appears when we’re logged into the WordPress backend/dashboard. This requires digging into the PHP code, we’ll explain this in section "Assign posts to a playlist (frontend)"
  2. Amount of recently modified playlists
    How many playlists to display in the dropdown menu. Recent modified playlists are listed on top.


  1. Treat shortcodes as attachments:
    If you are using third party plugins which use shortcodes (e.g. for embedding an audio player in your post) you can choose those shortcodes to be treated as they were attached media files. Ticking this option will extract the shortcode and its file from the post's content and puts it in the media files section of the visualization instead of displaying it inline. This will only work if the file which you included by a shortcode is located on your own server.


This tab enables us to
add our own maps to use in the “Maps” visualization by defining a name, base tiles and so on.
  1. Add new basemap
    To edit the options of an existing basemap choose it from the drop down menu. Its data will be loaded into the form subsequently.
    Leave "Add new", fill out the form and press Add to add a new one. Press Save Changes afterwards. Every user will be able to use this new basemap from now on for a map visualization.
  2. Map name
    Give the map a name which is easy to remember. (e.g. Sattelite images of the USA)
  3. Unique identifier
    Give the map a unique name which only consists of letters, numbers, underscores and dashes. (e.g. sattelite-images-usa)
  4. Basemap URL
    The URL to a basemap's server tiles (e.g. http://otile{s}.mqcdn.com/tiles/1.0.0/sat/{z}/{x}/{y}.png). Requests require at least 3 of 4 variables:
    1. {s} = subdomains (optional)
    2. {x} = longitude (required)
    3. {y} = latitude (required)
    4. {z} = zoom level (required)
  5. Subdomain names
    Define the subdomains provided by the tile server. You only need to specify this if you used the subdomain variable {s} in the domain name above. Separate them by comma. E.g. if you type 1,2 in the above example the subdomains http://otile1.mqcdn.com/tiles/... and http://otile2.mqcdn.com/tiles... will be accessed as tile servers.
  6. Max. Zoom Level
    Each basemap has a maximum zoom level (around 1 - 24). Specify it here to tell the map module when to stop zooming.
  7. Description and copyright notes
    Give the official basemap description and add the mandatory copyright notes provided by the tile server.

Update permalinks

Click on “Settings -> Permalinks”, set the value for “Common settings” to “post name” and hit the Save Changes button. This makes the URLs of our site readable more easily.

This will make pretty URLS to playlists and visualizations available (e.g. mysite.com/playlist/my-first-playlist or mysite.com/visualization/my-first-visualization)


Copy theme files

Copy the 3 PHP files that take care of displaying your playlists and visualizations:
  1. Navigate to the directory “/wp-content/plugins/uvis/theme_files” in your Wordpress directory
  2. Select the files archive-uvis_playlist.php, single-uvis_playlist.php and single-uvis_visualization.php
  3. Copy those files to the directory “/wp-content/themes/twentyfifteen

The 3 PHP files required in our theme directory

Add content to your site

Video tutorial

Add pages & a menu

Since we started with a blank Wordpress theme, there are no pages to display on our site yet. Therefore, we’ll do the following:

Add 2 pages
  1. Dashboard: navigate to “Pages” > “Add New”
  2. Enter the title “Home” and click “Publish
  3. Dashboard: navigate to “Pages” > “Add New
  4. Enter the title “Blog” and click “Publish
Change the appearance
  1. Dashboard: navigate to “Appearance” > “Customize”
  2. Click on “Static Front Page
  3. Change the value of the “Front page displays” field to “A static page
  4. Set the value for “Front Page” to “Home
  5. Set the value for “Blog Page” to “Blog
  6. Click “Save & Publish
  7. Click on the “X” icon to return to the dashboard
Add a menu
  1. Dashboard: navigate to “Appearance” > “Menus”
  2. Enter a menu name into the “Menu Name” field
  3. Click on “Create Menu
  4. Select “Blog” and “Home” in the “Pages” box (left)
  5. Click on “Add to menu
  6. Change the order of your menu according as you like by dragging them around in the “Menu Structure” box (right)
  7. Activate the “Primary Menu” checkbox
  8. Click “Save Menu


The result: Our site with a sidebar menu.

Add posts

Now we’ll create 3 posts that we’ll later use in a playlist:

Video tutorial

Dashboard: navigate to “Posts” > “Add new”
  1. Title: “Destination found!
  2. Content: “This is the first post’s content.” + an image from the media gallery (you can just upload any image from your hard drive)
  3. Add a geolocation to the post (Box “Geo Tag” on the bottom)
  4. Click “Publish
    Our first new post.

How to use

Playlists

Create a playlist

As you can see in the screenshot below, there is a new column on the right of our Posts overview page called “Add to playlist”. This column is created by the UVisualize! plugin and enables what it promises - adding posts to a playlist.

Clicking one of the Playlist buttons next to a post (1) shows a dropdown menu with 2 entries: “Create Playlist..” (2) and “Manage Playlists..”, which are pretty self-explanatory. Notice that we can’t actually add a post to a playlist yet, since we haven’t created one so far.
We can change this by clicking the
Create Playlist..” (2) menu entry and entering a name for it, which in our case will be “Holidays 2015”.

Creating the playlist “Holidays 2015”.

Assign posts to a playlist (via dashboard)

After we added a playlist to the system, it will be available in the dropdown menu. So what we’ll do now is:

  1. Click the dropdown button (1) next to the post “Destination found!
  2. Click on “Holidays 2015” to add the post to this playlist.
  3. Repeat this for every post you want to add to the playlist.

Adding the first two posts to our playlist.

Sort items


Clicking on the Edit Playlist button beside the playlist opens a new window for sorting its items.

Quick edit playlist

Bring your items in the right order by dragging them around or remove certain items from your playlist by pressing the trash button. Removing an item will only remove the item from the playlist and won't delete the post itself!
Press "Save" afterwards or "Delete" to remove the whole playlist.

Assign posts to a playlist (via frontend)

Since we didn’t uncheck the “Enable the dropdown menu in frontend?” in UVisualize!’s settings in the beginning, we are able to use a short PHP code snippet to show the dropdown button for adding posts to playlists in the front end.

In order to achieve that, we need to do the following:

  1. Open the file “/wp-content/themes/twentyfifteen/content.php” in a text editor
  2. Look for the line that says <header class=”entry-header”>
  3. Insert the code snippet <?php uvis_playlist_dropdown(); ?> below this line.
    If you want your site to keep working if the UVisualize! plugin was deactivated, use the code <?php if( function_exists("uvis_playlist_dropdown") ) uvis_playlist_dropdown(); ?> instead.
  4. Save the file content.php

Adding the Playlist dropdown button to the frontend.

After this has been done, we can visit the “Blog” section of our site and see that the dropdown button for adding posts to playlists is available in the frontend, above the post title itself. This makes it even easier to add existing content to playlists, which is exactly what we’re gonna do with the post we haven’t added to our “Holidays 2015” playlist in our dashboard.


Adding a post to our playlist in the frontend of our site.

Manage playlists

Click on “Playlists” to manage all of your playlists in the backend.



Click on the a playlist's title to edit it further.



Left column:

  • Give your playlist a title, a permalink address and a description
  • Sort and remove playlist items in the area "Playlist" below.

Right column:

  • Create another visualization or edit an existing one
  • Set status and visibility for the playlist. Make sure to set it to "Publish" to let visitors access it.
  • Delete the whole playlist by clicking on "Move to trash"
  • Upload a thumbnail image for the playlist by clicking on "Set featured image"

Create a visualization

Now that we’ve created some pages, posts and a playlist containing some posts, we can start with creating visualizations based on our “Holidays 2015” playlist.

The first one we’ll create is a visualization of the type “Layers”, which displays our posts along an axis.

  1. Dashboard: navigate to “Playlists” > “All Playlists”
  2. Click on our playlist “Holidays 2015
  3. In the “UVisualize!” box on the right side, click on “Create visualization
    Create visualization
  4. In the appearing window, enter the name “First visualization” and press “Add
    Add visualization
  5. We’ll now see an overview of all the options we can choose to customize our visualization:

The UVisualize! main page.

Story Editor

Tell your own story by using the Story Editor. Adding a comment title and a text will replace the original post's content. Leave it empty to display the original content.

  1. Click on “Story Editor
  2. Give a title and enter a description for your visualization (in our case, literally “A description.”)
  3. Set the status to “publish
  4. Enter a comment title for our post “Destination found”:
    First visualization special comment
  5. Enter a comment description for our post “Destination found”:
    This description will be used in the first visualization.
  6. We will see the effect of adding a custom comment title & comment description in a bit, for now the window should look like this:
    Custom comment title and comment description for our first post.

Configure your visualization

Choose a visualization module by clicking on one of the blue buttons ("Layers", "Map" or "Timeline") on top.
What we see now is exactly what the viewers of your WordPress site see when they view our visualization, with one difference:

Settings panel
The “settings” dialogue, which enables us (the admins of our site) to change the appearance and behaviour of our visualization. Notice that this dialogue can be dragged around the window and minimized by clicking the “--” icon.

The “settings” dialogue lets us customize what our visualization looks like. It is split into four tabs: The first one is dependent on the module you chose and is explained later for each module.
See chapters "Create a layers visualization", "Create a map visualization" and "Create a timeline visualization" for more info.

For now we explain the default tabs "Content", "Playlist" and "Filters":

Content tab



Display content
This tab is available for all types of visualizations and lets you specify which post fields and attachments to display.
  1. Fields to show: Whether to display the post's title, its publication date, content and permalink.
  2. Attachment display: Choose the media types to display
  3. Autoplay: Enables automatic playback of your audio and video attachments when a post is opened. Visitors don't need to press the Play button anymore.

Playlist tab

This tab is available for all types of visualizations and lets you specify where and how to display the playlist itself. Additionally, the “Auto-animate playlist” feature enables automatic and time-based switching between our playlist.


Filters tab

This tab is available for all types of visualizations. Make timerange or taxonomy filters available to your visitors. Use these functions if your playlist contains a lot of posts.

Filters

  1. Show timerange: Enabling the timerange filter will display a panel to constrain the playlist by the date you chose (default is the date of publication "post_date")

    Timerange filter

    Drag the date labels and the playlist will only show posts which were published within this range.


  2. Filter by terms: To make a term filter available to your visitors, click on "Show filter panel" and it will appear on the screen. Choose a taxonomy to filter by first (e.g. "category" or "post_tag").
    Choose a taxonomy for filtering

    Choose a term: The list contains all terms of taxonomy "category" used by the posts in your playlist. Choose a term to add it to the filter options.
    Choose terms to filter by

    Your visitors are now able to filter your playlist by the clicking on the terms you chose:
    Displayed filter

    Remove the terms from the filter options by clicking on them again.

    Remove term from filter options

Create a "Layers" visualization

  1. Click on the “Layers” button in the top section, the window should look like this now:

This tab is only available for the “Layers” visualization and enables customization of the layer axis (3D, horizontal, vertical), whether we want to show layer controls, colors and the used font.


  1. Layers axis: Choose "3D" to create a three-dimensional space. Select "horizontal" or "vertical" to create a two-dimensional slideshow.
  2. Perspective x-axis: If using the 3D-axis change this value to bend space on the x-axis.
  3. Perspective y-axis: If using the 3D-axis change this value to bend space on the y-axis.
  4. Show layer controls: Tick the checkbox to display arrows for switching between playlist items (e.g. when you choose to hide the playlist).
  5. Design: Change the background color of the screen or of the layer's box as well as of it's font color and style.

Create a “Map” visualization

The second visualization we’ll create is a map that shows our posts according to the geo data we assigned to them:

  1. Dashboard: navigate to “Playlists” > “All Playlists”
  2. Click on our playlist “Holidays 2015
  3. In the “UVisualize!” box on the right side, click on “Create visualization
  4. In the appearing window, enter the name “Second visualization
  5. Click on “Add
  6. Click on “Story Editor
  7. Set the status to “publish
  8. Click on the “Map” button in the top section, the window should look like this now:

  9. As in all other types of visualizations, the “settings” dialogue lets us customize what our visualization looks like. Since all the tabs except the “Map” tab enable the same customization as in all the other visualizations, we’ll just discuss the possibilities of the “Map” tab:
Tab “Map”:
This tab is only available for the “Map” visualization and enables customization of...
  1. Base map
    Choose the design of your map. Consider that those data are loaded by external tile servers and that you might not see anything as long as you aren't connected to the internet.
    If you can't see a map though, another reason might be your webserver can't establish a connection to the tile server because it temporarily went down or has moved to another location.
  2. Marker icon
    Choose the marker icon to be an icon other than the default pin (e.g. a microphone, a play button, etc.)
  3. Marker color
    Choose a color for the marker icon.
  4. Spiderfy clustered markers
    This feature enables a thing that comes in handy when markers are close to each other on the map: When we move our mouse over an area containing markers that “overlay” each other, they are separated temporarily so the right one can be clicked.
  5. Box background
    Choose a background color for the box appearing when clicking on a marker.
  6. Box border color
    Choose a border color for the box appearing when clicking on a marker.
  7. Font color
    Choose a font color for the content in the box.
  8. Font
    Choose a font for the content in the box.
  9. Auto Zoom Map
    Whether the visitor should see all markers at once on one screen. If disabled, the visualization will start in the same view and zoom level when saved.
  10. Save & close
    After clicking “Save & Close” we return to the dashboard and again see our new visualization pop up in the “UVisualize!” box.

Create a “Timeline” visualization

The third an last visualization we’ll create in this tutorial is a “Timeline” visualization:

  1. Dashboard: navigate to “Playlists” > “All Playlists”
  2. Click on our playlist “Holidays 2015
  3. In the “UVisualize!” box on the right side, click on “Create visualization
  4. In the appearing window, enter the name “Third visualization
  5. Click on “Add
  6. Click on “Story Editor
  7. Set the status to “publish
  8. Click on the “Timeline” button in the top section, the window should look like this now:

  9. As we can see, all our posts are displayed on the same position on the timeline. That’s because we created them in the last few minutes, therefore their publish date is not far enough from each other to separate them along the time line.
  10. We need to change the publish date of our posts to see how they are distributed along the timeline in our visualization, this can be done by editing the posts and specifying a different post date, we just assume that you know how to do this.
  11. After changing the post dates and returning to our “Timeline” visualization, the posts are distributed along the timeline correctly.

  12. After clicking “Save & Close”, we return to the dashboard and again see our new visualization pop up in the “UVisualize!” box.

Save visualization

  1. After clicking Save and close we return to the dashboard.
  2. We now see a new section in the “UVisualize!” tab, containing our freshly created visualization. You can edit it further by clicking its name, or view how it looks for site visitors, and so on.

View as visitor

Click on "View" to display the visualization from the visitor's perspective

Permalink

Click on to display the permalink - the direct link to your visualization. Share it with others or copy & paste it into your posts to link to a visualization.

Shortcodes

Click on "<>" to display the shortcode. Copy & paste the code snippet into a posts to display a button which opens the visualization in full screen.

Delete a visualization

Click on the trash button to delete the whole visualization.



Using widgets

Add the UVisualize! sidebar widgets

The last thing we’ll do in this tutorial is to add the 2 widgets that come with UVisualize! to our sidebar:

  1. Dashboard: navigate to “Appearance” > “Widgets”
  2. On the bottom section of “Available Widgets”, we can find the “UVisualize! Recent Visualizations” and the “UVisualize! Recent Playlists” widgets.
  3. Add these widgets by dragging & dropping them to our “Widget Area” box, they will now be displayed in the sidebar of your site, enabling visitors to easily navigate between playlists and visualizations.


Adding the UVisualize! widgets to the sidebar.


Our sidebar after adding the widgets.

Developer documentation

Theme functions

Use these functions in your theme files.

Filter name Description
uvis_playlist_dropdown() Displays a dropdown menu for each post in the frontend: Add posts to playlists, create new playlists, manage existing playlists (sort items, remove items, save, delete)
uvis_the_playlist_items() Displays a playlist, its items and all of its visualizations. Use this in single view like single-uvis_playlist.php
uvis_the_visualizations( $playlist_id ) Displays all visualizations of a playlist
uvis_link_to_visualization( $visualization_id ) Displays a link to a visualization
uvis_visualize( $args ) Displays a button for an auto-generated visualization

uvis_playlist_dropdown()

This code will add the playlist dropdown to your theme.

<?php if( function_exists("uvis_playlist_dropdown") ) uvis_playlist_dropdown(); ?>

uvis_the_playlist_items()

To display the playlist and its items:

<?php if( function_exists("uvis_the_playlist_items") ) uvis_the_playlist_items(); ?>

To display a playlist, its items and links to all of its visualizations:

<?php if( function_exists("uvis_the_playlist_items") ) uvis_the_playlist_items( true ); ?>

uvis_the_visualizations( $playlist_id )

Displays all visualizations to a playlist.

The $playlist_id is the ID of a post with the post_type "uvis_playlist".

<?php if( function_exists("uvis_the_visualizations") ) uvis_the_visualizations( $playlist_id ); ?>

To display the default headline:

<?php if( function_exists("uvis_the_visualizations") ) uvis_the_visualizations( $playlist_id, true ); ?>

uvis_link_to_visualization( $visualization_id )

Displays a direct link to a visualization or opens it in an overlaying window.

By default it prints a direct link to the permalink destination.

The $visualization_id is the ID of a post with the post_type "uvis_visualization".

<?php if( function_exists("uvis_link_to_visualization") ) uvis_link_to_visualization( $visualization_id ); ?>

Set the second parameter to 'true' to open the visualization in an overlaying window instead of opening a new URL.

The $visualization_id is the ID of a post with the post_type "uvis_visualization".

<?php if( function_exists("uvis_link_to_visualization") ) uvis_link_to_visualization( $visualization_id, true ); ?>

uvis_visualize()

The function will automatically create a playlist from a query you choose. It expects the same arguments as in WordPress' get_posts() function. Put this code in your theme files (like /wp-content/themes/twentyfifteen/content.php

This example will create a playlist of all posts filed under the category "home" on the fly and will display it on a map.

$args["taxonomy"] = "category"; // Choose a taxonomy name (e.g. "category" or "post_tag" for tags)
$args["term"] = "home"; // Include posts in the playlist containing this term of the taxonomy above
$args["module"] = "map"; // May be any module name like 'map', 'layers', 'timeline' or any module you have installed

if( function_exists("uvis_visualize") ) uvis_visualize( $args );

Use these additional parameters to constrain the playlist to a certain number of total posts.

$args["offset"] = 0; // Where to start?
$args["posts_per_page"] = -1; // Where to end? (-1 is for displaying all)
$args["caption"] = "Open auto map visualization for the category home";

if( function_exists("uvis_visualize") ) uvis_visualize( $args );

Configure your auto-visualization by giving default values (which are usually made manually in the tabs "Content", "Playlist" and "Filters"). The default configuration options are as follows.

// Whether to display the playlist by default?
$args["uvis_playlist_display"] = 1;

// Where to display the playlist on screen?
$args["uvis_playlist_position"] = "overlay"; // 'top', 'left', 'right', 'bottom', 'overlay'

// Default playlist background color
$args["uvis_playlist_background_color"] = "#ffffff";

// Default playlist text color
$args["uvis_playlist_text_color"] = "#000000";

// Whether to display attached media files to a post at all
$args["uvis_attachment_display"] = 1;

// Default mediatypes which can be toggled in display
$args["uvis_attachment_show_mediatypes"] = array( "audio", "video", "image", "document" );

// Whether to autostart playing a video or audio file after selecting the playlist item without having to click the play button
$args["uvis_attachment_autoplay"] = 0;

// Database fields which can be toggled in display
$args["uvis_filters_show_fields"] = array( "post_title", "post_date", "post_content", "post_permalink" );

// Whether to display the taxonomy filter planel
$args["uvis_filters_enable"] = 0;

// Build the array structure for the filters
$args["uvis_filters"] = array( 0 => array( "uvis_filter_by_taxonomy" => "",
                                           "uvis_filter_by_taxonomy_term_ids" => array(),
                                         )
);

// Whether to display the timerange filter
$args["uvis_filters_timerange_enable"] = 0;

// Which date field the timerange uses to filter by default (database fields wp_posts.post_date or wp_posts.post_modified)
$args["uvis_filter_by_timerange"] = "post_date";

// Whether to auto animate the playlist and switch to one item to the next
$args["uvis_animation_autoplay"] = 0;

// Number of milliseconds to switch between playlist items
$args["uvis_animation_delay"] = 1500;

// Whether to show playback control buttons (forward, backward and play) (0 = disabled, 1 = enabled)
$args["uvis_animation_playbuttons"] = 0;

if( function_exists("uvis_visualize") ) uvis_visualize( $args );

Create your own module


UVisualize! provides a handy framework for creating your own visualization module.
Have a look at the example module located in /wp-content/plugins/uvis/modules/example/ to learn more about it.

Directory structure


Separate your code into the directories listed. Let's assume your module is called "example". The root directory used in this example is /wp-content/plugins/uvis/modules


Directory name Purpose Required files
/example/ Your module directory contains only one file: example.php (It must be named after your plugin directory!). This is where you register your module and hook into the UVisualize! framework to extend the datamodel for your custom configuration options using the provided filters and hooks. Use it to include your custom stylesheets too. example.php
/example/css/ Put your stylesheets in here (e.g. example.css). Include your styles like in the example below using the action hook uvis_enqueue_styles. example.css
/example/images/ Put all your images here. Provide at least an image representing your visualization method to be displayed on the UVisualize! welcome screen. It must be a JPG and must be named after your module directory name. In our example example.jpg example.jpg
/example/js/ Your javascript goes code in here. Usually you need two files: One which deals with your custom configuration options in the Visualizer settings panel: example.js. Those configuration vars can be added by using the filer uvis_datamodel. The other one reacts to the changes the user made using the control panel (its template is located in /examples/templates/settings.html) and renders the output: render.js example.js
render.js
/example/templates/ You need two templates: One for displaying your visualization and the control panels, named after your plugin directory: example.html. And one for the settings panel for configuring the visualization: settings.html. example.html
settings.html

Filters & hooks

Filters

Use these filters in your main plugin file: /wp-content/plugins/uvis/modules/example/example.php

Filter name Description
uvis_register_module Registers your module and lets you add a title and description to it
uvis_datamodel Add custom configuration options to the visualizer by extending the datamodel.
uvis_global_vars Make certain variables available to the main uvis JS variable (beside "playlist", "config" and "items")
uvis_add_postmeta_to_playlist_item Add custom postmetas to each playlist item and make them available to the visualizer

uvis_register_module

Use this filter to register your module and add a title and description to it. Don't forget to change the array key according to your module directory name.
/**
 * Registers a module and adds a description to it
 * The array key is the directory name of the module
 */
function uvis_register_example_module( $modules ) {

  $modules["example"]["title"] = "Example Module";
  $modules["example"]["description"] = "Bootstrap your own visualization by using this as a template";

  return $modules;

}
add_filter( "uvis_register_module", "uvis_register_example_module" );

uvis_datamodel

Use this filter to add custom configuration options for your module and set default values. These should be the options to change in the settings panel. (Its template is located in /modules/example/templates/settings.html).
/**
 * Adds the necessary configuration fields and their default values to the uvis datamodel
 */
function uvis_register_example_datamodel( $datamodel ) {

  // Some Example settings
  $datamodel["uvis_example_setting"] = "FooBar";

  // Some color setting
  $datamodel["uvis_example_color"] = "#FFCC00";

  // Default Font
  $datamodel["uvis_example_default_font"] = "Arial";

  return $datamodel;

}
add_filter( "uvis_datamodel", "uvis_register_example_datamodel" );

uvis_global_vars

If you need to add a fixed list of data to the datamodel in order to make it regularly available to the Visualizer, use this filter.

E.g.: In the Map module we use this filter to add a list of predefined basemaps to a dropdown menu.

/**
 * Registers the global vars necessary for my module to work
 *
 * - Adds a predefined list of something
 *
 */
function uvis_register_example_global_vars( $globals ) {

  $globals["mylist"][0]["title"] = "My Item 1"; // Item title
  $globals["mylist"][0]["description"] = "This is my item 1"; // Item description

  $globals["mylist"][1]["title"] = "My Item 2";
  $globals["mylist"][1]["description"] = "This is my item 2";

  return $globals;

}
add_filter( "uvis_global_vars", "uvis_register_example_global_vars" );

uvis_add_postmeta_to_playlist_item

By default each playlist item comes with its basic post data (which is saved in the database table wp_posts).
If you want to make post metas for each post available to the Visualizer, use this filter. (E.g. "geo_latitude" and "geo_longitude")
/**
 * Makes post metas of every playlist item available to Javascript
 */
function uvis_add_example_postmeta( $postmeta ) {

  // Make a certain post meta key available to JS
  $postmeta[] = "name_of_meta_key";

  return $postmeta;

}
add_filter( "uvis_add_postmeta_to_playlist_item", "uvis_add_example_postmeta" );

Action hooks

Use these action hooks in your main plugin file: /wp-content/plugins/uvis/modules/example/example.php

Filter name Description
uvis_activate_module Is called after a module was activated. Use this hook with the add_option() function to add default options after activating your module.
uvis_enqueue_styles Enqueue your custom backend and theme styles properly

uvis_activate_module

Use this action to add options or do other stuff after activating your module.

/**
* Is triggered after activating your visualization module
*/
function uvis_example_activate_module() {
  // Adds a necessary option into the table 'wp_option'
  add_option( "uvis_example_my_option", "my value" );
}
add_action( "uvis_activate_module", "uvis_example_activate_module" );

uvis_enqueue_styles

/**
 * Adds styles for the example in backend and frontend
 */
function uvis_example_enqueue_styles() {

  wp_register_style( 'uvis-example', UVIS_MODULES_URL . 'example/css/example.css', array(), UVIS_VERSION );
  wp_enqueue_style( 'uvis-example' );

}
add_action( "uvis_enqueue_styles", "uvis_example_enqueue_styles" );

Additional hooks

Confine editing playlists to their creators

/**
 * Confine editing playlists to their creators
 */
function uvis_restrict_playlists_to_authors( $wp_query_obj ) {
  global $current_user, $pagenow;

  // Constrain this action to the playlist edit screen
  if( 'edit.php' != $pagenow || $_REQUEST['post_type'] != 'uvis_playlist' )
    return;

  // Only let users edit who are logged in
  if( ! is_user_logged_in() )
    return;

  // Confines access to playlists for their creators (= authors) only
  $wp_query_obj->set( 'author', $current_user->ID );

  return;
}
add_action( 'pre_get_posts', 'uvis_restrict_playlists_to_authors' );

Confine the access to the playlist dropdown to administrators

/**
 * Make the UVisualize! playlist dropdown available to administrators only
 */
function uvis_restrict_playlist_dropdown_to_admins( $continue ) {
  global $current_user;
  return ( in_array( 'administrator', $current_user->roles ) ) ? true : false;
}
add_filter( 'uvis_before_playlist_dropdown', 'uvis_restrict_playlist_dropdown_to_admins' );

Add custom stylesheets to the backend

/**
 * Add CSS to the backend
 */
function uvis_example_add_backend_css() {
?>

  <style>
  /* Additional styles for the edit playlist screen and the visualizer in the backend */
  </style>

<?php
}
add_action( 'admin_head', 'uvis_example_add_backend_css' );

Add custom stylesheets to the frontend

/**
 * Add CSS to the frontend
 */
function uvis_example_add_frontend_css() {
?>

  <style>
  /* Additional styles for manipulating my theme and visualizations in the frontend */
  </style>

<?php
}
add_action( 'wp_head', 'uvis_example_add_frontend_css' );