Advanced widget integration

Open full view...

Categories: Installing Guides

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

Performing an advanced installation

To get started, copy this modified installation code into your page.

<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: This is similar to the basic installation except that the data-userdeck-guides attribute is not present. Removing this prevents the javascript from auto-dispatching your guides instance on page load.

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

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.

Categories

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

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

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.