Oct 30 2018
kpv
Oct 30

The article continues the series started with Creating interactive content in CKEditor with VisualN Embed article.

It shows how to use IFrames toolkit provided with VisualN module to share embedded drawings across sites.

For our example we use a Drupal 8 site as drawings origin and a Wordpress site as a target resource exposing those drawings. The Wordpress site can be located at any domain and/or server and doesn't depend on the origin in any way.

[embedded content]

There are a couple of use cases when you might want to share drawings:

  • to share content with you audience to promote your brand, attract new users (generate quality traffic) or spread your data / knowledge across the Internet
  • to create SaaS-like solutions when users use your site to create content and reuse on their sites (e.g. Flickr)
  • to use it as a backend platform for your other resource (as in the video above, Drupal 8 can be used as a backend for Wordpress)

 

Generating quality traffic, promoting brand, spreading knowledge

Any shared drawing can be configured to show origin link near (at the bottom by default) the drawing.

Origin links allow to attract new target users from third-party sites. Clicking that link user is redirected to the origin site. Of course, you can't oblige users to click those links, so the user should want or find it useful (e.g. for some additional info) to click it. That makes it fair to expect that mostly target users will click the link under shared content. And thus generate quality traffic.

You can also manage which pages exactly to direct those users to, per drawing basis or multiple at once (using tokens* or relying on defaults). It allows you to better run marketing campaigns, e.g. to temporarily switch shared drawings to direct traffic to a specific page of interest. Also no restrictions are placed upon link url, it may even point to a different site, which allows you to share traffic.
Usually origin page url (i.e. the page where drawings appears) is used by default.

Though it is not always necessary for user to click the link to achieve your goals. Sometimes just showing the content is enough. E.g. when content is obviously related to your brand, it already accomplishes its promoting functions. Or if you want just to share some knowledge (e.g. plastic waste amounts in oceans dynamics), then its still enough that user just reads it. And of course someone should also want to share your content.

These and some other ideas (including those presented below) served as a foundation and composed the notion of Fidelity Marketing, something that can be seen as another branch of Internet Marketing (along with Content and Referral marketing). The concept is developed and promoted within the scope of VisualN Project.

* There are still tasks to do for better tokens support

Creating SaaS-like solutions

With the IFrames toolkit you can build solutions the primary purpose of which is to provide some service to users. There are a lot of such services on the Internet - some of them allow to share images (e.g. Flickr), slides presentations (e.g. Slideshare), data visualizations etc. Now you can build yours of any of these and other types or invent something different.

Also you can add such functionality to an already existing site which would add additional value to it and its users.

Using as a backend for some other resource

Imagine that you or your client (if you are a developer) owns a site made on some other framework or CMS.

When using Drupal with VisualN along with your primary site (if not D8), all embedded content is at one place and belong to your infrastructure, so you don't depend on third-party services providing similar services (e.g. charts or galleries), also it allows to use such solutions in internal, e.g. corporate systems without need to access Internet.

On the other hand VisualN is a general purpose graphical content authoring and sharing framework and can replace multiple other solutions having more specific implementation area.

Configuration details and Sharing settings

As mentioned before, the sharing functionality is provided by VisualN module, namely with VisualN IFrame submodule. At the moment it supports sharing for embedded drawings and drawings created as generic Drupal blocks, provided by VisualN Block submodule (which goes beyond the subject of the current article).

When enabling sharing, you have some options to configure. The following settings are available.

Use defaults - the defaults are set on IFrame settings page. Allows shared drawings to reuse global IFrame settings without saving locally for each single one. Useful to change settings for multiple shared drawings at once.

Show origin link - whether or not to show origin link at the bottom of shared drawings.

Origin url - by default current drawing page url is used. Though you can use some custom page for a specific drawing iframe as origin.

Origin title - you can set any title for the link to appear under the shared drawing. Of course, you can override shared drawing template to change its style or use an image instead of the origin link, e.g. origin site logo.

Open in new window - whether shared drawings links should open origin site in a new window or not.

Conclusion

These are just some obvious implementations of IFrames toolkit, you are encouraged to develop yours. Also the subject itself is relatively new to Drupal ecosystem since there were no noticeable attempts to create a such. As well as for other popular Content Management Systems.

Oct 23 2018
kpv
Oct 23

In the video below we will show you how to create an interactive and informative content based on a couple of xls files and a handful of images using just CKEditor wysiwyg.

ckeditor to content screenshot

Our goal is to create a demo article with info on emperor pinguins, containing an interactive chart, a map and a gallery. For that we are using just functionality provided by VisualN modules pack (with a couple of generic dependencies).

[embedded content]

* Actually opening and closing dialog window before embedding a drawing is not really required - drawings can be embedded at saving clicking 'Save and embed' or updating the list clicking 'Update list' and then the 'Embed' button. Though there is a Drupal core issue that should be fixed.

The structure of xls files is as follows (the last screenshot also represents images used):

Excel file containing colonies demo data Excel file containing colonies demo coordinates Images for colonies demo gallery pinguin colonies demo datapinguin colonies demo coordinatespinguin colonies demo gallery

Each xls file contains a plain data table. The first row is used for data keys. Generally it can contain any keys - remapping is shown in the video. Actually remapping is required only for the first demo_data.xls file, since data_coords.xls keys already coincide with those used by LeafletMapBasic drawer.

The configuration steps and other details are subject for upcoming articles series.

All the drawers used in the video are provided with the VisualN contrib module. You can also see them in action based on generated sample data at https://visualnxpress.com. Feel free to subscribe for updates. Also it serves as an example of using different resource types (i.e. generated data instead of xls file) with the same drawer showing how flexible and resource-type agnostic drawers are.

Coming up series:

  1. Getting started
  2. Creating visualization styles
  3. Creating drawing (entity) types
  4. Configuring VisualN Embed integration with CKEditor
  5. Using VisualN Excel module for Excel files support
  6. etc.
Dec 26 2017
kpv
Dec 26

For content managers as well as developers Drupal provides a lot of tools and approaches to create content of different types and flavours, from simple text to structured layouts with much of graphics and media. Though still there is enough uncertainty and complexities with authoring experience. Some tasks are even hardly accomplishable without coding or require a sensible effort to. Here to the rescue comes VisualN. The VisualN module brings a generic approach to carry out many of those "painful" and daunting tasks with ease and fun. What is important, it hides the complexities from user to make interaction intuitive and joyful.

The drawing above as any other drawing in the article is fully created and configured via UI with no single line of code or extra modules. To embed drawings into content VisualN provides a rich set of approaches and their combinations so that user wouldn't be limited in his content structuring strategies and could stick to the preferred ones. For the examples in the article we've chosen to use visualn token functionality to embed drawings via simple tokens of [visualn:embed:drawing:id] format. Though you can choose to use Paragraphs or even embed drawings via iframes (which generally is more suitable to embed drawings into third-party sites content).

So what a drawing is and how it works

There is practically no limit on what a drawing can be. For purposes of the article though we can say that a drawing is basically a piece of content or markup with styles, scripts and settings attached generated by a drawer plugin or fetched by a fetcher plugin (which commonly relies on a drawer). Drawer may also need some data to generate drawings, e.g. maps need a list of points with geodata, charts may need some kind of statistics in which case data can be provided for it. Data can be provided as files or retrieved from many other types of sources, even generated on the fly - VisualN provides all required tooling and infrastructure.

The gallery above is considered to be a single drawing, there is no difference for VisualN what kind of drawing it is: map, chart, video, gallery or anything else.

The spectrum of use cases

As with any other technology there is always a question on where and how to use it. A short answer would be to use drawings as you would use images. Just configure a drawing entity and insert it where you need it. Though you can also create a drawing block or add one of VisualN field types to a content entity and create a drawing directly when editing it. For example, you can create a node type with a VisualN File field to upload data file (e.g. of JSON or some other supported format). After uploading a file you can configure a drawing that consumes the data just as any other field.

You can even create a view-based drawing - thanks to VisualN views display style provided by VisualN.

Examples always speak better so lets give some:

  • Place a map somewhere in an article. The map itself would take data from some arbitrary source of a mixed format
  • Create two charts (one as a block, another as a node field) of two different types but using one set of data uploaded to a Data Set entity. When updating the file in one place, all charts using it change accordingly
  • Generate some static markup clientside and insert it into content
  • Create a set of paragraphs each of which would generate content incorporating different types of visualizations or media
  • Embed a locally created gallery or a chart into a third-party site content
  • Create a graph showing Drupal Commerce sales
  • Output an always up-to-date chart using data from an external url resource
[embedded content]

Hopefully you have already grasped the idea for now.

Drawer and Drawing are the base concepts for VisualN, everything else is build around them to make it possible to use drawings in different contexts, provide data, handy configuration UI etc.

It is worth to mention that Drawer always comes together with another structural element, Visualization style, which is basically a wrapper around a drawer that stores some default configuration for it and can be used directly without the need to fill in the config every time you want it. Of course there can be created multiple styles for a given drawer.

Where to get those drawers

If you are a programmer you can easily create a drawer for whatever you need and share it with community. We are working on a visualizations open registry at visualn.org so that you could use it to let people know about your work.

If you are not a programmer and you don't find a drawer that supplies your needs, you can make a description of what you need and share it with community. If they find it interesting and useful you can expect someone to make it - creating drawers is really easy and entertaining.

In some cases you don't even need to look for a drawer - it's enough to find a configuration.

As the approaches get more mature and more drawers appear out there, the more ways to solve the same task will appear. There is a concept of "generic drawer" - a highly flexible drawer configured with a set of rules set in JSON format. Such drawers are able to create a rich set of different drawings though may be a bit more complex to configure (actually depends on every single drawer). Both charts in the given article are created using just one single "generic" drawer.

Thus, to get a specific drawing you can choose a suitable configuration set, shared by other users or just read specs and make yours.

Let user explore the context and look beyond the text

There is no reason to treat users just as passive observers or readers.

You should motivate them to think and to explore. That will help to create grateful audience and you will gain real adepts that come to your site consciously, not just clicking search results links.

The yearning for exploration is a natural one for human beings, so why not benefit of that?

Often a good visualization can better express the idea then a ton of text. Also visually attractive and interactive content keeps visitors longer on your site or even brings new ones.

Surely, content should be also informative and meaningful or it doesn't work.

Why it really matters

The Wild Wild Web...

Content defines the success. Without quality content there is a strong chance to become just another cactus to stay alone in the desert not worth of any special attention.

[embedded content]

Technology won't make outstanding content for you but when you have something to say or to share it can help to communicate the message to the audience effectively.

Drawings have been a universal language for centuries and still they are. Technology in its turn brings extensive ways and tools to "draw" those drawings and make them interactive. What is true, it can make really great things in right hands.

Nov 16 2017
kpv
Nov 16

In the screencast we show how easily a custom VisualN Drawer can be created and how versatile even such a basic drawer can be.

VisualN is a Drupal 8 module used to visualize any data from any source in practically any way. The example here demonstrates how to create a Slick gallery using VisualN toolkit.

Charts, maps, dashboard etc. drawers can be created in a similar way. You can read more on creating drawers strategies in this article.

[embedded content]

Prerequisites

  1. Enable VisualN module and its submodules
  2. Extract D3.js library to libraries/d3 (path should be libraries/d3/d3.min.js)
    D3.js is the only requirement for VisualN to work (though each drawer may have its own dependencies). Read more about D3.js on https://d3js.org/
  3. Extract Slick.js library to libraries/slick (path should be libraries/slick/slick/slick.min.js)
    Since our drawer is based on Slick.js gallery script, we need it too.

Libraries

Add an entry into the custom module libraries.yml file to attach the Slick.js assets.

my_module.libraries.yml

# attach slick.js library (mostly a copy-paste from slick.libraries.yml from Slick module)
slick-lib:
  remote: http://kenwheeler.github.io/slick/
  version: 1.x
  license:
    name: MIT
    url: https://github.com/kenwheeler/slick/blob/master/LICENSE
    gpl-compatible: true
  js:
    /libraries/slick/slick/slick.min.js: { weight: -3, minified: true }
  css:
    base:
      /libraries/slick/slick/slick.css: {}
      /libraries/slick/slick/slick-theme.css: {}
  dependencies:
    - core/jquery

and another entry for drawer javascript (see js/drawers/custom-slick-gallery-drawer.js below).

# drawer-specific library
custom-slick-gallery:
  js:
    js/drawers/custom-slick-gallery-drawer.js: {}
  dependencies:
    - my_module/slick-lib

Drawer Plugin

Here we use drawer plugin file to extend a boilerplate class, attach drawer javascript library and provide script with info about data source to use for the drawing (which is done under the hood).

Boilerplate classes are used to create generic drawers in minimum time and effort.

src/Plugin/VisualN/Drawer/CustomSlickGallery.php

<?php

namespace Drupal\my_module\Plugin\VisualN\Drawer;

use Drupal\visualn\DrawerBoilerplate\DrawerGenericBoilerplate;

/**
 * Provides a 'Custom Slick Gallery' VisualN drawer.
 *
 * @VisualNDrawer(
 *  id = "my_module_custom_slick_gallery",
 *  label = @Translation("Custom Slick Gallery"),
 * )
 */
class CustomSlickGallery extends DrawerGenericBoilerplate {

  public function prepareBuild(array &$build, $vuid, array $options = []) {
    // Attach drawer config to js settings
    parent::prepareBuild($build, $vuid, $options);
    // Attach visualn style libraries
    $build['#attached']['library'][] = 'my_module/custom-slick-gallery';
  }

  public function jsId() {
    return 'my_moduleCustomSlickGallery';
  }
}

In the given example we create quite a simple plugin, though such plugins can be used to create custom configuration forms, extend other drawers to change their behaviour, implement custom mechanics to create drawings (e.g. server-side drawings using ImageMagick) etc.

Drawer JS script

Drawer javascript is a de-facto standard way to create drawings. Nowadays there are multiple js libraries of any kind and flavour on the Internet, and each of them can be used to create a drawer based on it.

js/drawers/custom-slick-gallery-drawer.js

(function ($, Drupal) {
  Drupal.visualnData.drawers.my_moduleCustomSlickGallery = function(drawings, vuid) {
    var drawing = drawings[vuid];
    var data = drawing.resource.data;
    var html_selector = drawing.html_selector;
    var drawer_setup = drawing.drawer.config.drawer_setup;

    var slick_content = '';

    data.forEach(function(d){
      slick_content += '<div><img src="https://drupalbase.com/articles/creating-basic-slick-alternative-8-minutes-with-visualn-from-scratch/' + d.url + '" /></div>';
    });

    var slick_id = html_selector + '--slick-id';
    $('.' + html_selector).append('<div id="' + slick_id + '">' + slick_content + '</div>');

    $('#' + slick_id).slick(
      drawer_setup
    );


  };

})(jQuery, Drupal);

Using the Drawer

There are multiple ways and scenarios that VisualN drawers can be used in. In the video we will just see some of them:

  • Using a CSV file as data source
  • Using Views as data source
  • Creating a VisualN Block with a Share link

Drawer data keys

Data keys are used to remap input data keys. Imagine when drawer script expects data to have label and count columns but the source provides data with title and number columns. Data keys allow to seamlessly change column names. Actually they can even be used by Mapper plugins to restructure data.

Oct 25 2017
kpv
Oct 25

The listed below are some major approaches to creating VisualN drawers. Some of them need coding, some don't, some need just a couple of lines of code. Choose the ones that fit you and your case best. You may even find a drawer ready for you when the package registry at visualn.org is ready.

Base drawers

Base drawers are the basis of the whole system. They are those very mechanisms that draw visualizations. Everything else is build around base drawers.

A base drawer is typically a Drupal plugin and a javascript script. At minimum, a drawer plugin should implement VisualNDrawerBase::prepareBuild() method to attach the js library. Once it is done, the drawer is ready to use all across the system.

Base drawers made on top of other drawers

You can see how Highcharts Bar drawer is made on top of Highcharts drawer. Technically HighchartsBar drawer class just extends Highcharts class and overriddes a couple of methods to provide a more usable configuration form, nothing more. It has nothing to do with js scripts and underlying mechanics - everything is done by the parent class. It takes 5-10 minutes to create such a drawer but in result you get a drawer with a simple configuration form which doesn't require user to know anything about highcharts.js configuration format and accomplishes one specific function - draws a Bar chart.

Of course, you may create drawers as sophisticated as you wish - it is all up to your needs and imagination. The idea is to show a pattern to create drawer hierarchies - first one drawer with a generic configuration field (e.g. for options in JSON format) and capable to use every feature of a js library is created, then other more specific drawers are created on top of it.

You will see more implementation of the approach below.

Base drawers using drawer boilerplates

There are a couple of drawer boilerplate abstract classes which reflect common approaches to create drawers. Beside of being helpful to create generic drawers in minimum time and effort they also create an opportunity to create custom drawers for users who are not drupal developers or don't have any good php skills. A major such an audience is js/front-end developers that need a way to integrate their visualization scripts into Drupal.

User-defined drawers (subdrawers)

A User-defined drawer, or subdrawer, is a configured wrapper around a base drawer with possibly some drawer modifiers attached.

Subdrawers are created via admin UI (follow to Configuration > Media > Visualization > User-defined drawers (subdrawers) in the main menu) and fully configured manually. They work transparently to the system, i.e. the systems sees these wrappers as generic drawers with all interfaces of those. This is achieved by implementing a couple of simple ideas but we won't discuss it here (see documentation for that).

Drawer modifiers allow user to modify different aspects of drawer behaviour. A typical task is to hide one field from configuration form and add another more specific one. For example in case of Highcharts drawer we may want to set initial configuration for the drawer then hide it (so that users wouldn't be able to change it or wouldn't be confused by json), and then add a textfield that would allow to set just chart title.

Base drawers with setup select (wss-drawers)

WSS-drawers are base drawers that use Drawer Setups to store their configuration. Drawer Setups are configuration entities (see VisualNSetup entity type) and have their own UI to create (follow to Configuration > Media > Visualization > Drawer setups in the main menu). The main difference between wss-drawers and other drawers is that they have a select box (or maybe a couple) which allows to select a setup for the drawer, thus when configured it basically stores a reference to the drawer setup entity instead of setup contents by itself. When a drawing is prepared, the drawer simply loads the setup and applies it. There are several benefits of such approach:

  • Setups can be reused across multiple drawers
  • Multiple drawers, using the same setup, can be reconfigured in one change
  • Possibility to use different setup bakers to create a setup (a setup baker may be thought as a form type to input setup, see documentation for more details)
  • Moving all that "technical" raw configuration out of the drawer configuration form

Base drawers and configuration metalanguages

For some js libraries that is enough to provide just one array of options to create a visualization, for others it is hardly possible. For example to draw a pie chart a library may use PieChart(options) function and for a donut chart - DonutChart(options) function respectively. In this case we need to create some kind of a wrapper script and develop a metalanguage for configuration if we want to handle the drawer behaviour using just a generic set of options.

Base drawers using a set of js libraries at once

Let's say you want to create a drawer that would be capable of drawing charts using Highcharts.js and charts using C3.js. In this case you may just add some additional setting to the drawer configuration form to distinguish one from another. It may be a radio button that will point at the library, which configuration settings are intended for.

Combined drawers

Theoretically several drawers can be taken and combined to create one drawer that would allow them to communicate in some way with one another or to influence one other's behaviour. An example could be a map with points for some kind of objects and a chart (two independent drawings). Then they are combined into one drawer to achieve the following behaviour: when a user clicks an object, the chart shows some statistics or other info for that specific object.

The approach is quite promising though not developed at the moment.

Use ready drawers

When the package registry is ready, you can search there for a drawer to solve your task instead of creating a new one. There you'll be able also to improve someone's work and to share yours.

Plans and other approaches

There is a plan to create a UI for users to register js scripts as libraries without coding and to attach them to drawers or maybe subdrawers (a question of discussion). That would allow users, especially js-developers, to create drawers without a single line of php code. Also that would make it possible to develop some kind of compatibility layer for non-drupal js visualization scripts integration.

Combinations

No need to say that you can combine the approaches listed above. For example, you can move several custom scripts into one js library, create a configuration metalanguage for them and create a single drawer. Then you can use that drawer to create others on top of it or create user-defined drawers (subdrawers) based on the given one. In such a case you can make such a drawer that would provide the basis for all visualizations across the site.

There may be also edge cases when you would move several ready drawers (not just js libraries) into one drawer (and create a configuration metalanguage) that would serve as a wrapper for them and seamlessly instantiate one or another depending on the configuration and apply it to create a drawer. But you will hardly want to do something like that, it is mentioned here just for demonstration purposes.

Conclusion

As you can see, there are no strict limits of what and how you should do, and there is a broad set of variants and combinations at your disposal. The ones you choose depend on your cases and capabilities. Even if you are not a programmer, you can create user-defined drawers which can dramatically improve UX for your users involved in creating visualizations.

Feel free to experiment and.. keep it simple.

Oct 09 2017
kpv
Oct 09

The article and the screencast are not finished, revisit for updates.

The screencast demonstrates basic usage example of the Highcharts drawer provided with the VisualN module. Highcarts drawer allows to render any type of chart that highcharts.js library allows. Here we just show three use cases:

  • Create a visualization based on data file
  • Create a visualization based on external data resource
  • Sharing visualization, embedding into third-party site content

[embedded content]

Highcharts drawer itself is just a particular case of VisualN usage. VisualN isn't tied to any library or a set of tools, even to any single approach. That idea will be demonstrated in detal in further screencasts.

Scenario in short:

  1. Enable modules and copy js libraries
  2. Create a "highcharts demo" VisualN style based on the Highcarts drawer
  3. Create a data file in JSON format
  4. Create a custom "visualn demo" content type with a "visualn file" field of VisualN file type
  5. Configure "visualn file" field formatter
  6. Create a content of "visualn" content type, upload data file and apply "highcharts demo" VisualN style
  7. View result
  8. Copy link path to the uploaded data file
  9. Create and configure a VisualN block that points to the file
  10. View result
  11. Click the "Share" link and copy the embed html code
  12. Create a generic "Basic page" content and insert embed code into the content
  13. View result

VisualN installation and Highcharts set-up

Download and extract module archive as usual or use console toos (such as drush or drupalconsole). Note that you need the latest dev version at the moment since development is in progress.

  1. Enable the submodules from the package
  2. Download d3js library and extract to libraries/d3/d3.min.js (base js requirement for the VisualN module to work)
  3. Download highcharts.js library and extract to libraries/highcharts/js/highcharts.js (required for Highcharts drawer)

Create a VisualN style

VisualN style is the point which connects your data and the drawer to make a drawing. To create a VisualN style follow to Configuration > Media > Visualization > Visualization styles > Add VisualN style. Choose a drawer (Highcharts in our case), copy script setup into "Highcharts setup" field and save. The setup itself is specific for the library in use --- highcharts.js in the given example. There may be more user-friendly drawers that provide some generic fields for input like "title", "color" etc. for the user. Those can be easily created, see Highcharts Bar drawer for example. But here our goal is too show how flexible and generic drawers can be.

Now you will have that style available whenever you create a new drawing.

Create a data file

The data structure depends on the drawer in use. Data format can be json, csv, xml or any other for which a VisualN adapter exists. In most cases though you should use json since it is specifically intended for structured data for js scripts.

Create a content type with a VisualN file field

Now to upload a file you need to create a content type (or use an existing one) and add a VisualN Field to it.

Configure field formatter

In field formatter settings you should select default style and set default configration for the field. The style and configuration are used if user doesn't select a style in the field widget settings after uploading a file.

Create content and upload the data file

Now you can upload your data file. When the file is uploaded you will see a configuration form with style select and resource format. Choose json for resource format and the VisualN Style you've created earlier.

After you save the node, you should see the visualization rendered.

Create a VisualN block

Got to Structure > Block layout and create a block of "VisualN Block" type and add it to the "Content" region. Copy url for the file uploaded into the node field from the previous step (right-click on the link and select "Copy link location" from the pop-up menu) and copy it into the block configuration resource url field. Select the style from the select box and save. Now you should see the visualization rendered as a block.

Copy embed code and create a generic content

If you have enabled "Enable share link" in the VisualN block configuration settings then you will see a "Share" link under the visualization. On click there will appear a text box with html embed code - you can use it to embed the visualization into any site content.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web