Adding page-wise module documentation in PrestaShop 1.7

In this blog, we are going to learn how to add back-office page documentation in modules like Prestashop native page documentation.

In Prestashop native pages, there is a Help block on the header which shows page-related documentation. For this purpose, Prestashop uses its own server help.prestashop.com, but we cannot get our page’s documentation from this server so we’ll use our own server to get documentation response.

Suppose, we have the server https://store.webkul.com which will return documentation response as per the requested page.

1- Server side code to handle the request

We are handling requests from another server https://store.webkul.com. This server also has Prestashop and a module named wkdocdataprovider to handle requests. You can create this module with another name.

Let’s write a script to handle the request :

Create a javascript file named mod_help.js like the below code

$(() => {
    $('.btn-help').addClass('wk-btn-help');
    $('.wk-btn-help').removeClass('btn-help')
    let storage = false;
    if (typeof (getStorageAvailable) !== 'undefined') {
        storage = getStorageAvailable();
    }
    window.initHelp = function () {
        $('#main').addClass('helpOpen');
        if ($('#help-container').length === 0) {
            $('#main').after('<div id="help-container"></div>');
        }
        pushContent(help_class_name);
    };
    $('.toolbarBox a.wk-btn-help').on('click', (e) => {
        e.preventDefault();
        if (!$('#main').hasClass('helpOpen') && document.body.clientWidth > 1200) {
            if (storage) storage.setItem('helpOpen', true);
            window.initHelp();
        } else {
            $('#main').removeClass('helpOpen');
            $('#help-container').html('');
            if (storage) storage.setItem('helpOpen', false);
        }
    });
    if (storage && storage.getItem('helpOpen') === 'true') {
        $('a.wk-btn-help').trigger('click');
    }
    function getHelpDoc(pageController) {
        $.ajax({
            url: 'https://store.webkul.com/module/wkdocdataprovider/apidoc',
            type: "post",
            async: true,
            dataType: "json",
            data: {
                ajax: true,
                page: `${pageController}`,
                mod_name: wk_mod_name
            },

            success(data) {
                if (window.isCleanHtml(data)) {
                    $('#help-container').html(data.page_content);
                }
            },
        });
    }
    function pushContent(target) {
        $('#help-container').removeClass('openHelpNav');
        $('#help-container').html('');
        getHelpDoc(target);
    }
});

Create a front controller apidoc.php like the below code

class WkDocDataProviderApiDocModuleFrontController extends ModuleFrontController
{
    public function init()
    {
        header('Access-Control-Allow-Origin: *');
        parent::init();
        $this->display_header = false;
        $this->display_footer = false;
    }

    public function initContent()
    {
        $page = Tools::getValue('page');
        $moduleName = Tools::getValue('mod_name');
        if ($moduleName == 'wkrma') {
            switch ($page) {
                case "AdminRmaDefaultSetting":
                    $pageData = '<div class="page-wrap">
                            <header class="main-header bar bar-nav"></header>
                            <div class="content">
                                <section class="article">
                                    <h1 id="help_userguide-AdminRmaDefaultSetting">RMA Module User Guide</h1>
                                    <p>Lorem ipsum, or lipsum as it is sometimes known, is dummy text used in laying out print, graphic or web designs. The passage is attributed to an unknown</p>
                                </section>
                            </div>
                        </div>';
                    break;
                case "AdminRmaStatus":
                    $pageData = '<div class="page-wrap">
                        <header class="main-header bar bar-nav"></header>
                        <div class="content">
                            <section class="article">
                                <h1 id="help_userguide-AdminRmaDefaultSetting">RMA Module User Guide</h1>
                                <p>Lorem ipsum, or lipsum as it is sometimes known, is dummy text used in laying out print, graphic or web designs. The passage is attributed to an unknown</p>
                            </section>
                        </div>
                    </div>';
                    break;
                default:
                    $pageData = '<a href="https://webkul.com/blog/prestashop-rma/">';
                }
            die(Tools::jsonEncode(array('page_content' => $pageData)));
        }
    }
}

The above two files will handle requests. You can also use API for data.

2- Add documentation block in module:

In the first point, we have shown you the script of another server, which will handle requests and return responses.

Suppose, we have a module RMA and we want to show documentation help block on AdminRmaDefaultSettingController page. The controller name may be different in your case, it’s just an example.

Add the below code in AdminRmaDefaultSettingController.php. The initPageHeaderToolbar function will add documentation if javascript is disabled.

 public function initPageHeaderToolbar()
 {
    parent::initPageHeaderToolbar();
    $this->context->smarty->assign('help_link', 'https://store.webkul.com/en/module/wkdocdataprovider/apidoc?page='.Tools::getValue('controller') . '&mod_name=' . $this->module->name);
 }

Add assets files in setMedia() function that is created on another server (shown to you in the first step)

public function setMedia($isNewTheme = false)
{
   parent::setMedia($isNewTheme);
   Media::addJsDef(array('wk_mod_name' => $this->module->name));
        $this->addJS('https://store.webkul.com/modules/wkdocdataprovider/views/js/mod_help.js');
        $this->addCSS('https://help.prestashop.com/css/help.css');
}

Unset Prestashop help.js script to avoid multiple responses.

   public function addJS($js_uri, $check_path = true)
   {
       if ($js_uri == __PS_BASE_URI__ . $this->admin_webpath . '/themes/' . $this->bo_theme . '/js/help.js') {
            return true;
        }
        parent::addJS($js_uri, $check_path);
  }

Now, when we click on the help block, it will show module documentation related to the page.