How to install extension

  1. Backup your store's database and web directory.
  2. Login to the SSH console on your server and navigate to the root directory of the Magento 2 store.
  3. Copy installation instructions from page My Downloadable Products to the SSH console and press ENTER.
  4. Run command php -f bin/magento module:enable Mirasvit_Core Mirasvit_Kb to enable the extension.
  5. Run command php -f bin/magento setup:upgrade to install the extension.
  6. Run command php -f bin/magento cache:clean to clean the cache.
  7. Deploy static view files

    rm -rf pub/static/*; rm -rf var/view_preprocessed/*; php -f bin/magento setup:static-content:deploy

Quick Start

Our Knowledge Base extension have quite intuitive interface, so it can be used directly from the box.

However, there's some tips, that can help you to build your information bank.

  1. Start with creating proper Category Tree, that will correspond main topics, that you wish to cover. If you have multiple storeviews, develop separate hierarchy for each of it, and put under corresponding Root Categories.

  2. Create a set of Articles, covering each regular question you have.

  3. Tune up displaying of both categories, and articles on the frontend using Settings, which allows you to flexibly change their appearance.

  4. Keep your information base up-to-date, by regular adding new articles, creating a comfortable information hub for your customers and reducing most of your repetitive questions down to zero.

This should be a good beginning.

Refer to appropriate sections of our manual to have more info.

General Settings

This section describes settings, that allow you to tune up Knowledge Base to your needs. They are located at Content -> Knowledge Base -> Settings, and divided into the following subsections.

General Settings

Option Description
Base URL Sets frontend base URL for the Knowledge Base. For example, if you fill in: knowledge-base, your Base URL will be: http://example.com/knowledge-base.html
Enable Articles Rating If the option is enabled, the customers are able to rate the Knowledge Base articles.
Enable SEO Friendly URLs If the option is enabled, the extension will create SEO-friendly URLs for the categories and articles, based on their URL keys.
For example, if article has URL key mars and its primary category planets, then URL would be http://example.com/knowledge-base/planets/mars.html
Limit of article's links on category view page Allows you to set, how many articles should be displayed per page on Category View.
Hide article's author If this option is enabled, article's author will be hidden at the frontend.
Hide article's date If this option is enabled, article's date will be hidden at the frontend.
Display article amount If this option is enabled, amount of articles in categories, which do not contain other categories, will be displayed
Exclude categories URL-keys from Article URL If this option is enabled, categories URL keys will be skipped in article's final URL. After changing this option it is recommended to regenerate URL's for articles. See more here.

Comments

Option Description
Provider Allow customers to leave comments of articles with selected provider.

There's three possible Provider types:

  • Facebook - allows to post and view comments via Facebook API
  • Disqus - allows to post and view comments via Disqus. This option triggers additional field Disqus Shortname, which is used for communicating with Disqus. More about shortnames can be found here.

Categories

Categories is the basic structure block, which allows you to organize your articles into hierarchical structure for each storeview you use.

Managing Categories

Unlike Articles, Categories are managed from general edit view, divided into two parts:

  • Category Tree (left pane) - displays hierarchical structure of currently defined categories.
  • Category Edit Pane (right pane) - allows to instantly edit selected category.

Category Tree

Category Tree consists of tree itself, and button pane:

  • Add Root Category - adds a zero-level category. Can be used only once per storeview.
  • Add Subcategory - adds a subcategory of lower levels. Read more below.

Category utilizes drag-and-drop functional for moving categories from node to node. Subcategories can be moved in a bundle, e. q. if you move it - all its subnodes will be moved as well.

If you wish to remove node, then select proper node, and only then press Delete button.

Creating a New Category

  1. Go to Content -> Knowledge Base -> Categories.
  2. If you need to add new zero-level category, press Add Root Category.
  3. If you need to add subcategory, press. Add Subcategory.
  4. On right pane fresh edit form will appear, divided into following sections:

    • General - contains basic information. It is the only mandatory, all others sections are optional.
      • Title - title of the category.
      • Is Active - indicates, whether category is enabled and displayed on frontend.
      • Store View - Store Views, where this category and its children should be displayed. Appears only for Root Categories.
      • URL Key - URL key of the category, appears only for Subcategories. If not filled manually, is generated from title.
    • Design & Content - contains only one field - Content - where you can enter short description of current Category. It can be either plain or HTML-rich (with WYSIWYG editor).
    • Meta Information - contains metadata, that will be included to the page and will improve indexing of corresponding frontend page. If similar section in associated Articles is not filled, category Meta Information will be propagated to Article pages as well.
      • Meta Title - meta title of current category.
      • Meta Keywords - meta keywords of articles from the current category. You can enter multiple keywords, separated with a comma.
      • Meta Description - meta description of articles from the current category.
  5. Press Save Category to add category to the tree.

Note

Creating a New Category can be quite tricky for stores with multiple storeviews, because level of subcategory have additional meaning.

Root Category corresponds with particular storeview. So if you have English, French and German storeviews, then proper Category Tree should look like this: Category Tree

Articles

Articles are basic building blocks of your Knowledge Base. Each article contains covering of specific topic or question, and should be associated with one or more categories.

Managing Articles

All articles are located in Content > Knowledge Base > Articles grid.

It also provides two useful mass actions:

  • Delete - allows to remove selected articles.
  • Update URL - allows to re-generate articles URL without re-saving them. It is extremely useful, when experimenting with URL settings and Category Tree.

Note

Depending on Magento's settings, each article URL can have a suffix.

It can be changed or turned off (by setting empty) at Configuration -> Catalog -> Search Engine Optimization -> Product URL Suffix option.

Creating a New Article

  1. Go to Content > Knowledge Base > Articles. Click the button Add New Article to bring up creation edit page. It consists of three tabs:
    • General Information
      • Title - title of the articles.
      • Text - contents of the article. It can contain both regular text and HTML-rich content - you can use for that WYSIWYG-editor, which is switched with Show/Hide Editor. In plain mode you can also insert there widgets, images and special variables.
      • URL Key - URL key of the article. It is used in generating final URL of article.
      • Is Active - indicates, whether article is enabled (e. q. displayed in frontend)
      • Sort Order - numeric value, that allow to create custom articles sorting instead of ID-based - for example, bring up promoted or most important ones.
      • Store View - store views where the article should be displayed. Please, note, that if you opted to show article to some storeview - the same should be set in corresponding Category.
      • Author - author of this article. By default contains staff user name, which initially had created article.
      • Tags - sets one or more comma-separated tags, which can be used for improving search of the article. Instead of Categories, they can provide additional semantic information. A good guide to tagging can be found here.
      • Categories - sets the Knowledge Base category for the article. You can either select one or more categories from Category Tree, or create new one using New Category button.

        Note

        If Article has more than one category, than first of them is a Primary category, and the one, whose URL-key will be used in final URL generation.
    • Meta Information
      • Meta Information tab (allows you to set the Meta tags):
      • Meta Title - allows to set the meta title for the current article.
      • Meta Keywords - allows to set meta keywords for the current article.
      • Meta Description - allows you to set a meta description for the current article.
    • Rating
      • Number of Votes - allows you to set the default number of votes for the article.
      • Rating - allows to set the default value of the article's customer rating.
  2. Save article.

Note

Additionally to properties, described above, each article have a hidden one - Final URL. It is not dynamic, but static - and re-generated on each article save.

Typically it consists of Base URL, set in Settings, Primary Category URL key and Article own key: http://example.com/knowledge-base/planets/venus.html

But if you're wish to use the same Article on different storeview, each of which has it's own Categories Tree - it will result to wrong Final URL, since Primary Category can be only one. In this case we recommend you to turn on option Exclude categories URL-keys from Article URL. Once it enabled, URL's will be generated only from Article URL keys.

After you enable option above, use Update URL mass action from the grid to update all URL in bundle.

How-To

How shall I integrate Knowledge Base with Help Desk MX extension

Integration should be set on Help Desk MX side, with the following steps:

  1. Make sure, that Mirasvit Help Desk and Knowledge Base are both enabled.
  2. Proceed to Customers -> Help Desk MX -> General Settings and set Search Knowledge Base Topics first option to Yes.
  3. Clean all Magento cache and re-generate static content.

After that both Help Desk contact forms and popup will be replaced with simple search form, that will ask for request - and will bring up ticket form only if proposed Knowledge Base topic proved to be invalid (if they were found anyway).

Migration from Magento 1 to Magento 2

Our extension provides you with migration scripts for transferring data from Mirasvit Knowledge Base for Magento 1 to Mirasvit Knowledge Base for Magento 2.

Click on the names of scripts below to download:

How to perform Migration

Follow these steps to correctly perform migration:

  1. Run standard Magento 2 migration, and make sure, that customers and orders were transferred from your M1 store to M2;
  2. Make sure, that Knowledge Base for Magento 2 is installed on your M2 store.
  3. Place mirasvit_kb_m1_export.php to the root of your M1 store, and run it either:
    • From browser by opening URL http://store_m1.com/mirasvit_kb_m1_export.php, or
    • From SSH/Console: navigate to your store's root and run command php -f mirasvit_kb_m1_export.php
  4. If script returned success, file kb_export.xml will be created at the root of the store, with all your data. Transfer it to the root of your M2 store;
  5. Place mirasvit_kb_m2_import.php to the root of your M2 store, and run it either:
    • From browser by opening URL http://store_m1.com/mirasvit_kb_m2_import.php, or
    • From SSH/Console: navigate to your store's root and run command php -f mirasvit_kb_m2_import.php
  6. Check migrated data.
  7. When migration is completed, remove both migration scripts.

Troubleshooting

In some cases import script can crush on timeout or memory overloading error (due to large quantities of data). In this case just restart import script by reloading browser page. It will skip previously uploaded data, and proceed from the last unprocessed record.

How to upgrade the extension

To upgrade the extension follow these steps:

  1. Backup your store's database and web directory.
  2. Login to the SSH console of your server and navigate to the root directory of the Magento 2 store.
  3. Run command composer require mirasvit/module-kb:* --update-with-dependencies to update current extension with all dependencies.

    Note

    In some cases the command above is not applicable, it's not possible to update just current module, or you just need to upgrade all Mirasvit modules in a bundle. In this case command above will have no effect.

    Run instead composer update mirasvit/* command. It will update all Mirasvit modules, installed on your store.

  4. Run command php -f bin/magento setup:upgrade to install the updates.
  5. Run command php -f bin/magento cache:clean to clean the cache.
  6. Deploy static view files

    rm -rf pub/static/*; rm -rf var/view_preprocessed/*; php -f bin/magento setup:static-content:deploy

Disabling the Extension

Temporarily Disable

To temporarily disable the extension please follow these steps:

  1. Login to the SSH console on your server and navigate to the root directory of the Magento 2 store.
  2. Run command php -f bin/magento module:disable Mirasvit_Kb to disable the extension.
  3. Login in to the Magento back-end and refresh the store cache (if enabled).

Extension Removal

To uninstall the extension please follow these steps:

  1. Login to the SSH console on your server and navigate to the root directory of the Magento 2 store.
  2. Run command composer remove mirasvit/module-kb to remove the extension.
  3. Login to the Magento back-end and refresh the store cache (if enabled).

Change Log

1.0.45

(2018-04-03)

Improvements

  • Translation for Article and Category names

1.0.44

(2018-02-22)

Fixed

  • Pager's limit box duplication

1.0.43

(2018-02-15)

Improvements

  • Added event kb_article_after_load for developers.

Fixed

  • Solved possible error if we enable inline translation (message like Warning: sprintf(): Too few arguments in vendor/magento/module-email/Model/Template/Filter.php on line 1031)
  • Styles for category's paging

1.0.42

(2017-11-23)

Improvements

  • Allows to create articles with the same url per store view

1.0.41

(2017-10-19)

Features

  • Allowed to exclude categories keys in article URL

Fixed

  • Variables for category description

1.0.40

(2017-10-04)

Fixed

  • Cron sitemap generation

1.0.39

(2017-09-27)

Fixed

  • Compatibility with 2.2.0
  • Sitemap generation for multi stores

1.0.37

(2017-09-15)

Fixed

  • Sitemap generation for multi stores

1.0.36

(2017-09-04)

Fixed

  • Compatibility with Magento 2.2.0rc
  • Filter articles by customer group

1.0.35

(2017-08-30)

Improvements

  • Added ability to filter articles by customer group
  • Improved category tree displaying

1.0.33

(2017-08-03)

Fixed

  • URLs for sitemap

1.0.32

(2017-07-28)

Improvements

  • Added categories and articles to sitemap

1.0.30

(2017-07-06)

Fixed

  • Fixed wrong parent pickup on Category creation without selecting a parent

1.0.29

(2017-04-06)

Improvements

  • Ability to add additional content to category and change layout (xml)

1.0.28

(2017-03-20)

Improvements

  • Added option that allow to show amount of articles in category that does not contain other categories on category list page

1.0.27

(2017-02-20)

Fixed

  • Fixed redirect after voting on article

1.0.26

(2017-02-07)

Fixed

  • Fixed config does not store for storeview
  • Fixed article view page does not display categories
  • Fixed search does not use tags

1.0.25

(2017-02-03)

Improvements

  • Added filters to admin artilce list page

Fixed

  • Fixed styles for long article's name in sidebar
  • Fixed js error for Single store mode when saving article

1.0.24

(2016-12-23)

Improvements

  • Added ability to hide article's date
  • Moved category view link under the list of categories/articles

1.0.23

(2016-12-08)

Fixed

  • Fixed an issue when "Articles not found for store with multiple root categories"

1.0.22

(2016-11-22)

Fixed

  • Varnish compatibility
  • KB permissions position in role resource tree

1.0.21

(2016-11-08)

Fixed

  • XML errors

1.0.20

(2016-10-19)

Fixed

  • Ability to assign article to storeview

Improvements

  • Support of Magento 2.1.2

1.0.19

(2016-10-17)

Improvements

  • Added ability to assign article to storeview

Fixed

  • WYSIWYG insert variable widget

1.0.18

(2016-10-12)

Improvements

  • Use the same font-awesome.min.css for all extensions

Fixed

  • Added translation (#17)

1.0.17

(2016-09-20)

Fixed

  • Removed unnecessary paging templates

1.0.16

(2016-09-07)

Fixed

  • Latest version of font-awesome

1.0.15

(2016-09-05)

Improvements

  • Update font awesome to the latest version

1.0.14

(2016-08-31)

Improvements

  • Ability to use widgets

1.0.13

(2016-08-23)

Fixed

  • Fixed an issue when settings "Enable Articles Rating" and "Hide article's author" not working properly (#13)

1.0.12

(2016-08-05)

Fixed

  • Fixed an issue when 'kbase' css class is added to the body tag on every page (#11)

1.0.11

(2016-08-02)

Fixed

  • Fix article's category field in edit form for M 2.1.0
  • Fixed an issue when WYSIWYG contains broken images

1.0.10

(2016-07-22)

Improvements

  • Added ability to browse an existing image or upload a new image when editing knowledge base content

1.0.9

(2016-07-14)

Fixed

  • Fixed an issue when WYSIWYG is not showing

1.0.8

(2016-06-27)

Fixed

  • Fixed styles issue with categories sidebar and helpful block

1.0.7

(2016-06-24)

Improvements

  • Support of Magento 2.1.0

1.0.6

(2016-06-14)

Features

  • Ability to use facebook comments.

1.0.5

(2016-05-20)

Fixed

  • Fixed that inactive categories displaying in a list of categories

1.0.2

(2016-05-13)

Fixed

  • Fixed Article 'created at' contains wrong date

1.0.1

(2016-04-11)

Improvements

  • Category Display Mode
  • Styles

Fixed

  • Issue with menu
  • Remove field "Url Key" for root category
  • Fixed an issue with showing disabled categories
  • Fixed an issue with tags