<section>
|
<h1 class="blue" data-id="#custom/onpage-help"><i class="ace-icon fa fa-desktop grey"></i> Onpage Help</h1>
|
|
|
<div class="alert alert-info">
|
<button class="close" data-dismiss="alert"><i class="ace-icon fa fa-times"></i></button>
|
<i class="ace-icon fa fa-exclamation-triangle"></i>
|
Please use the following info and demo's example to use Onpage Help in your own app.
|
<br />
|
It still may be confusing though, so if you need further help with that, just get in touch with me.
|
</div>
|
|
<div class="hr hr-double hr32"></div>
|
|
<!-- #section:custom/onpage-help -->
|
<div class="help-content">
|
<h3 class="info-title smaller">1. Overview</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
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.
|
<br />
|
For an example of this you can refer to
|
<a href="../html/index.html#help">Ace demo</a>
|
and click the black button on right of page.
|
</li>
|
|
<li>
|
You can also use this feature in your app to provide help and instructions for users.
|
</li>
|
</ul>
|
</div>
|
|
|
<h3 class="info-title smaller">2. Usage</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
Help content can be retrieved from your own help files and it will be displayed inside a modal box in your
|
application.
|
</li>
|
|
<li>
|
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
|
<code>assets/js/ace/elements.onpage-help.js</code> file.
|
</li>
|
|
<li>
|
To initiate help you can call:
|
<pre data-language="javascript">
|
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()
|
})
|
})
|
</pre>
|
</li>
|
|
<li>
|
Your application page should have special comments for special sections that have help material:
|
<pre data-language="html">
|
<!-- #section:manage/user -->
|
Some elements are here which will show a help dialog when clicked!
|
<!-- /section:manage/user -->
|
</pre>
|
</li>
|
|
<li>
|
The help content is retrieved dynamically from a remote file that you specify.
|
<br />
|
That file should have similar comments like above:
|
<pre data-language="html">
|
<!-- #section:manage/user -->
|
Documentation and help content for "manage/user" are here inside some file.
|
<!-- /section:manage/user -->
|
</pre>
|
<br />
|
There should also be an element with <code>data-id="#manage/user"</code> attribute
|
which is used to specify modal box's title.
|
<br />
|
If no such element exists, its possible parent is looked up and if available its title is used for the modal box!
|
</li>
|
|
<li>
|
If inside one documentation(help) page, there are several sections to be displayed in your application,
|
you should use "."(dot) character to separate them:
|
<pre data-language="html">
|
<!-- #section:manage/user.edit -->
|
Manage user documentation is here
|
<!-- /section:manage/user.edit -->
|
..
|
..
|
..
|
<!-- #section:manage/user.delete -->
|
Delete user documentation is here
|
<!-- /section:manage/user.delete -->
|
</pre>
|
</li>
|
|
<li>
|
Same is true for your application page:
|
<pre data-language="html">
|
<!-- #section:manage/user.edit -->
|
<a href="#">Edit</a><!-- will display help dialog -->
|
<!-- /section:manage/user.edit -->
|
..
|
..
|
..
|
<!-- #section:manage/user.delete -->
|
<a href="#">Delete</a><!-- will display help dialog -->
|
<!-- /section:manage/user.delete -->
|
</pre>
|
</li>
|
|
<li>
|
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.
|
<br />
|
Please see next section for more info.
|
</li>
|
|
<li>
|
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>code</code> tag with <code>.open-file</code> class
|
and <code>data-open-file="css"</code> attribute:
|
<pre data-language="html">
|
<code class="open-file" data-open-file="js">path/to/some/file.js</code>
|
</pre>
|
</li>
|
|
</ul>
|
</div>
|
|
|
<h3 class="info-title smaller">3. Options</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
There are several options when initiating help.
|
</li>
|
<li><code>icon_1</code> Optional icon displayed inside a help section.
|
Default is 'fa fa-question'
|
<br />
|
<span class="thumbnail inline">
|
<img src="images/help-icon1.png" />
|
</span>
|
</li>
|
<li><code>icon_2</code> Optional icon displayed on top left of a help section.
|
Default is 'fa fa-lightbulb-o'
|
<br />
|
<span class="thumbnail inline">
|
<img src="images/help-icon2.png" />
|
</span>
|
</li>
|
<li><code>include_all</code>
|
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):
|
<br />
|
<span class="thumbnail inline">
|
<img src="images/help-include-all.png" />
|
</span>
|
</li>
|
|
<li><code>base</code> Optional path to documentation folder which you can use later in following callbacks to return content url.</li>
|
<li><code>section_url</code> Callback function which return a url to load the help content of a section.
|
<br />
|
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:
|
<pre data-language="javascript">
|
'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;
|
}
|
</pre>
|
</li>
|
<li><code>file_url</code> Similar to above callback. This function is used when a file (which contains code snippets) is to be loaded.</li>
|
<li><code>img_url</code> Similar to above callbacks. When inserting images into DOM, the url may need to be updated.</li>
|
|
<li><code>code_highlight</code> Used for syntax highlighting code snippets.
|
<br />
|
Currently if Rainbow.js or Prism.js libraries are available, they will be used for highlighting.
|
</li>
|
|
|
<li><code>before_enable</code> Optional callback to make some changes before help is enabled.
|
<br />
|
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.
|
</li>
|
<li><code>after_enable</code> Optional callback to make some changes after help is enabled</li>
|
<li><code>before_disable</code> Optional callback to make some changes before help is disabled</li>
|
<li><code>after_disable</code> Optional callback to make some changes after help is disabled.
|
<br />
|
For example in Ace's demo, we restore fixed state of previously unfixed navbar, etc.
|
</li>
|
|
<li><code>add_panels</code> Separate & wrap help content inside panels like image below.
|
Default is true.
|
<br />
|
<span class="thumbnail">
|
<img src="images/help-panels.png" />
|
</span>
|
</li>
|
<li><code>panel_content_selector</code> Use this selector to find and separate contents and wrap them inside panels</li>
|
<li><code>panel_content_title</code> Use this selector to find the title for each panel. Should come before relevant 'panel_content_selector'</li>
|
</ul>
|
</div>
|
|
|
<h3 class="info-title smaller">4. Example</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
For an example of using Onpage Help in your application, you can see
|
<a href="../html/index.html#help">Ace's demo pages</a>
|
</li>
|
|
<li>
|
The code that initiates help is inside
|
<code>assets/js/ace/ace.onpage-help.js</code>
|
and has comments and explanations.
|
</li>
|
|
<li>
|
For Ace's demo there is also an extra style file which is
|
<code>assets/css/ace.onpage-help.css</code>.
|
<br />
|
It is used for styling the black help button and you don't need it.
|
</li>
|
|
<li>
|
Also, "Rainbow.js" files are include for syntax highlighting.
|
<br />
|
You don't need them if your help content doesn't make use of it.
|
</li>
|
|
<li>
|
The help content is retrieved from <code>docs/sections</code> folder.
|
</li>
|
|
<li>
|
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.
|
<br />
|
You should use your own approach.
|
<br />
|
Perhaps a button inside navbar or sidebar which enables or disables help.
|
</li>
|
</ul>
|
</div>
|
|
|
</div>
|
<!-- /section:custom/onpage-help -->
|
|
</section>
|
