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.

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.

NameTypeDescription
keystringRequired. The guides key associated with your account.
elmixedRequired. A jQuery selector for the anchor placeholder tag.
layoutstringChanges 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.
themestring or boolean falseChanges 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_idintInitialize the widget by showing the requested collection as the default page.
category_idintInitialize the widget by showing the requested category as the default page. Requires 'collection_id'.
article_idintInitialize the widget by showing the requested article as the default page. Requires 'collection_id'.
settingsobjectSee 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.

NameTypeDescription
collectionslist.numintSet the number of collections shown on the homepage. Pass false to show all collections.
collectionslist.categorieslist.numintSet the number of categories shown under a collection. Pass false to show all categories.
collectionslist.categorieslist.show_emptyboolPass true to show categories even if they have no articles in them.
collectionslist.categorieslist.linkboolPass true to make the entire category element a link.
collectionslist.categorieslist.num_articlesintPass true to show the number of articles in the category next to the category title.
collectionslist.categorieslist.articleslist.numintSet 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.

NameTypeDescription
bodystringPass 'articleslist' to show a list of articles on this page. Otherwise the categorieslist will be shown.
categorieslist.numintSet the number of categories shown under the current collection. Pass false to show all categories.
categorieslist.show_emptyboolPass true to show categories even if they have no articles in them.
categorieslist.linkboolPass true to make the entire category element a link.
categorieslist.num_articlesintPass true to show the number of articles in the category next to the category title.
categorieslist.articleslist.numintSet the number of articles shown under each category.
articleslist.numintSet the number of articles shown.

Categories

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

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

NameTypeDescription
articleslist.numintSet the number of articles shown.

Articles

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

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

NameTypeDescription
articleview.relatedboolPass 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.

NameTypeDescription
visibleboolPass 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.

NameTypeDescription
visibleboolPass true to show the sidenav.
expandstringPass 'active' to expand and show the articles from the current category.
Pass 'none' to never expand.
Pass 'all' to always expand all categories.
Was this article helpful?