[Typo3-dev] Extension Developers Guide TOC

[Leendert Brouwer [Netcreators]]

Hey list!

As a follow-up of the "extension reviewing" post where a discussion was
digged up about the documentation for extension writing, I've written a
suggestive Table of Contents for this user guide, to get things going. It's
probably very incomplete, and I hope this post will have the desired
snowball effect as to what is missing or what should be done differently
(I've only touched Typo3 since a month, after all). After we have decided on
the correct TOC, I believe it will be time to ask who will take
responsibility for what part. Also, it would be great if we can form a
Quality Assurance team for this guide, as to provide developers with
information that is as correct as possible. There's nothing more annoying
than incorrect technical information.Oh btw if this appears to be too
unreadable, I can throw it in an OpenOffice document instead.

Lines underlined with '---- ' are chapters.
Lines prefixed with a - are sections
Lines prefixed with a * are abstracts for the sections

Typo3 Extension Developers Guide

Preface
--------
 * Some things about what is in this document, and how it should be used

Introduction
------------
 - What is an extension?
  * What an extension is exactly, and why they allow for so much
flexibility, and when you start making your own extensions
- Extension types
  * Explains the difference between user extensions and core extensions, and
when you actually need either of   those
 - Required knowledge
  * Information on the knowledge about concepts that matter when you write
extensions. E.g. PHP,  databases and database normalization, the concept of
Typoscript, OOP etc. (possibly accompanied with links to   online documents,
articles and literature suggestions)


The Typo3 architecture
-----------------------
 * Explains the overall architecture of Typo3, possibly accompanied by
diagrams. The "why" of things is also    very important here.
Pre/post-processing issues, the role (and boundaries!) of Typoscript, the
philosophy    behind the architecture, the TCA etc. (Kasper will be the best
judge of the structure of this section)

Extension Maintenance
-----------------------
 - Extension scope
  * Explains the difference between global and local scope for extensions,
and when to choose which (also the things to take in account when choosing
either of them)
-  Upgrading
  * Practices that are involved with keeping your server clean and safe for
upgrading (i.e. avoiding breaking   things by modifying an existing
extension and then upgrading it), some things about dependencies, how to
manually install extensions etc.
 - PHP Compatibility
  * Things to keep in mind when installing extensions on the server (like
the register_globals thing,     explaining the distribution's .htaccess file
that sets PHP flags, PHP version compatibility, etc.)

Programming Extensions
-------------------------
 (note: probably better to not rely on the kickstarter here, it's more
educative to learn from scratch if you   really want to learn about
extension writing, and that's why someone reads this guide after all)
 - One base for all
  * Explains why and how you should inherit from tslib_pibase, and how your
extension will be 'hooked' at    runtime.
- Things you must use
  * Explains which parts of the Typo3 API are mandatory to use in order to
work correctly with Typo3 or "system   - intense" extensions of Typo3 (like
RealURL).
- Things you can use
  * Explains which parts of the Typo3 API are there for you to use, but are
not mandatory (like the template    engine)
- Types of user extensions
  * A description of the different kinds of user extensions (frontend
plugins, modules, etc.) and when they    should be used (case examples of
when they should be used would be helpful)
- Required extension files
  * For each type of user extension, it should be clear what files need to
be present in order to make the    extension work, and what exactly should
be in them (while specified whether something is mandatory or not, to
avoid bloat and confusion!).
- Extending an extension
  * Actions that are required to extend an extension, and the implications
this has for future compatibility. A   case study would be useful here.
- System extensions
  * Explains what is different about system extensions, when they can/should
be written and how they differ    from user extensions. A case study would
be useful here.

Common practices
-------------------
- Handling user data
  * Examples along with descriptions on how to handle incoming GET/POST data
- Dealing with Typoscript
  * Explains when to use Typoscript for your extensions and how to read it
inside the extensions
- Handling file uploads
  * Examples of dealing with file uploads in extensions
- Using sessions
  * Examples of how to use PHP sessions in your extensions (even though
that's "vanilla PHP", I can imagine    confusion about this subject)
- Using databases
  * Examples of how to query a database and the best ways to deal with the
data (even though that's "vanilla    PHP")
- Handling user authentication
  * Examples on what exactly should happen for e.g. logging a user into
Typo3

Structural practices
-------------------
- Coding conventions
  * All naming schemes, style rules, database naming rules etc. to conform
to
- Handling content
  * Examples of how to use the markers, TemplaVoila, Smarty etc.
- Writing larger extensions
  * Suggestions on how to structure your code when writing larger extensions
(explanation of Front Controller   style structures)
- Porting third party applications to Typo3
  * Things to keep in mind when porting third party applications to Typo3
such as database migration, user    integration, etc.