Controlling On Screen Text and Help

From Achievo/ATK Wiki

Jump to: navigation, search

ATK Howto: Controlling On Screen Text and Help

Complexity: Easy
Author: Thom Dyson <TDyson@sybex.com>

List of other Howto's

Contents

Intro

This document will cover the many ways that you can add on-screen text or help files with ATK. The options for on screen text include:

  • Altering default text for tabs and menus.
  • Placing fixed text in a form
  • Creating a node specific help file
  • Creating attribute (or field) specific tool tips.
  • Creating text at the top and/or bottom of a record list.

Several of these may include HTML. When you use HTML you do not need to include <html> or <body> tags. ATK handles that automatically.

This document was written using ATK 5.0.7, but the concepts should work in later versions as well.

Altering Default Text with Language Files

ATK will create default labels for items, based on their internal names. These labels can be changed using language files. There is a global application language file in <application home>/languages. There can also be module specific language files in <application home>/modules/<module name>/languages . Entries in any module specific language file over rides entries in the global language file. Module specific language files are optional, but recommended.

Language files are named xx.lng, where xx is the 2 character abbreviation of the language set in the config.inc.php file. config.inc.php is in the <application home> directory. So, for English, the config.inc.php file has this: 

$config_language="en";

Each language file is named en.lng. In the language file there is one array, in this format: 

  $en=array(
     "tab_address" => "Address",
     "menu_lesson1" => "Lesson 1",
     "employee" => "Employee Name"
  );

To add to the language file, just keep adding entries to the array. Notice the array name is also the two character language code.

ATK groups fields using a tabbed display. Usually all fields are on a single tab, called "default". ATK will create default text to label the tabs based on the information in the node file. Which tab to use is a based on a parameter when the attribute is added to the node. ATK will also create default text for menu options based on the the module.inc.

For example, in a node file, this entry: 

$this->add(new atkAttribute("city",AF_OBLIGATORY), "address");

will display a field, called "City", on a tab labeled, "Tab Address". Notice that the first letter is automatically changed to upper case. You can change the tab label with an entry in the language file like this: 

"tab_address" => "Address"

The "tab_address" is case sensitive. In this example, 

  $en=array(
     "tab_address" => "Address",
     "menu_lesson1" => "Lesson 1",
     "employee" => "Employee Name"
  );

The first line changes the name of a tab. The second line changes a menu label. The last line changes the field name displayed on a form. The format of the key in the array can be just the attribute name. However, it can also include the module and node names, in the form <module name>_<node name>_<attribute name>. So, it can look like this: 

  $en=array(
     "finance_companies_name" => "Company Name" //Finance Module, Companies Node, Name Attrbiute
     "hr_companies_name" => "Company Name" //HR Module, Companies Node, Name Attrbiute
     "employees_name" => "Employee Name" //Employee Node, Name Attrbiute - applies to all modules
  );

Including the module name only makes sense in the global language file. Including the node name is only needed if you have attributes with the same name in different nodes within that module. While you could work from one global language file, we recommend that you create module specific ones. That increases the portablity of a module.

Placing text on a form

To place fixed text in a form, use the atkDummyAttribute in the node file. Before you can use the atkDummyAttribute, you need this line in your node file: 

useattrib("atkdummyattribute");

The atkDummyAttribute takes this form: 

  $this->add(new atkDummyAttribute("status_description",
                                   "Status is calculated automatically.", 
                                   AF_HIDE_LIST));

The "status_description" is the name of the attribute. Every attribute needs a name and that's the one for this attribute. This example explains to the user why there is a field on the form they cannot change. As with all attributes, atkDummyAttribute can take AF_* flags. AF_HIDE_LIST is a common one to keep the text from appearing in record lists. While this example is plain text, you could use HTML to insert things like bold tags, images, custom submit buttons (for custom actions), links and whatever else you need that isn't a database field.

Changing form buttons

If you don't like the default 'save and close' on the bottom of a form of a particular node, add the following entry to your language file: 

'nodename_saveandclose' => 'Send',

This makes the button read 'Send' instead of 'save and close'.

Creating a Node Help File

A help file is simply a text file that holds whatever you want people to know about the node. To create a node's help file, create a file with this naming structure: 

 <application home>/help/<language code>/help.<node name>.inc

<Language code> is, again, the 2 character language code. <node name> is the name of the node, without the module name. So, in an English setup, a node like this 

 <application home>/modules/admin/class.personnel.inc

would use this help file: 

 <application home>/help/en/help.personnel.inc

Help files can hold plain text or HTML, like text tags, links, images. If you use HTML, you should note that the help file handler will add a
for every newline in the text file. This is so that a plain text help file renders "properly". While this makes it easy to add basic text, it can have unexepect results. For example, if you add a table, you will get odd results if you format your raw HTML with new lines between each <TR> or <TD> because ATK will add
at each new line.

In some versions of ATK, the help file link is only displayed in "edit" mode. More recent versions display the link in all display modes.

Creating Attribute Tool Tips

You can create a "tool tip" for each attribute. Each attribute usually maps to a table field. These are attribute specific text entries that show up in a pop up window. When a tool tip is defined, ATK displays a small graphic next to the attribute. That graphic is a link to the pop up window with the text.

Tool tip text is defined in the language file(s). It can be in either the core application language file or the module specific file. It is an element in the language array, with this format: 

"<node name>_<attribute name>_tooltip" => "Tool tip text here"

So, the "last name" attribute in the personnel node of the admin module, would have an entry like this: 

  $en=array(
     ...,
     "personnel_last_name_tooltip" => "Enter the family name in this field",
     ...
  );

Tool tips cannot contain any HTML.

Creating text at the top and/or bottom of a record list

To create text that shows at the top or bottom of a record list, define the adminHeader or adminFooter hooks in the node file. You might use this text to describe the filter on a record set. For example: 

  public function adminHeader()
  {
      return "This list includes only current employees";
  }
  
  public function adminFooter()
  {
      return "This is the bottom of the page";
  }

To include the link to the node's help file, use this code: 

  public function adminFooter()
  {
      $helpLink = $this->GetHelp();
      return "This is the bottom of the page. " . $helpLink['helplink'] ;
  }
Retrieved from "http://www.atk-framework.com/wiki/Controlling_On_Screen_Text_and_Help"
Personal tools
Navigation