Viafoura

The Viafoura Documentation Hub

Welcome to the Viafoura documentation hub. You'll find comprehensive guides and documentation to help you start working with Viafoura as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Viafoura Javascript API

Viafoura aims to empower our customers to integrate and customize our community engagement platform. By using our JavaScript API we allow you to subscribe to our event bus to allow you to integrate with your own analytics platforms, or add custom behaviors on certain engagement events. You may want to listen for new comments, or likes being added.

Another common integration is done by publishing your own events onto our event bus to trigger UI elements such as our notification tray, or trigger a login flow.

VfUniqueId

The unique_id attribute allows multiple URLs to be linked to the same page and thus, comments
created under associated URLs will be the same. You may specify any string you would like to
use as your unique_id, as long as it is no more than 100 characters in length.

If used incorrectly, unique_ids can lead to problems such as comments for different pages showing
in the wrong places. As such we recommend exercising caution when utilizing this feature.

Viafoura unique ID documentation

Type: String

vf

The JavaScript API exposes a global variable (window.vf) to enable easy interaction
with the Viafoura JavaScript code running on your page.

It is best used in conjunction with vfQ to ensure your callbacks run
after the Viafoura context has fully loaded.

Examples

// Make vfQ available or use existing one if already loaded
window.vfQ = window.vfQ || [];
window.vfQ.push(() => {
    // viafoura is loaded and window.vf is available
    window.vf.context.get('user').then((user) => console.log(user.name));
};

$publish

$publish - publish an event to a dispatcher.
View the full list of events.

Parameters

  • channel string channel event is taking place in
  • event string name of event
  • args array arguments to pass to callbacks

Examples

window.vf.$publish('tray', 'open', 'args');

$subscribe

$subscribe - subscribe to an event through a dispatcher.
View the full list of events.

Parameters

  • channel string channel of subscription
  • event string event of subscription
  • callback function callback when event occurs

Examples

window.vf.$subscribe('login', 'failure', function() {});

Returns EventSubscription subscription

$unsubscribe

$unsubscribe - unsubscribe from a channel/event combo through a dispatcher.
View the full list of events.

Parameters

  • channel string channel of unsubscription
  • event string event of unsubscription

Examples

window.vf.$unsubscribe('login', 'failure');

Returns array subscriptions unsubscribed from

$once

$once - subscribe once to a channel/event combo through a dispatcher.
View the full list of events.

Parameters

  • channel string channel of subscription
  • event string event of subscription
  • callback function callback to call once when event is triggered

Examples

window.vf.$once('login', 'failure', function() {});

Returns EventSubscription one-time subscription

$prepublish

$prepublish - lifecycle hook to run before $publish invocation

Parameters

Examples

window.vf.$prepublish((channel, event, ...args) => {
    if (channel === 'authentication' && event === 'required') {
       return false;
    }
    return { channel, event, args };
});

context

The vf.context API is used to manage the application context and state. This
is primarily useful when working with single page apps,
infinite scroll implementations
and other similar functionality.

get

Returns a promise resolving to a context item (either page, or user)

Parameters

Returns Promise<(VfUser | VfPageMeta | VfNotifications)> resolves to a context object

teardown

This function is used to destroy the current viafoura context. It will:

  • Unsubscribe from realtime events
  • Destroy all widgets on the page
  • Posts engagement tracking data to our analytics server
  • Pauses window.vfQ

This function is intended to be used when you would like do perform some
intermediate actions between the teardown and setup steps of a page reset.

Parameters

  • shouldDestroyWidgets Boolean If false, widgets attached to a VfContainer remain in the DOM and their event
    listeners remain intact, if true, they are reverted to their original state before they were loaded as functioning components (optional, default true)

Examples

// First destroy the current viafoura context
window.vf.context.teardown()
    // Update the page meta information
    .then(updatePageMetaData)
    // Add some new widgets to the page
    .then(addNewWidgetContainers)
    // Finally restart the viafoura application
    .then(window.vf.context.setup);

Returns Promise<null> A promise resolving to nothing

setup

This function is used to initialize the viafoura application. It is used after
teardown to restart the viafoura application. It will:

  • Refetch the page meta data
  • Reloads all settings/page/user/language information
  • Reinitialize all widgets
  • Refire analytics
  • Restarts window.vfQ

This function is intended to be used when you would like do perform some
intermediate actions between the teardown and setup steps of a page reset.

Examples

// First destroy the current viafoura context
window.vf.context.teardown()
    // Update the page meta information
    .then(updatePageMetaData)
    // Add some new widgets to the page
    .then(addNewWidgetContainers)
    // Finally restart the viafoura application
    .then(window.vf.context.setup);

Returns Promise<null> A promise resolving to nothing

reset

vf.context.reset() resets the Viafoura JavaScript, loading any changes
to the meta tags, or other properties defined after page initialization.

Conceptually, calling the vf.context.reset() method is treated as a new
page load
. As such, this call triggers a full re-initialization of our
engagement tools, which means several requests to our REST APIs will be invoked.

Call this if Viafoura should display new content when no page reload was
triggered. This function will return a promise which resolves when it is finished.
Custom behaviour after the reset is finished can be chained onto the promise.

The Viafoura reset function internally runs both vf.context.teardown
and vf.context.setup.

NOTE: any changes to the widget after they have been loaded
will not take effect after a viafoura reset. i.e. if you change
the data-path of the commenting widget, viafoura.reset will not action that change.
This change was made to accomodate our new widgets.
If you would still like to use reset to change a data-attribute, you can call
vf.context.teardown, perform changes and then vf.context.setup.

Returns Promise<null> A promise resolving to nothing

loadNewPage

vf.context.loadNewPage() is used for an infinite scroll implementation. For more information on infinite scroll,
please refer to our infinite scroll implementations.
This function takes in an element and some page information and
will load all widgets inside the given element with the data for the given page.

The first parameter is an element denoting a new page. The element passed in should be a wrapper containing all
the html for the newly loaded page. All widgets in the DOM that are within this parent element will be initialized
after calling this function.

The second parameter is an object with defining attributes of a page: either the path or url or both the path/url and unique id. This information
will determine which page's data will be loaded inside the widgets on this new page. The path or the full url of the page is always
required and should point to the canonical URL for that page. For more information on unique id, please refer to VfUniqueId.

Parameters

  • el HTMLElement top level article container containing all the Viafoura widgets of this new page
  • options VfPageMeta an object containing information needed to identify which
                         page to load. Needs to include either the path or the url; it can optionally include a unique_id (optional, default `{}`)
    

Returns Promise<null> A promise resolving after the page data has been successfully fetched

topics

Topic subscriptions object

subscribe

subscribe to a topic

Parameters

  • topic_id String id of the topic
  • topic_name String name of the topic
  • topic_type String type of topic. Default is "topic"
  • store Object optional custom store (needed for tests)

Examples

window.vf.topics.subscribe("id", "topic");

Returns Promise promise that resolves when the topic subscription is complete

unsubscribe

unsubscribe to a topic

Parameters

  • topic_id String id of the topic
  • store Object optional custom store (needed for tests)

Examples

window.vf.topics.unsubscribe("id");

Returns Promise promise that resolves when the topic unsubscribe is complete

fetch

fetch a list of topics that can be subscribed to

Parameters

  • store Object optional custom store (needed for tests)

Examples

window.vf.topics.fetch();

Returns Promise promise that resolves to the list of topics

session

Object representing the current user session

Examples

window.vf.session;

logout

performs a viafoura logout

Examples

window.vf.session.logout();

Returns Promise promise that resolves when the logout is complete

login

viafoura login apis

loginRadius

login - attempts to login a LoginRadius account with the given access token

Parameters

Examples

window.vf.session.login.loginRadius("token")

Returns Promise login promise

jwt

performs a viafoura JWT login

Parameters

  • access String a viafoura access token for a user
  • refresh String a viafoura refresh token for a user
  • session String a viafoura legacy session ID for a user

Examples

window.vfQ = window.vfQ || [];
window.vfQ.push(function() {
    window.vf.session.login.jwt(access, refresh, session)
       .then((user) => alert(`You are now logged in as ${user.name}`))
       .catch((e) => alert(e.message));
});

Returns Promise promise that resolves to a user when the login is completeThe JWT login javascript function can be used to execute a login using an existing access/refresh token
pair as well as a legacy session ID. This will log in the user with Viafoura's servers and set any
necessary cookies and local state.See the full JWT login flow documentation for more information.

cookie

performs a viafoura cookie login

Parameters

  • cookie String string representing the login cookie

Examples

window.vf.session.login.cookie("token");

Returns Promise promise that resolves when the login is completeThe Cookie Login javascript function can be used to execute the Cookie Login Integration on pages that have
Viafoura engagement modules present like the Commenting Module. This javascript function requires your
Cookie Login Integration to be completed.View the full cookie login documentation.

social

performs a legacy viafoura social login

Parameters

  • type String string representing network to socially login from

Examples

window.vf.session.login.social("facebook");

Returns Promise promise that resolves when the login is complete

PUBLIC_CONTEXTS

The various context objects that can be accessed from the Viafoura JS API

Type: enum

Properties

  • user String Specify the "user" context
  • page String Specify the "page" context
  • notifications String Specify the "notification" context

USER_PRIVILEGES

Viafoura user privilege levels:

Type: enum

Properties

  • guest String Guest user privileges. Can only view but cannot take any actions (A guest user can post comments if anonymous comments are enabled)
  • user String Regular user privileges. Can perform regular user actions (e.g. post comment, like, follow)
  • moderator String Moderator user privileges. Can perform moderation actions (e.g. approve, disable)
  • administrator String Administrator user privileges. Can perform administrative actions (e.g. promote, demote)

vfQ

The window.vfQ api provides a safe mechanism for executing functions which
depend on the viafoura context and API. Because the API is loaded asynchronously
there is a need to have a method to queue functions to run once the Viafoura
context is fully loaded.

Examples

// Safely initialize vfQ
window.vfQ = window.vfQ || [];
// add callbacks to vfQ
window.vfQ.push(() => console.log('window.vf.* is now ready'));

isLoggedIn - Deprecated

Checks if the current user is logged in or not

Examples

window.viafoura.core.current.user.isLoggedIn();

Returns boolean true if the current user is logged in and false otherwise

Meta

get - Deprecated

Gets the current value of the attribute specified from current user

Parameters

  • attribute String key of the attribute being grabbed

Examples

window.viafoura.core.current.user.get('name');

Returns any value of the attribute and undefined if it doesn't exist

Meta

viafoura - Deprecated

The legacy viafoura JavaScript API exposes an object on the window: window.viafoura

Examples

window.vfAsyncInit = function(){
    // viafoura object is available
    window.viafoura.ready(function(){
        // viafoura is loaded
        window.viafoura.users.current().name;
    });
};

Meta

  • deprecated: This has been deprecated in favour of vf

users - Deprecated

Legacy object representing the current user. See VfUser

Meta

  • deprecated: This is deprecated.

cookieLogin - Deprecated

Passes calls through to the new login.cookie function

Parameters

Examples

window.viafoura.users.cookieLogin();

Meta

current - Deprecated

Returns the current user

Examples

window.viafoura.users.current();

Returns VfUser object representing the current user

Meta

updateDisplayName - Deprecated

updateDisplayName - updates the current user's display name

Parameters

Examples

window.viafoura.users.updateDisplayName("Albert Einstein")

Meta

  • deprecated: This function is deprecated

poll - Deprecated

viafoura.poll() scans the page for uninstantiated Viafoura Social Plugins,
and instantiates them. Call this if Social Plugins are dynamically added
to the page long after the page is loaded.

Examples

window.viafoura.poll();

Meta

  • deprecated: This has been deprecated in favour of $publish

session - Deprecated

Legacy object representing the current user session

Examples

window.viafoura.session;

Meta

login - Deprecated

login - Performs a login using a session

Parameters

Examples

window.viafoura.session.login.session("uo98vnm2jifnk8lrba8ahc59p7",
  function (currentUser) {
      if (currentUser.user_privilege === "guest"){
          console.log ("not logged in");
      }
  });

Meta

  • deprecated: This function is deprecated

logout - Deprecated

performs a legacy viafoura logout

Examples

window.viafoura.session.logout();

Meta

logins

Legacy viafoura login apis

cookie - Deprecated

performs a legacy viafoura cookie login

Cookie Login javascript function can be used to execute the Cookie Login Integration on pages that have
Viafoura engagement modules present like the Commenting Module. This javascript function requires your
Cookie Login Integration to be completed.
See https://documentation.viafoura.com/v2/login_integrations_cookie.php for more information

Parameters

  • cookieValue String string representing the login cookie

Examples

window.viafoura.session.login.cookie("token");

Returns Promise promise that resolves when the login is complete

Meta

social - Deprecated

performs a legacy viafoura social login

Parameters

  • network String string representing network to socially login from

Examples

window.viafoura.session.login.social("facebook");

Meta

loginRadiusLogin - Deprecated

performs a legacy viafoura login radius login

Parameters

Examples

window.viafoura.session.login.loginRadiusLogin("token");

Meta

current - Deprecated

Gets the session id

Examples

window.viafoura.session.current();

Returns object object containing the session id

Meta

  • deprecated: This function is deprecated and will be removed in the future

ready - Deprecated

viafoura.ready() takes a callback function, and is called once Viafoura
is ready to process requests. This is called before the DOM is ready and
any widgets have been created.

Parameters

Examples

window.vfAsyncInit = function() {
    window.viafoura.ready(function () {
        // This code will be run when Viafoura is ready
        console.log('Viafoura is ready');
    });
}

Returns Promise promise that resolves when the function has run

Meta

  • deprecated: This has been deprecated in favour of vfQ

context - Deprecated

The viafoura.context API is used for managing the application context.
See vf.context for information about API members.

Meta

  • deprecated: This has been deprecated in favour of vf.context

ui - Deprecated

Viafoura.ui

Meta

  • deprecated: This is deprecated and will be removed in the future

publish - Deprecated

Legacy publish event. Should show a deprecation warning and then convert the legacy event
to an engage-2 one and publish it on the global event bus

Parameters

  • legacyEvent String legacy public event name
  • args any additional arguments to be passed to the listener

Examples

window.viafoura.publish();

Meta

  • deprecated: This has been deprecated in favour of $publish

subscribe - Deprecated

Legacy subscribe event. Should show a deprecation warning and then convert the legacy event
to an engage-2 one and subscribe to it on the global event bus

Parameters

  • legacyEvent String legacy public event name
  • callback function callback function

Examples

window.viafoura.subscribe('onLoginFail', function() {});

Returns Boolean returns true if the subscribe was successful and false otherwise

Meta

  • deprecated: This has been deprecated in favour of $subscribe

VfUser

This is a viafoura user

Type: Object

Properties

  • uuid Uuid
  • id Number
  • name String
  • user_privilege USER_PRIVILEGES
  • email_verification_status ModerationStatus
  • username_moderation_status ModerationStatus
  • avatar_moderation_status ModerationStatus
  • pic_small String
  • pic_large String

Examples

{
  email: "user@viafoura.com",
  id: 1000000004242,
  logged_in: true,
  likes_made: 4,
  likes_received: 0,
  name: "Viafoura User",
  pic_large: "https://s3.amazonaws.com/viafoura/user_pictures/1000000004242_5_120x120.jpg",
  pic_small: "https://s3.amazonaws.com/viafoura/user_pictures/1000000004242_5_60x60.jpg",
  picture_comments_made: 27,
  plain_comments_made: 35,
  subscriber_count: 0,
  user_privilege: "user",
  video_comments_made: 14
}

VfNotifications

The viafoura Notifications object contains information about the current user's
notifications

Type: Object

Properties

  • counts Object A collection of notification counts
    • counts.new Number The number of "new" (unseen) notifications, as shown in the Viafoura bell

VfPageMeta

A Viafoura page meta object describing page attributes for fetching/creating pages

One of path, url, id, or unique_id is required - path and url are mutually exclusive
Title, section are optional

Type: Object

Properties

Viafoura Javascript API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.