Advanced widget integration

The UserDeck Guides widget can customized through an advanced installation allowing you to customize the look and behavior of your knowledge base.

The code is similar to the basic install except that the data-userdeck-guides attribute is not present. Removing this prevents the javascript from auto-dispatching your guides instance on page load. This is necessary in order to support single page applications (SPAs) such as those built with React.js or Vue.js.

Performing an advanced installation

To get started, copy this modified installation code into your page with the following example:

<a href="http://userdeck.net/g/xxxxxxxx" id="guides"></a>
<script src="//widgets.userdeck.com/guides.js"></script>
<script>
UserDeck.factory('guides', {
    // Required...
    key : 'xxxxxxxx',
    el : '#guides',

    // Optional...
    layout : 'leftnav',
    theme  : 'default',
    collection_id : null, // Initialize on a collection
    category_id : null, // Initialize on a category
    article_id : null, // Initialize on an article
    settings : {} // Advanced settings
});
</script>
<noscript><a href="http://userdeck.com">Customer Support Software</a></noscript>

Note: Make sure to pass in the correct value for your widget key.

The anchor element is only required for SEO support in order for robots to index the content with authority which links back to the widget. If you prefer, you can create an empty div element with the matching id attribute where the widget will be loaded into.

Options

Let's take a look at the list of settings you are able to adjust.

Name	Type	Description
key	string	Required. The guides key associated with your account.
el	mixed	Required. A jQuery selector for the anchor placeholder tag.
layout	string	Changes the layout of the widget. Value can be `'leftnav'` or `'main'`. Default is `'leftnav'`. Note: layouts are just a set of default values for the settings object listed below and may be overridden.
theme	string or boolean `false`	Changes the CSS theme applied to the widget. Value can be `'default'` or `false`. Pass `false` to apply layout styling only. No colors, fonts, etc will be applied.
collection_id	int	Initialize the widget by showing the requested collection as the default page.
category_id	int	Initialize the widget by showing the requested category as the default page. Requires `'collection_id'`.
article_id	int	Initialize the widget by showing the requested article as the default page. Requires `'collection_id'`.
settings	object	See below for a list of advanced settings.

Advanced settings

Below is a list of all advanced settings for the widget. These settings are broken down into pages and their components. Some settings (such as breadcrumbs and sidenav) apply to all pages.

Use the settings object mentioned above to adjust these page/component settings. If there is a dot (.) in the name, that indicates a nested object.

Home

URL: #
Object: settings.home

These are the settings for the home page of the widget.

Name	Type	Description
collectionslist.num	int	Set the number of collections shown on the homepage. Pass `false` to show all collections.
collectionslist.categorieslist.num	int	Set the number of categories shown under a collection. Pass `false` to show all categories.
collectionslist.categorieslist.show_empty	bool	Pass `true` to show categories even if they have no articles in them.
collectionslist.categorieslist.link	bool	Pass `true` to make the entire category element a link.
collectionslist.categorieslist.num_articles	int	Pass `true` to show the number of articles in the category next to the category title.
collectionslist.categorieslist.articleslist.num	int	Set the number of articles shown under each category.

Collections

URL: #collections/{id}
Object: settings.collections

These are the settings for the collections page of the widget.

Name	Type	Description
body	string	Pass `'articleslist'` to show a list of articles on this page. Otherwise the categorieslist will be shown.
categorieslist.num	int	Set the number of categories shown under the current collection. Pass `false` to show all categories.
categorieslist.show_empty	bool	Pass `true` to show categories even if they have no articles in them.
categorieslist.link	bool	Pass `true` to make the entire category element a link.
categorieslist.num_articles	int	Pass `true` to show the number of articles in the category next to the category title.
categorieslist.articleslist.num	int	Set the number of articles shown under each category.
articleslist.num	int	Set the number of articles shown.

Name	Type	Description
articleslist.num	int	Set the number of articles shown.

Articles

URL: #articles/{id}
Object: settings.articles

These are the settings for the articles page of the widget.

Name	Type	Description
articleview.related	bool	Pass `true` to show related articles for the current article.

Breadcrumbs

Object: settings.breadcrumbs

These are the settings for the breadcrumbs shown on all pages of the website.

Name	Type	Description
visible	bool	Pass `true` to show breadcrumbs on all pages.

Sidenav

Object: settings.sidenav

These are the settings for the sidenav shown on all pages of the widget. The sidenav will not be shown on the home page if there is more than one collection.

Name	Type	Description
visible	bool	Pass `true` to show the sidenav.
expand	string	Pass `'active'` to expand and show the articles from the current category. Pass `'none'` to never expand. Pass `'all'` to always expand all categories.