DEPRECATION WARNING
This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.
| Created: | 2007-10-04T18:32:32 |
|---|---|
| Changed by: | Alban Cousinié |
| Changed: | 2009-05-11T13:14:22.170000000 |
| Author: | Author Name |
| Email: | your@email.com |
| Info 3: | |
| Info 4: |
EXT : Templavoila XML for Flash¶
Extension Key: tv_xml_for_flash
Copyright 2009, Alban Cousinié, <extensions@mind2machine.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.com
Table of Contents¶
EXT : Templavoila XML for Flash 1
Introduction 1
What does it do? 1
Screenshots 2
Users manual 4
FAQ 8
Adminstration 8
FAQ 8
Configuration 8
FAQ 10
Reference 10
Tutorial 10
Known problems 10
To-Do list 10
Changelog 11
Introduction¶
What does it do?¶
There already exists several extensions capable of outputing Typo3 content to XML so it can be read by flash, but none supports templavoila and I found they were not stable enough to rely on them for production purposes.
This extension is capable of exporting the whole page tree as XML and the whole content of a given typo3 page including flexform data. It exports ALL information i could gather from 'pages' and tt_content tables, thus generates pretty big XML files (they still load quickly though since there are no images), but in return you can make use of almost any typo3 information from flash, such as controlling if a page has a start / stop date, sorting information, creation date etc...
Several types of flexform fields are recognized during and processed in order to be reverted from their Typo3 custom internal format to a format usable externaly.
Currently the extension knows how to deal with the following flexform editing types (eTypes) :
- bodytext edited with RTE including all type of links (open window, file link, internal link, external link). Images embeded from inside the RTE are not tested and likely not to be supported. Anyway I don't think flash supports including an image inside a text field.
- Input text
- image input
- link input
- content element
It is easy to customize the PHP code in order to deal with more type of objects as explained in this documentation, but I haven't had enough time to cover all eTypes of contents present in typo3. The eTypes provided in standard should already cover most usages. If you add some content types, please send me your code so I can integrate it into the extension for the benefit of the community.
This extension is capable of dealing with multiple web sites and multiple languages.
Important : web sites making use of this extension should have Typo3 and their mysql database configured for utf-8, as flash doesn't handle properly non utf-8 content.
Screenshots¶
These websites are making use of tv_xml_for_flash :
Leisure park Vulcania : http://www.vulcania.com
Agence Bande à part : http://www.bandeapart.fr
This is a part of the XML output of the page structure :
This is a part of the XML output of a page data :
Users manual¶
Once the extension is installed and configured it can be used as is (notice the page type set by default for this extension is 555)
This will of course load your regular web page with your flash template :
http://www.mydomain.com/index.php?id=25
Now from the flash you can retrieve the content data associated with page id 25 using the following URL :
http://www.mydomain.com/index.php?id=25&type=555
You can also retreive the page tree as XML using the following URL :
Retreiving the page tree as XML using the siteMenu.xml file is now deprecated and no longer works since version 0.9
http://www.mydomain.com/typo3conf/ext/tv_xml_for_flash/res/siteMen u.xml [DEPRECATED]
((generated))¶
Base actionscript code you may want to use as a start for loading XML content :¶
See the new actionscript 3.0 API + preloader located in the /res/Flash_AS3_Typo3_API directory of the extension (in typo3conf/ext/tv_xml_for_flash/)
Structure of the XML for page description¶
Here is a simplified output of a page layout featuring 2 content areas : column1 and column2
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Typo3Page>
<sys_language_uid id="sys_language_uid">0</sys_language_uid>
//this is the current sys_language_uid displayed in the frontend
<page id="page">
<attribute id="uid">29</attribute>
|
Page attributes listing
|
</page>
<contentElements id="contentElements"> //here we start listing the content elements in the page
<contentElement id="field_column1"> //first content element in the page template
<element>
<attribute id="uid">264</attribute>
|
secondary importance attributes listed here
|
//when bodytext is typed it appears in this attribute, as it is not recorded in the database as a flexform element
<attribute id="bodytext">
This is a bodytext typed in the RTE
</attribute>
|
secondary importance attributes listed here
|
<attribute id="flexformFields">
//here you may find some flexform elements. Look in column_2 how they appear
</attribute>
|
</element>
</contentElement>
<contentElement id="field_column2"> //second content element in the page template
<element>
<attribute id="uid">334</attribute>
<attribute id="flexformFields"> //here we have flexforms !
<flexformField id="field_mp3group" title="MP3 group content area">
<element>
<attribute id="uid">143</attribute>
|
secondary importance attributes listed here
|
//we have a nested content element here !
<attribute id="flexformFields">
//here are the attributes from a flexform
//notice the fields in green are named as in your flexform data structure specification
//this is a file link
<flexformField id="field_mp3src"> fileadmin/my-file.mp3</flexformField>
//this is input text
<flexformField id="field_title">Spot radio Vulcania #1</flexformField>
<flexformField id="field_bitrate">256</flexformField>
//this is an image
<flexformField id="field_imgsrc">uploads/tx_templavoila/poste-radio.jpg</flexformField>
</attribute>
|
secondary importance attributes listed here
|
</element>
</flexformField>
</attribute>
</element>
</contentElement>
</contentElements>
</Typo3Page>
Structure of the XML for page tree¶
This is a page tree XML stripped and formated for readability. I have left all attributes for the first page, but removed most attributes on following pages.
Most interesting attributes are commented. Some I have not commented may interest you as well.
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Typo3Sitemap>
<page uid="3" //The page uid
pid="0" //uid of the page parent. 0 is the tree root
t3ver_oid="0"
t3ver_id="0"
t3ver_wsid="0"
t3ver_label=""
t3ver_state="0"
t3ver_stage="0"
t3ver_count="0"
t3ver_tstamp="0"
t3ver_swapmode="0"
t3_origuid="0"
tstamp="1191428736"
sorting="128"
deleted="0" //should be 1 if the page is deleted, but deleted and hidden pages are not output by the plugin
perms_userid="1"
perms_groupid="1"
perms_user="31"
perms_group="19"
perms_everybody="0"
editlock="0"
crdate="1184687398" //creation date of the page
cruser_id="1"
title="www.bandeapart.fr" // the page title
doktype="1" //very important. This value tells if the page is a regular page, advanced page, shortcut, sysfolder and such...
storage_pid="4"
is_siteroot="0"
php_tree_stop="0"
tx_impexp_origuid="1"
url=""
hidden="0" //should be 1 if the page is hidden, but deleted and hidden pages are not output by the plugin
starttime="0" //if specified, the page should go online at specified timestamp
endtime="0" //if specified, the page should go offline at specified timestamp
urltype="1"
shortcut="0"
shortcut_mode="0"
no_cache="0"
fe_group=""
subtitle="" // page subtitle
layout="0"
target=""
media=""
lastUpdated="0"
keywords=""
cache_timeout="0"
newUntil="0"
description=""
no_search="0"
SYS_LASTCHANGED="1191428736" //last page modification timestamp
abstract=""
module=""
extendToSubpages="0"
author=""
author_email=""
nav_title=""
nav_hide="0"
content_from_pid="0"
mount_pid="0"
mount_pid_ol="0"
alias=""
l18n_cfg="0"
fe_login_mode="0"
tx_templavoila_ds="2" //uid of the datastructure for this page template
tx_templavoila_to="2" //uid of the template for this page
tx_templavoila_next_ds="0" //uid of the datastructure for subpages
tx_templavoila_next_to="0" //uid of the template for subpages
>
<page uid="25" pid="3" >
<page uid="32" pid="25">
<page uid="33" pid="32" />
<page uid="34" pid="32">
<page uid="42" pid="34" />
<page uid="41" pid="34" />
<page uid="40" pid="34" />
</page>
</page>
<page uid="31" pid="25">
<page uid="45" pid="31" />
<page uid="67" pid="31" />
<page uid="43" pid="31" />
<page uid="52" pid="31" />
</page>
</page>
</page>
</Typo3Sitemap>
Important note :
Since version 0.9, the count of fields output in the XML file can be reduced to only the fields needed. This can be done by editing the file stripedKeys.php in the extension forler for this purpose and specify there the useless fields that should not be output. Most useless fields are now already stripped by default.
FAQ¶
None yet.
Adminstration¶
Usage of this extension is only targeted at web developers, and there are not administration requirements.
FAQ¶
None yet.
Configuration¶
- Install the extension.
- In the extension settings (in the ext manager, click on the extension name), set the Site root uid value to the page Id of the root of the website you want to publish as XML. Currently this extension is limited to publish only one website.
logically, you should be using templavoila, so the Typoscript setup of your site root page should at least feature the following lines :
//we are using templavoila
page = PAGE
page.typeNum = 0
page.config.doctype = xhtml_trans
page.10 = USER
page.10.userFunc = tx_templavoila_pi1->main_page
//remember flash requires utf-8
config.metaCharset = utf-8
config.renderCharset=utf-8
if you want to modify the pageType for the XML generated content, set the following line in your typoscript setup :
// setting the page type to 888
extension.tv_xml_for_flash.XMLPageContent = 888
Inserting the flash file in your template :
##############################################################
# Transmit Typo3 variables thru javascript
##############################################################
page = PAGE
page{
headerData{
10=HTML
10.value(
<script type="text/javascript" src="/fileadmin/templates/vulcania.fr/javascript/swfobject.js"></script>
)
//Passing required Typo3 variables to the javascript
20 = COA
20{
10=HTML
10.value= <script type="text/javascript">var langKey='
20 = TEXT
30=HTML
30.value= ';var id='
40 = TEXT
42=HTML
42.value= ';var pid='
44 = TEXT
46=HTML
46.value= ';var realurl='
48 = TEXT
50=HTML
50.value= ';var baseURL='
52 = TEXT
54=HTML
54.value= ';var siteIndex='
56 = TEXT
58=HTML
58.value= ';var siteRootUid='
60 = TEXT
70=HTML
70.value= ';var L='
80 = TEXT
90=HTML
90.value= ';</script>
}
}
}
//transmit current page pid and uid values
page.headerData.20.40.data = page:uid
page.headerData.20.44.data = page:pid
##############################################################
# Multi-language adjustments
##############################################################
// Netherlands language
[globalVar = GP:L = 3]
config {
sys_language_uid = 3
language = nl
locale_all = nl_NL
htmlTag_langKey = nl-NL
}
page.headerData.20.80.value = 3
[END]
// German language
[globalVar = GP:L = 4]
config {
sys_language_uid = 4
language = de
locale_all = de_DE
htmlTag_langKey = de-DE
}
page.headerData.20.80.value = 4
[END]
//update language key in javascript variable in page header
page.headerData.20.20.value < config.language
##############################################################
# Multi-site adjustments
##############################################################
//site principal
[PIDinRootline = 2]
config.baseURL = http://www.vulcania.com/
page.headerData.20.56.value = 0
page.headerData.20.60.value = 2
[end]
//site education
[PIDinRootline = 51]
config.baseURL = http://education.vulcania.com/
page.headerData.20.56.value = 1
page.headerData.20.60.value = 51
[end]
##############################################################
# REAL URL adjustments
##############################################################
config.tx_realurl_enable = 1
page.headerData.20.48.value < config.tx_realurl_enable
page.headerData.20.52.value < config.baseURL
Then insert you FLASH file either using typoscript or by putting it natively in your XHTML template HTML code.
Notice 1 : usage of swfobject is recommended as it generates less code and is very intuitive to use.
Notice 2 : don't forget to pass the typo3 parameters to the flash applet using javascript
<div id="flashcontent">
</div>
<script type="text/javascript">
// <![CDATA[
::
var so = new SWFObject("fileadmin/templates/vulcania.fr/flash/vulcania.swf", "vulcania", "984", "467", "9", "#FFFFFF");
so.useExpressInstall('fileadmin/templates/vulcania.fr/flash/expressinstall.swf');
so.addVariable("id", id); // typo3 page ID
so.addVariable("pid", pid); // typo3 page parent ID
so.addVariable("langKey", langKey); // language ISO2 code
so.addVariable("realurl", realurl); // url rewriting status
so.addVariable("baseURL", baseURL); // url rewriting status
so.addVariable("L", L); // language variable in url request
so.addVariable("siteIndex", siteIndex); // 0=site principal, 1=education, 2=groupes, 3=seminaires, 4=science
so.addVariable("siteRootUid", siteRootUid); // page uid for the root page of the website
so.addParam("AllowScriptAccess", "always"); // allows loading xml files between http and https
so.addParam("loop", "false");
so.write("flashcontent");
::
// ]]>
</script>
Now you should be able to insert some bodytext in some content area you have defined in your template and the text should show up in the XML when you call your page with the parameter &type=555
((generated))¶
How to create Flexforms for use with the extension ?¶
Simply create a basic HTML file featuring attributes so you can map the data of your interest. For example, here is the flexform template for the MP3 flexform featured in the page sample XML format described above :
<div>
<img src="" title="" bitrate="" imgsrc="" />
</div>
The top div is required so you can map the root of the flexform data structure on it. Our file is an MP3, but we have used an <img> tag here because templavoilà would not let us map a custom html field <mp3>. Anyway we don't care since this flexform is not intended to be output to HTML : our interest goes to the fields recorded in the database so they can be output to XML.
Then the fields are mapped as is :
FAQ¶
How do I add custom processing for an unsupported eType ?
Look in the file typo3conf/ext/tv_xml_for_flash/XMLPageContent.php around line 509 to figure how supported editing types are processed. Then make your own processing, and don't forget to send it to us for sharing with the community.
In order to know the right syntax for the etype name testing like if($DS_definition[$key]['eType']=="rte"){},look the datastructure XML of your flexform for the content of the <eType> tag you want to process correctly. The tag should contain the internal Typo3 name for the eType which you should be testing against.
Reference¶
Tutorial¶
Known problems¶
- Multi language has not been tested with single tree scheme, only separate tree is tested and aproved
- Flexforms of type “container” are not supported
- Some Flexforms eTypes are missing and remain unsupported
To-Do list¶
- Support all Typo3 eTypes
- Improve XML tab formating (could it be passed thru tidy for automatic indentation?)
- Test single tree multiple language model support
- Move stripedKeys specification to typoscript setting
- Caching of XML content as text files would be nice
Changelog¶
- Version 0.9 (release date 11/05/2009) :
- WARNING : breaks compatibility with version 0.8 !!! Sitemap.xml no longer supported. Use the &getPageTree parameter instead.
- Now compatible with actionscript 3.0 + small typoscript 3.0 API supplied in the extension directory
- now supports multiple websites and multiple languages (separate tree model tested only)
- removed support for sitemap.xml static file due to multiple language support
- links output as realURLs in the sitemap when realurl is enabled
- fixed the following problem : when 2 images in the website have the very same name, the image processing function which remaps the image path from the database information may return path to the wrong image if found first in the database entries of the sys_refindex table.
- Many other small bugfixes I don't remember of..
- Allows optimization of XML content files by allowing to disable output of unwanted database fields (edit file stripedKeys.php in the extension forler for this purpose and specify there the useless fields that should not be output).
Version 0.8 : First release (release date : 05/10/2007)
- 12