Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

DocTeam/Online TSref

From TYPO3Wiki
Jump to: navigation, search
This page belongs to the Documentation Team (category DocTeam)

notice - Note

Christopher: We should check in how for the new typo3.org website already offers this, also in addition with using ReST. Maybe there is not much to do here then.

notice - Note

We want to start a kickoff meeting at T3DD10

Currently, an accurate, easily accessible online TypoScript reference on typo3.org, something like the PHP function reference, doesn't exist.

The functional requirements for such a reference tool are discussed on this page.

Goals of the T3DD workshop

  • Information
  • Discuss: how should the xml should look like => so others can rely on this
  • To form teams for the time after the T3DD
  • 30 minutes ore more should be time of coding

Requirements for the whole project

must have

  • XML format which can easily transformed into the XML used by the t3editor
  • "Speaking" URLs like typo3.org/documentation/TSref/stdWrap/typolink#ATagParams
  • URLs should be case-insensitive (it's what RealURL does anyway, isn't it?)
  • viewable as one long page (allows to use the browser's build in search functions for inexperienced users)
  • viewable as separate pages (faster access for experienced users, better suited for comments)
  • downloadable as PDF for offline reading
  • the server must be fast
  • (implementation using extbase for forwards compatibility)
  • spam comments shall not be possible: a math captcha! (better use the typo3.org SingleSignOn?) maholtz: +1 for singlesignon
  • the "raw" reference itself must be available for download from some official URL, so that other applications may use it too.
  • links! if a property is type of string/stdWrap - both types should be linked!

nice to have

  • XML should be extensible. It should be possible to define the possible propertys for an extension and merge it with the main TSref-XML-File.
  • rating of the snippets
  • with snippets from snippets.typo3.org (based on tags)
  • with comments (text field, for additional information, a special hint or feedback for that page/property)
  • rating of that documentation (for each property)
  • use tabs (FIXME: please clarify)
  • browsing like the jQuery docteam has created: http://api.jquery.com/ --- http://api.jquery.com/browser/ (but allow opening browser tabs by middle-clicking on links) maholtz: on my laptop i do not have a middle-click. I do not like that, its wasting of space
  • support different languages
  • generate some parts of the openoffice manual e.g. the tables => or even replace the TSref with a printable version of the online reference. Parts of the TSref that are not really a TypoScript reference need to be moved to other manuals

t3editor: XML format/data structure

A brainstorming in the documentation mailing list resulted in the following sketch of a data structure/XML format for the new TSref:

  • Property
  • Data type
  • Short Description
  • Examples / Long Description
  • default value
  • deprecated since version
  • introduced with version
  • see also (list)
  • security (a flag indicating that a function is relevant to security issues - like config.baseUrl, htmlSpecialChars, select.andWhere)

URL

  • never changing url
  • versioned
  • ID: valid for TYPO3-version from ... to

Discussion of XML structure

Example (please comment, extend and discuss):

<?xml version="1.0" encoding="UTF-8"?>
<tsRef>
<type id="string">
	<description><![CDATA[ ... ]]></description>
</type>
<type id="CONFIG">
	<property name="ATagParams" type="string">....</property>
</type>
<type id="PAGE">
	<property name="config" type="CONFIG">....</property>
</type>
<type id="stdWrap">
	<property name="stdWrap" type="stdWrap">....</property>
</type>
<type id="typolink">
        <property name="ATagParams" type="string">...</property>
</type>
<type id="TEXT" extends="stdWrap">
</type>
<type id="GB_TEXT" extends="GifBuilderObj">
 ... that is the GIFBUILDER-TEXT Object in t3editor
</type>


<type id="TMENU" extends="CommonProperties"">
 ...
</type>
<type id="TMENUITEM" extends="CommonItemStates" parent="TMENU">
...
<type>

<type id="tx_extendstdwrap_pi1" parent="plugin">
        <property name="enable" type="boolean">
</type>

</tsRef>

Draft structure created during T3DD10 workshop: http://drp.ly/1kAG1X

Drafts

First draft of the new structure:

Tsref1.png

Second draft of the new structure:

Tsref2.png