DocTeam/Online TSRef
From TYPO3Wiki
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.
Contents |
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:
Second draft of the new structure:
