EXT: Name of your Extension

Author:Christopher
Created:2010-12-18T19:57:23
Changed:2012-03-22T16:59:05.450000000
Classification:extension key
Description:The keywords help with categorizing and tagging of the manuals. You can combine two or more keywords and add additional keywords yourself. Please use at least one keyword from both lists. If your manual is NOT in english, see next tab "language" ---- forEditors (use this for editors / german "Redakteure") forAdmins (use this for Administrators) forDevelopers (use this for Developers) forBeginners (manuals covering TYPO3 basics) forIntermediates (manuals going into more depth) forAdvanced (covering the most advanced TYPO3 topics) ----
Keywords:keywords comma-separated
Author:Documentation Team
Email:documentation@typo3.org
Language:en

img-1 img-2 EXT: Name of your Extension

Extension Key: extension key

Language: en

Version: x.y.z

Keywords: keywords comma-separated

Copyright 2006-2012, Author Name, <your@email.com>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.org

Table of Contents

`EXT: Name of your Extension 1 <#__RefHeading__5708_1738894311>`_

`Introduction 3 <#__RefHeading__5710_1738894311>`_

What does it do? 3

Screenshots 3

`Users manual 4 <#__RefHeading__467_413120346>`_

Subheading 4

FAQ 4

`Administration 5 <#__RefHeading__31511_818911409>`_

FAQ 5

`Configuration 6 <#__RefHeading__31515_818911409>`_

FAQ 6

Reference 6

`Tutorial 8 <#__RefHeading__31523_818911409>`_

`Known problems 9 <#__RefHeading__31525_818911409>`_

`To-Do list 10 <#__RefHeading__477_413120346>`_

`ChangeLog 11 <#__RefHeading__31623_818911409>`_

`Important guidelines 12 <#__RefHeading__31625_818911409>`_

Inserting images 12

Fonts 12

Paragraph styles 12

Character styles 13

Linking 13

Meta data and updates 13

HowTo: Update a manual to the new layout 13

HowTo: Alternative updating possibility: Import the styles from another document 14

HowTo: Fix the Table Of Contents when it is empty 15

HowTo: Fix the Table Of Contents when a chapter is missing 15

Help from documentation.openoffice.org 15

Introduction

What does it do?

Overview. What does it do? What problem is solved? Who is interested in this? Brief technical insight. Basically everything people need to know to decide, if they should go on with this extension.

Information on this template file

To get an overview about the formatting templates, which you can use in this template, hit F11. In the box, which will open, you will see the different styles.

Before you upload an extension to TER, you should do the following:

  • Check that there is no empty line between a header and a paragraph.
  • Change special paragraph styles to standard (with "Clear formatting").
  • Update the Table of Contents with a right click (when you hover over the TOC-items you see the numbering).

Screenshots

Here you see what the extension does:

img-3 Screenshots are very much welcome for a visual impression.

Target group: Mostly Developers and administrators, but should be a non-technical and visual presentation.

This section is required and in some cases it basically tells it all.

Users manual

Documentation of how to use the extension, how it works, how to apply it if it's a website plugin. A user manual.

Language should be non-technical, explaining, using small examples.

Examples: For the "News" plugin this would be a manual showing how to create the news-items, explaining the options etc.

Target group: Users, Administrators or Developers in that priority. Depends on the extension.

Subheading

That is a new section holding some content.

It can also include an

Example

To make settings for a content element of the type TEXT, you can use the following TypoScript code in the setup field of your template:

page.20.marks {
  HEADER = TEXT
  HEADER.field = title
  ...
}

And some more text, which can also use lists:

  • Line 1
  • Line 2
  • Line 3

FAQ

Possible subsection: FAQ

Administration

Describes how to manage the extension from an administrator’s point of view. That relates to Page/User TSconfig, permissions, configuration etc., which administrator level users have access to.

Language should be non/semi-technical, explaining, using small examples.

Target group: Administrators

FAQ

Possible subsection: FAQ

Configuration

Technical information: Installation, Reference of TypoScript options, configuration options on system level, how to extend it, the technical details, how to debug it and so on.

Language should be technical, assuming developer knowledge of TYPO3. Small examples/visuals are always encouraged.

Target group: Developers

FAQ

Possible subsection: FAQ

Reference

Possible subsections: Reference of TypoScript options.

allWrap /+stdWrap

Property

allWrap /+stdWrap

Data type

wrap

Description

Wraps the whole item.

Default

wrapItemAndSub

Property

wrapItemAndSub

Data type

wrap

Description

Wraps the whole item and any submenu concatenated to it.

Default

subst_elementUid

Property

subst_elementUid

Data type

boolean

Description

If set, all appearances of the string '{elementUid}' in the total element html-code (after wrapped in .allWrap} is substituted with the uid number of the menu item.

This is useful if you want to insert an identification code in the HTML in order to manipulate properties with JavaScript.

Default

RO_chBgColor

Property

RO_chBgColor

Data type

string

Description

If property RO is set (see below) then you can set this property to a certain set of parameters which will allow you to change the background color of e.g. the table cell when the mouse rolls over you text-link.

Syntax:

[over-color] | [out-color] | [id-prefix]

Example:

page = PAGE
page.typeNum = 0
page.10 = HMENU
page.10.wrap = <table border=1>|</table>
page.10.1 = TMENU
page.10.1.NO {
  allWrap = <tr><td valign=top id="1tmenu{elementUid}" style="background:#eeeeee;">|</td></tr>
  subst_elementUid = 1
  RO_chBgColor = #cccccc | #eeeeee | 1tmenu
  RO = 1
}

This example will start out with the table cells in #eeeeee and change them to #cccccc (and back) when rolled over. The "1tmenu" string is a unique id for the menu items. You may not need it (unless the same menu items are more than once on a page), but the important thing is that the id of the table cell has the exact same label before the {elementUid} (red marks). The other important thing is that you DO set a default background color for the cell with the style-attribute (blue marking). If you do not, Mozilla browsers will behave a little strange by not capturing the mouseout event the first time it's triggered.

Default

[tsref:cObject.TEST]

Example

Here you would show an example of the stuff from the reference or so:

page = PAGE
page.typeNum = 0
page.10 = TEXT
page.10.value = HELLO WORLD

Tutorial

A full point-a-to-b-to-c walk-through of an application of the extension. Include screenshots.

Language: As tutorials are...

Target group: Whatever fits.

Known problems

Use this section for important warnings about bugs, problems or performance issues. This is where you should explain shortcomings of the extension, so that people are properly warned. Be honest.

Target group: Mostly Developers

TYPO3 Forge link to your project

Alternatively if you like: User contributions to YOUR manual. (Don't use the forge wiki page, because nobody will find it. The central wiki is wiki.typo3.org .

To-Do list

A wish list of things you want to add or fix. This includes smaller problems/bugs which are best described as a to-do item.

Visions for what the extension could become with more development.

TYPO3 Forge link to your project .

ChangeLog

Create a file "ChangeLog" (see e.g. the extension "cal") to inform about changes or use this section to document all the changes through the versions.

Alternatively to using the following list: ChangeLog online (Forge gives the possibility to create a Roadmap very easily; change this link to point to YOUR extension)

0.5.0

Version

0.5.0

Changes

Fixed an ugly bug.

0.4.0

Version

0.4.0

Changes

Wrote the code of the extension.

Important guidelines

The following sections are not part of the template itself and if you use this file to write your manual, you can delete them. However, they contain helpful information for issues with Open Office, which can arise, when you use this template.

Inserting images

When you insert images you have several possibilities:

img-4 - Make a copy and paste it from e.g. Photoshop. If you do that, it is
REALLY IMPORTANT that you insert the image into Open Office using the menu "Edit > Paste Special" and then select "Bitmap". If you don't do it in this way, the image cannot be shown on the typo3.org Website (since it will not be stored as a PNG internally in the SXW file).
  • Alternatively you can use the traditional way "Insert > Graphics > From file" and insert an image from your hard drive. In particular use this if the image is photographic (JPG) since the internal storage as PNG is not good for photographs.

Generally please use copy/paste only for screendumps with large areas of similar color (good png compression) and JPG files for photographic images. Go for small images, 72 dpi, medium quality.

Fonts

The official documentation template relies on three open source fonts:

You find the font packages in the folder res/ inside this extension.

Make sure all these fonts are installed on your system before using the official template. (Note that OpenOffice also displays the name of the font in the font drop down selector, when you do not have it installed! So just seeing the right name there does not mean, that you see the text in the right font.)

Paragraph styles

  • Use the paragraph style "Default" for bodytext.
  • Use "Heading 1" to "Heading 5" for headers. "Heading 1-3" will be recognized as "sections" on typo3.org. "Heading 4-5" are subheaders, where "Heading 5" is preferably for "Examples".
  • For code listings, use the style "Preformatted Text" (found under "HTML Styles"). For code listings in tables there is a custom style called "Table Contents Preformatted".

You can see the allowed paragraph styles when you open the window "Formatting templates" by pressing F11.

Character styles

If only some words in a paragraph should be displayed as preformatted text (e.g. the name of a variable in PHP or of a property in TypoScript), use the character style "Preformatted text" (not be confused with the paragraph style with the same name):

Open the window "Formatting templates" by pressing F11. In that window click on the small button "Character Style" and choose "All" from the dropdown box. Now you see all available character styles. Mark the signs you want to change and click on "Preformatted text".

Linking

You can make hyperlinks in the documents as absolute URLs. Use the menu "Insert > Hyperlink".

Meta data and updates

There are three fields of meta-data you have to fill in. First of all go to "File > Properties...".

img-5 - In the screen "Description" you enter the title of the document.
Extension manuals are prefixed "EXT: [extension title]".
  • In the field "Subject" enter your extension key.
  • In the field "Keywords" enter the according keywords as explained by the text in the box "Comments" below.
  • In the screen "User defined" you enter your full name in the field named "Author".
  • Enter your email address in the field named "Email".

Finally you should not forget to update the version number on the cover page, before you release a new version of your extension.

HowTo: Update a manual to the new layout

With these steps you get it very fast:

  • Update the extension doc_template (if there is a new version).
  • Hit the F11 key to show the styles.
  • Copy everything from your old manual except the title page and the table of contents.
  • Delete the contents from the new manual but leave the title page and the table of contents there .
  • Paste your content into the new manual and check that the formatting is correct and images are in place.
  • Hint : When the header-styles are still in the old layout then clear and re-assign the new style.
  • If you update from doc_template < 1.5.0 to a higher version, you will need to adjust the styles in tables. See the example table in this document to see, which styles to use for the different columns, examples, caption and so on.
  • Update the page properties with your extension key, e-mail-address, name, language and tagging as explained in the section "Meta data and updates" above.
  • Currently the language and tagging properties are not in use by the TER, but they are findable by search.
  • Reload the table of content (right click update index table).
  • Insert your version number on the cover page below the title.
  • Ready.

HowTo: Alternative updating possibility: Import the styles from another document

img-6 Note: In some old OpenOffice versions (e.g. 2.4) there's a bug with the TOC, so that you will need the HowTo "Fix the TOC" after the import.

  • Load your manual, then hit the F11 key to show the styles.
  • Click on the small arrow top-right.
  • A select box appears , you click at "Load Styles" and then "From File".
  • Check all the boxes.
  • Navigate to the "doc_template"/doc" folder and switch the file-type to .sxw "OpenOffice.org 1.0 Text Document".
  • Open manual.sxw, now you can use the new style!

HowTo: Fix the Table Of Contents when it is empty

The TOC will be empty (or might miss some headlines) when the outline numbering (german: "Kapitelnummerierung") is broken.

To fix that go to the menu "Tools" > "Outline Numbering" and apply the missing "Heading" styles to the empty levels.

Update the TOC, ready.

HowTo: Fix the Table Of Contents when a chapter is missing

If you have created a new section with a new header (which is not yet displayed in the TOC), you simply have to update the TOC to get it displayed there.

If you have changed the styling of a header to something else, it will no longer appear in the TOC. To fix that clear the formatting of the header and re-assign the header-style.

Help from documentation.openoffice.org

OpenOffice offers an international portal, where you can get help: http://documentation.openoffice.org