TYPO3 Editor Documentation at your fingertips

You know the challenge to provide current and well written editor documentation, don’t you? Probably you are tired in writing MS Word documents, converting them to pdf, sending them around via e-mail and knowing, at the same time, that nobody will read it. In this post I will show you a solution with which the editors will have it right at their fingertips, when working in the TYPO3 backend.

The solution is simply described in one sentence: It’s a backend module which resides in the section „Help“ and loads a part of the page tree within an iframe in the backend, styling of the website included. This approach has the advantage that the documentation

  • has a nice layout
  • is easy to read
  • is accessible where the editor works
  • can be updated at any time without any distribution efforts
  • can use all the power the TYPO3 installation has (incl. extensions)

It will be also a good location for spreading editor and TYPO3 related news, especially if it is used as the module, which is instantly loaded after the backend login.

If you are in doubt whether this tutorial is something for you, because you are an integrator with basic php knowledge.  Trust me, using this tutorial you do not need much (any?) php knowledge.

So … these few following steps are necessary. You do not have to type all steps manually. At the end of the post is a zip file which contains all necessary files and folders.

1) Create a basic extension folder tree

Usually you will do it using the EXT:extension_builder, but in this case the creation of some folders and files is sufficient. The extension_builder would be overkill.
You do this by creating the following folder tree beneath „/typo3conf/ext”

If you are already using a template layout extension, this structure will be already there. You can use this, but you have to replace several strings later. In most cases it will be the extension key.

2) Create extension manager configuration file

The first file is „ext_emconf.php“ in the root folder of the extension. You must replace all strings in “<>” with your custom values

The second file, you must add, is a gif file named „ext_icon.gif“, which resides on the same level and is the icon which will be displayed in the extension manager and in the module menu.

At this point you can already go to the extension manager (EM) and activate the extension.

3) Add the extension configuration file

Create an empty file „ext_conf_template.txt“ at the root level of the extension and add the following lines:

This enables another icon in the EM, where you can set the pid where the documentation will reside. If you have this extension in the version control system and you want to deploy it, you can set the pid already in the code. But you can overwrite it in the TYPO3 backend via the EM later at any time.

typo3worx_beuser-docs-01_activate-extension-configuration

4) Create the controller for the module

To achieve this you need to create a the file „HelpController.php“ in the folder „customer_docs/Classes/Controller“. You must replace “MyNameSpace” with the name of your namespace. A good possibility is using a combination of your first- and lastname. In my case it would be “MarcusSchwemer”.

The controller takes the configuration as an argument an passes it on to the template, which will be created in the next step.

5) Create the template for the backend module

The template for the backend module is a simple „Index.html“ file which resides in „/Resources/Private/Templates/Help/„. The content of the file are the following three lines:

6) Create TypoScript Files for the module

As with frontend extensions you need to add two TypoScript files for the module: “constants.txt” and “setup.txt”

constants.txt

setup.txt

Further settings or adjustments in these files are not necessary.

7) Add language files

For a proper display of the module labels language files in xlf format are required. Create a file “typo3conf/ext/customerdocs/Resources/Private/Language/locallang_customerdocs.xlf“ and add the following content.

If you want to add another language, just create another file in the same directory with a prefix for the language followed by a dot. For example „de.locallang_customerdocs.xlf“ for german.

8) Register the TYPO3 backend module

Now it is time to register the backend module and make TYPO3 display the module in the help section. This is done in the file „ext_tables.php“, which is also located in the root folder of the extension. Please create the file and add these lines. Please change the string “MyVendorName” to something individual.

9) Enable the module for BE users

The last technical step to enable the module for the editors and to provide the database mount. This should be done in a separate group, which can be added to any other group or user.

typo3worx_be-group-for-docs_01

 

typo3worx_be-group-for-docs_02

10) Create user documentation

Creating the module was really easy … nine reproducible steps. But now the comes the hard part … Creating the editor documentation. I know, this is not a task everybody likes. But see it like this: Using this kind of editor documentation is also some kind of quality assurance. If you provide a step by step instructions and templates of content elements, which users can copy, paste and modify, you prove yourself (and the customer) that your work works.

Maybe it’s the best if you start with this module and add documentation step by step, when a feature is ready to. So it is not “the big documentation“ task at the end.

I wish you now happy coding and documentation sessions!

Finally here is the download link to the EXT:customerdocs

1 Comments

Leave a Comment.