plainblack.com
Username Password
search
Bookmark and Share

Help

In addition to internationalization, WebGUI also provides an online help system for template variables, asset configuration, or anything else. This is done with an i18n-like module in the lib/WebGUI/Help folder (with the same name as your i18n namespace).

 

package WebGUI::Help::Asset_InfoCard;

use strict;

our $HELP = {

'howToUse' => {

title => 'help howToUse title',

body => 'help howToUse body',

},

};

1; # I can handle the truth

 

This help file seems a little abstract, there's no help to be found! What you do have, however, are keys to the i18n file so that Help can be internationalized as well.

 

First, set up your package to have the same name under WebGUI::Help as your i18n has under WebGUI::i18n::English. Then, make your $HELP structure, whose keys are references to the article. Inside the article reference, specify a title and body. The values of these two keys point to entries in the i18n file. This is all that is required to have a very basic help article. Once you add your keys to your i18n file, you can visit WebGUI's Help pane in the Admin Console and see your new article listed.

 

Template Variables

There are some help topics that are so common you have better ways to make help files for them. One of these topics is Template Variables.

 

By using the “variables” key in your article definition, you can specify a list of template variables available to a template, like so:

 

'templateIdView' => {

title => 'help templateIdView title',

body => 'help templateIdView body',

variables => [

{

name => 'name',

description => 'helpvar name',

required => 0,

},

{

name => 'address',

description => 'helpvar address',

},

],

},

 

Here, a new help article is defined, templateIdView. You have the normal title and body keys, but you also have a new key: variables.

 

“variables” is an array reference of hash references that define each of the template variables available at that scope. For the InfoCard asset, you have at least two variables available “name” and “address”. The “name” key is the exact name of the template variable, what the template designer would use inside the <tmpl_var> tag. The “description” key is another i18n key for a description of the variable. Finally, the optional “required” key can be set to true if the variable absolutely must be inside the template for the asset to work.

 

If the variable is a loop, it can contain a second level of “variables”, like so:

 

{

name => “card_loop”,

description => 'helpvar card_loop',

variables => [

{

name => 'card',

description => 'helpvar card',

},

],

},

 

These variables will show up with an extra level of indentation, to show they are available from inside the loop “card_loop.”

 

Related and ISA

A lot of assets are related to each other in some way. At the very least, they all inherit from the same base class, so share a portion of the same template variables. You can define these relationships in two ways: “related” and “isa”.

 

“isa” defines a standard parent-child relationship. By saying an article “isa” another article, you inherit all those template variables, and don't have to redefine them in your own article.

 

'templateIdView' => {

title => 'help templateIdView title',

body => 'help templateIdView body',

isa => [

{

namespace => 'Asset',

tag => 'asset template asset variables',

},

],

# variables

},

 

“isa” is an array reference of hash references, much like “variables.” Inside the hash reference is the “namespace” of the parent article, and the “tag” of the parent article, which is to say the key in the $HELP hashref. So, given the above isa, you could look in lib/WebGUI/Help/Asset.pm to find the “asset template asset variables” article that you're inheriting from.

 

“related” simply defines a relationship between two articles and provides a link to the related article. It's defined in the same way as “isa”, an array reference of hash references.

 

'templateIdView' => {

title => 'help templateIdView title',

body => 'help templateIdView body',

related => [

{

namespace => 'Asset',

tag => 'asset template asset variables',

},

],

# variables

},

 

Now, the “asset template asset variables” article in the “Asset” namespace will show up under the “Related” section.

 

Keywords: asset configuration template variables

Search | Most Popular | Recent Changes | Wiki Home
© 2018 Plain Black Corporation | All Rights Reserved