How to distribute a template as an extension

WARNING: This technique will not work with TemplaVoila templates, as the HTML Template Object (TO) mapping cannot be distributed in an extension. Only a Document Structure (DS) can be distributed. Therefore this document will only focus on the distribution of TypoScript based templates, such as described in the MTB1 tutorial.

Basis Creation

First of all you need to create an empty extension with the extension kickstarter. Enter a name for the extension (format is usually xxxxxx_tmpl). Just fill in the "General Info" details (screenshot), update, view result, and save the extension. That is all that will be done with the extension kickstarter.

Icon for the template

Create a colorful icon, size should be 21x18 pixels (common size across extensions), and should be called ext_icon.gif in the main extension directory.

Directory structure

Create the following subdirectories in the extension main directory:

- static: will hold all the typoscript files associated with the extension

- template: will hold the html, images, stylesheet files related to the extension

- doc: any documentation associated with the extension

Referencing files

In all the typoscript code that is related to this template, you will need to replace file paths (like images or stylesheets references) with relative filepaths to the extension. Use the following format to achieve this: EXT:<extension_name>/<directory>/<file> for example, a stylesheet for the template_tmpl extension may be referenced as EXT:template_tmpl/template/default.css This will allow the various files to be found no matter if the extension is installed as global or local

To convert an existing html template, you need to create markers:

1. 1. LOGOIMAGE### media/uploads/crcph/logo.gif
  2. PILIMAGE### media/uploads/crcph/pil.gif
  3. HOMEIMAGE### media/uploads/crcph/home.gif
  4. SEARCHIMAGE### media/uploads/crcph/search.gif
  5. PILIMAGE2### media/uploads/crcph/pil2.gif
  6. TOPARROWIMAGE### media/uploads/crcph/toparrow.gif

document the process to convert that with tags... (with the:

in the "constants.txt" file: variable = EXT:extensionkey/files/image.gif

in the "setup.txt" file: marks.SUBPART = {$variable} )

Create required files

1. <extension directory>/ext_tables.php:

<?php
if (!defined ('TYPO3_MODE')) 	die ('Access denied.');

t3lib_extMgm::addStaticFile($_EXTKEY,'static/','template: nouvo');

?>

The inclusion of the template is done by the creation of ext_tables.php. This is used to announce Typo3 that there is a new static template available for the users to choose in the "Include static (from extension):" screen (include screenshot).

t3lib_extMgm::addStaticFile() arguments are : (include an extract from the TSRef): 1st arg = extension key 2nd argument is path to: - setup.txt - constants.txt - include_static.txt - editorcfg.txt $path is the path where the template files (fixed names) include_static.txt (integer list of uids from the table "static_templates"), constants.txt, setup.txt and editorcfg.txt is found (relative to extPath, eg. static/') 3rd = title in selector box

2. <extension directory>/static/constants.txt

  # cat=basic/file; type=file[IMAGE_EXT]; label=Background image:
background = EXT:mysite_tmpl/template/images/background.gif

  # cat=basic/links; type=int; label=Login PID: Page ID of the sysfolder where the website user information is stored.
loginpid = 0

TSConstantEditor.basic {
  header = Template "mysite"
  description = My Site template
  image = EXT:mysite_tmpl/overview.gif
  1=logotop
  2=logo
  3=backgroundtop
  4=photo
  5=title
  6=login
}

Is the typoscript for constants used in the template. Usually this will be a list of items like the example, to help the positioning of calculated fields at specific marker positions within the template. (see the section that explains why we need EXT:... in front of filename)

Make sure that important settings for the template respect the TSCE structure: add the TSCE header (comments) for the variables in constants.txt

==> Write doc on how to create modifiable constants in the template ==> tell where to find the small '1', '2' '3'... numbers to copy/paste to the screenshot you would have made of a sample site. Also tell people what size and name the screenshot(s) should have. How to create different sections, and different screenshot sections. (TSCE)

3. <extension directory> static/setup.txt

marks.SUBPART = {$variable}

4. <extension directory>/static/include_static.txt

This iss a CSV of the uid for the included templates... (found with:

SELECT title, include_static
FROM `static_template` 
WHERE title
LIKE 'template%' )

Usage of the extension

Create new template, Remove all the default typoscript code (in the setup part of the template), and select the correct template in the "Include static (from extension):" (see screenshot)

Constants can be edited through the Template "Constants editor" (include screenshot) if they were properly documented.

Future ideas

it would be great if we would have a include_static_files.txt where you could specify the inclusion of other template files, to build some kind of library... Currently a library can only be built from static templates. or by manually including a sequence of templates from the template building record

Standard information

static templates are stored in :

- static_template DB (uid, pid, tstamp, crdate, title, include_static, constants, config, description, editorcfg) - they belong to the id0 page (list module)

they are made of :

- title : title - constants (text) : constants - setup (text) : config - dependencies on other templates : include_static - description (text) : description - backend editor configuration (text) : editorcfg

all of these can be seen in the id0 page details....

CONVERSION:

- look in the template all references to files and copy them to the "files/" directory

(example of styles.gmenu_layer.green - 75 content(default) - 43 plugin.meta [DEPRECIATE] - 68

- in the ext_tables.php you NEED TO HAVE the first argument of addstatic as $_EXTKEY OTHERWISE THE TEMPLATES WILL NOT APPEAR ANYWHERE AND NOT BE WORKING !

if the template depends on a specific static template that will never be used outside of it, then include it into the template extension (e.g here the styles.gmenu_layer.green).

find references to external files in the template constants & setup (e.g media/images/...) and store them to a "files" directory. Replace then their reference by something like EXT:extname/files/filename

my QUESTIONS

locallang ? ext_locallang ?

STATUS

ESCAPING is done through markers (see newsletter example...)

Typo3 Template Extension