stmllr.net

How to add context sensitive help (CSH) items to TYPO3 extension modules

by on stmllr.net

Software documentation is often rare and developers are lazy, when writing manuals instead of code. TYPO3 comes with a built-in help system which can easily be used to explain items directly in the backend. Dear lazy coder, let's have a look at it!

I guess CSH is one of the most obvious but yet overseen feature of the backend. That's no surprise given the large quantity of icons. But the backend has been cleaned up very much with the release of 4.2. So there's no more excuse to omit CSH in your extension. I recently added CSH to the Developer's Log extension and would like to demonstrate some of the main techniques to add CSH to a BE module.

All you need to have is:

  1. the content itself, put into a classic locallang file called locallang_csh_txYOUREXTKEY.xml
  2. the item, placed in mod/index.php
  3. a reference to tell the extension manager about the locallang file

Let's start with the first one. I prepared a skeleton file, which explains the most significant fields: 

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<T3locallang>
   <meta type="array">
      <description>CSH contents of myextkey module</description>
      <type>CSH</type>
      <csh_table>_MOD_tools_txmyextkeyM1</csh_table>
      <fileId>EXT:myextkey/locallang_csh_txmyextkey.xml</fileId>
      <labelContext type="array"></labelContext>
   </meta>
   <data type="array">
      <languageKey index="default" type="array">
         <label index=".alttitle">Module title</label>
         <label index=".description">
            This part describes the module and is also shown
            when hovering over the CSH icon [hover]
         </label>
         <label index=".syntax">
            This part is a predefined section and
            can be used to demonstrate coding syntax.
         </label>
         <label index="mod_itemname.alttitle">Item title</label>
         <label index="mod_itemname.description">
            This part describes a certain item [hover]
         </label>
         <label index="mod_itemname.details">
            This part gives more details of the item
         </label>
         <label index="mod_itemname.image">
           EXT:myextkey/res/imagefile.png
         </label>
      </languageKey>
   </data>
</T3locallang>

Next, add a CSH item to the content of the module. Of course you can have more than one item: 

$content .= t3lib_BEfunc::cshItem(
   '_MOD_'.$GLOBALS['MCONF']['name'],
   'mod_'.$str,
   $GLOBALS['BACK_PATH'],
   '|',
   FALSE,
   'margin-bottom:0px;'
);

The function cshItem() is well documented inside the source code. I was lazy and simply copied the descriptions from the sources: 

string   Table name ('_MOD_'+module name)
string   Field name (CSH locallang main key)
string   Back path
string   Wrap code for icon-mode, splitted by "|".
         Not used for full-text mode.
boolean  If set, the full text will never be shown (only icon).
         Useful for places where it will break the page
         if the table with full text is shown.
string   Additional style-attribute content
         for wrapping table (full text mode only)

Finally add a reference to ext_tables.php to tell the extension manager about the CSH: 

t3lib_extMgm::addLLrefForTCAdescr(
   '_MOD_tools_txmyextkeyM1',
   'EXT:myextkey/locallang_csh_txmyextkey.xml'
);

That's all you need to do for a backend module. You can find out more about CSH in the Inside TYPO3 documentation.

Tags