Onpage Help

Please use the following info and demo's example to use Onpage Help in your own app.
It still may be confusing though, so if you need further help with that, just get in touch with me.

1. Overview

Onpage Help is a feature of Ace admin template that allows users to select an element or a section of a page and see more info about it without leaving the page.
For an example of this you can refer to Ace demo and click the black button on right of page.
You can also use this feature in your app to provide help and instructions for users.

2. Usage

Help content can be retrieved from your own help files and it will be displayed inside a modal box in your application.
To use onpage help you should build a custom Javascript file using JS builder tool and include onpage help feature or you can directly include assets/js/ace/elements.onpage-help.js file.

To initiate help you can call:

jQuery(function($) {
  var help = new Onpage_Help({/* for available options, see below */});
  $('#some-button').on('click', function() {
	help.toggle();
	//or help.enable()
	//or help.disable()
  })
})

Your application page should have special comments for special sections that have help material:
```
 
  Some elements are here which will show a help dialog when clicked!
 
```
The help content is retrieved dynamically from a remote file that you specify.
That file should have similar comments like above:
```
 
  Documentation and help content for "manage/user" are here inside some file.
 
```
There should also be an element with data-id="#manage/user" attribute which is used to specify modal box's title.
If no such element exists, its possible parent is looked up and if available its title is used for the modal box!
If inside one documentation(help) page, there are several sections to be displayed in your application, you should use "."(dot) character to separate them:
```
 
  Manage user documentation is here
 
..
..
..
 
  Delete user documentation is here
 
```
Same is true for your application page:
```
 
  Edit
 
..
..
..
 
   Delete
 
```
When user clicks on a help section to see its content, the name of section is passed to "section_url" function in which you should return the url which contains relevant help material.
Please see next section for more info.
If you have files with HTML, CSS, etc code that you want to show inside the modal help dialog, you can wrap the path inside a code tag with .open-file class and data-open-file="css" attribute:
```
 path/to/some/file.js
```

3. Options

There are several options when initiating help.
icon_1 Optional icon displayed inside a help section. Default is 'fa fa-question'
icon_2 Optional icon displayed on top left of a help section. Default is 'fa fa-lightbulb-o'
include_all Include all elements between two comments or just the first and last one(might be slightly faster in some cases). Default is true (include all):
base Optional path to documentation folder which you can use later in following callbacks to return content url.

section_url Callback function which return a url to load the help content of a section.
For example when a help section which refers to "basics/sidebar.compact" is requested, you can use this function to return the url to load which contains help content:

'section_url': function(section_name) {
	//From Ace Demo's example
   
    //according to a section_name such as `basics/navbar.toggle` return the file url which contains help content
    section_name = section_name || '';

    //for example convert section_name=`basic/navbar.layout.brand` to `basic/navbar`
    //because in Ace's documentation files 'basic/navbar.layout.brand' section is inside `basic/navbar.html` file
    var url = section_name.replace(/\..*$/g, '');

    var parts = url.split('/');
    if(parts.length == 1) {
        //for example convert `changes` to `changes/index.html`
        if(url.length == 0) url = 'intro';//or convert `empty string` to `intro/index.html`
        url = url + '/index.html';
    }
    else if(parts.length > 1) {
        //for example convert `basics/navbar.layout` to `basics/navbar.html`
        url = url + '.html';
    }
    return this.settings.base + '/docs/sections/' + url;
}

file_url Similar to above callback. This function is used when a file (which contains code snippets) is to be loaded.
img_url Similar to above callbacks. When inserting images into DOM, the url may need to be updated.
code_highlight Used for syntax highlighting code snippets.
Currently if Rainbow.js or Prism.js libraries are available, they will be used for highlighting.
before_enable Optional callback to make some changes before help is enabled.
For example in Ace's demo, when help is enabled, we unfix navbar, sidebar, etc, because when an element is fixed or is inside a fixed parent, it will need a fixed help box above it and it becomes unnecessarily complex.
after_enable Optional callback to make some changes after help is enabled
before_disable Optional callback to make some changes before help is disabled
after_disable Optional callback to make some changes after help is disabled.
For example in Ace's demo, we restore fixed state of previously unfixed navbar, etc.
add_panels Separate & wrap help content inside panels like image below. Default is true.
panel_content_selector Use this selector to find and separate contents and wrap them inside panels
panel_content_title Use this selector to find the title for each panel. Should come before relevant 'panel_content_selector'

4. Example

For an example of using Onpage Help in your application, you can see Ace's demo pages
The code that initiates help is inside assets/js/ace/ace.onpage-help.js and has comments and explanations.
For Ace's demo there is also an extra style file which is assets/css/ace.onpage-help.css.
It is used for styling the black help button and you don't need it.
Also, "Rainbow.js" files are include for syntax highlighting.
You don't need them if your help content doesn't make use of it.
The help content is retrieved from docs/sections folder.
Inside Ace's demo, help is initiated when "#help" is appended to url and a black button on right side of page is shown which enables/disables help.
You should use your own approach.
Perhaps a button inside navbar or sidebar which enables or disables help.