Upgrading to Typo3 3.5June 2002

Copyright 2000-2002, Kasper Skårhøj, kasper@typo3.com

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

Inside Typo3 - 1

Table of contentsIntroduction .....................................4

Introduction.....................................................4Syntax.............................................................4

The concept.................................................4

Inside Typo3 - 2

What's the fuzz? The Extension ManagerIt's all about the Extension Manager (EM):

The Extension Manager (EM) is the power center in Typo3 from version 3.5. By this version there has been made aclear separation between what is considered “core parts” and “extensions” in Typo3.

This concept of separation has lead to more than 70 default extensions. These are old core parts which has nowbeen extracted from the core and made into extensions which can be optionally added or removed!

Many of these default extensions are enabled by default. But they are marked “shy”. That is why they don't showup in the list of loaded extensions:

Inside Typo3 - 3

But if you enable the “Display shy extensions” flag, you'll see all the installed “default” extensions:

(Technical note: The extensions installed by default are listed by their extension key in the variable$TYPO3_CONF_VARS[“EXT”][“extList”] configured in t3lib/config_default.php)

Former default extensions, not default anymorePreviously when Typo3 was one big chunk of stuff, all considered “core”, there was a number of less used featureswhich are now considered optional and must therefore be specifically enabled if you used them before.

The image below shows the list of available extensions which were formerly installed by default, but do now needspecific installation:

Inside Typo3 - 4

So if you used any of these features, you must install the proper extension:

• Static file edit (came with Typo33b1)

• These plugins: Address list, Calender, Guestbook, Link list, Messageboards, News, Shop

• In the Task Center: Actions, Messaging, Plugin list, Tasks (To-dos), Workflow

• The plain text import found in Web>Func / Import

• The Direct Mail module.

Inside Typo3 - 5

So you think:

Oh, boy!

I don't wanna go through another

hairy technical install procedure!

Now, dont worry!

Installing an extension is exceedingly easy!

Say, you want to install the message board and the newsletter subscription (using the address table). Simply clickthese buttons (in the EM, select menu “Available extensions to install”):

In some of the cases you will need to click a confirmation button for clearing the cache or installing tables andfields. Most probably you should just obey and press the button...

The result is this list of loaded extensions (with the “Shy” flag unset):

And you are done!

(Of course you are not. Read on.)

Inside Typo3 - 6

ChecklistImportantIn general the upgrade is straight forward, but because you are most likely you have a Typo3 site with at leastsome of the formerly default extensions enabled, you'll most likely have to enable those extensions. Therefore theupgrade procedure is - apart from the usual stuff with the files (see the “installing_upgrading.pdf”) - all aboutfinding out which extensions you should enable for your site(s).

Here are some general things you should be aware of:

• The list of plugins found in the Content Element type “Insert Plugin” is empty! Items are added automaticallyto this list when extensions with plugsin are installed. However if you wish to enable the old list, a fix isprovided of course: Just enable the extension “Set Old Plugin list” (setoldpluginlist).

• All plugin-related files from media/scripts/ which has been transformed into extensions has been moved tomisc/3.0.0/oldscripts/. You can always copy those files back into media/scripts/ if you wish a quick backwardscompatibility for those old plugins.

• A number of good old static templates are now depreciated because their future is in the hands of a newcorresponding extension. You can still use them. Maybe some day they will disappear.

• Observe any cron-jobs you may have pointing to moved files now!

Checklist

1: Backup your site, in particular the database

No explanation needed, I hope

2: Install the new source

As usual, follow “installing_upgrading.pdf” document. But when you upgrade the database, wait with the table-comparison - only update static tables now:

3: Detect use of old frontend plugins and substitute with extensions

Notice: You dont have to convert the usage of the old plugins into the new corresponding extensions.

Inside Typo3 - 7

The disadvantage of using the new extensions is that they apply database-wide - so using the message board asan extension means it is available in every TypoScript template inside the database - formerly you added the statictemplate for the message board only to template records where you needed it.

The advantage of course is the ease of use.

If you wish to continue along the old lines, you should simply copy the contents of the misc/3.0.0/oldscripts/ folderback into media/scripts/ and ignore the rest from here (of “3: Detect use of old frontend plugins” that is).

These static templates has now been converted into plugins:

+------------------------------------------------+-----+| title | uid |+------------------------------------------------+-----+| content.tt_address [DEPRECIATED] | 65 || language.de (german) [DEPRECIATED] | 93 || language.dk (danish) [DEPRECIATED] | 76 || language.fr (french) [DEPRECIATED] | 96 || language.nl (dutch) [DEPRECIATED] | 95 || language.no (norwegian) [DEPRECIATED] | 97 || plugin.feadmin.dmailsubscription [DEPRECIATED] | 91 || plugin.feadmin.fe_users [DEPRECIATED] | 92 || plugin.meta [DEPRECIATED] | 68 || plugin.tipafriend [DEPRECIATED] | 90 || plugin.tt_board_list [DEPRECIATED] | 66 || plugin.tt_board_tree [DEPRECIATED] | 80 || plugin.tt_calender [DEPRECIATED] | 62 || plugin.tt_guest [DEPRECIATED] | 64 || plugin.tt_news [DEPRECIATED] | 79 || plugin.tt_poll [DEPRECIATED] | 94 || plugin.tt_products [DEPRECIATED] | 61 || plugin.tt_rating [DEPRECIATED] | 88 || temp.tt_board (shared) [DEPRECIATED] | 81 |+------------------------------------------------+-----+

What you need to do is search the table sys_template for the uid numbers of these static templates and whereeverthey are found in use, you should disable them.

In modules Tools>phpMyAdmin (or your MySQL client), perform this query (just copy/paste it all):

SELECT uid,pid,title,include_static FROM sys_template WHERE include_static LIKE '%61%' OR include_static LIKE '%62%' OR include_static LIKE '%64%' OR include_static LIKE '%65%' OR include_static LIKE '%66%' OR include_static LIKE '%68%' OR include_static LIKE '%76%' OR include_static LIKE '%79%' OR include_static LIKE '%80%' OR include_static LIKE '%81%' OR include_static LIKE '%88%' OR include_static LIKE '%90%' OR include_static LIKE '%91%' OR include_static LIKE '%92%' OR include_static LIKE '%93%' OR include_static LIKE '%94%' OR include_static LIKE '%95%' OR include_static LIKE '%96%' OR include_static LIKE '%97%' ORDER BY pid;

That will generate a result, for instance this could be it:

+-----+-----+-------------------------+----------------+| uid | pid | title | include_static |+-----+-----+-------------------------+----------------+| 1 | 2 | Barneguiden direct mail | 71,76,82,77,57 || 3 | 8 | Barneguiden 2001 | 23,68,90,43,77 || 2 | 3 | dmail admin | 43,91,57 |+-----+-----+-------------------------+----------------+

It tells us that three sys_template records possibly uses the old static_templates which are now depreciated.Therefore were are going to find those, remove the static template and at the same time enable the correspondingplugin in the extension manager.

Now repeat this process for every static template listed in the result:

(Tip: Press CTRL+N to open two Typo3 backends, one with the Extension Manager ready to enable extensions, theother to modify templates)

Inside Typo3 - 8

1: Find and remove static template(s)

Go to the Web>Template module, click the root-page and in the overview, find the page id (pid's) of the pageswhere you seek the templates:

Find the correct template if many and edit it:

Find and remove the static templates:

Save it

2: Enable the corresponding extension:

Go to the Extension Manager (EM). (If you were clever you pressed CTRL+N - else do it now so you can quicklyswitch forth and back between editing the templates in Web>Template and adding extensions in the EM).

Simply find the corresponding extensions and click the “Add” button ...

Inside Typo3 - 9

(see table below to an overview)

... when if presented with a question like this:

... simply shoot and ask questions later ...

... and back in the EM you can now see that your extensions are nicely installed as you have requested!

Notice: If you add some of the “TS language ...” extensions, please read the notice on configuration hereof in thelater section in this document, “Static template files with language definitions”.

Inside Typo3 - 10

Old static template: New extension #content.tt_address Address list 1

plugin.feadmin.dmailsubscription Direct Mail Subscription 2

plugin.feadmin.fe_users Front End User Admin 3

plugin.meta Meta tags, extended 4

plugin.tipafriend Tip-A-Friend 5

plugin.tt_board_listplugin.tt_board_treetemp.tt_board (shared)

Message board, twin mode

6

plugin.tt_guest Guestbook 7

plugin.tt_news News 8

plugin.tt_poll Poll 9

plugin.tt_products Shop system 10

plugin.tt_rating Rating 11

plugin.tt_calender Calendar 12

language.no (norwegian) TS Language, Norwegian 13

language.nl (dutch) TS Language, Dutch 14

language.fr (french) TS Language, French 15

language.dk (danish) TS Language, Danish 16

language.de (german) TS Language, German

17

Repeat the process. When you are finished you should see something like this in the Template Analyzer for all yourtemplates (of course it depends on which plugins are enabled...):

Inside Typo3 - 11

Obviously five new static template files are added by the extensions enabled. This is produced by this list ofinstalled extensions:

4: Add any other extensions you know were previously used

In the former section in this document, labels “Former default extensions, not default anymore” you can findinformatin about which extensions were default previously. If you used any of these, install the extension now.

5: Update database table/field structure

After having installed the new extensions as substitution for the old plugins + any additional extension you knowwere used, you should now consult the Install Tool to verify and update the database structure:

Then you'll probably see something scarry like this:

Inside Typo3 - 12

Now there are two aspects of this process:

1. The ordinary updates of new and changed fields. Those are the actions checked off by default. Just press the“Update” button and that is all done.

2. Clean up of excessive tables/fields. This is what is described below. Notice: You don't have to go through this clean-up process. It just means that you remove any un-useddatabase fields and tables, which is generally a nice thing to do! So if you are a little shaky here, just bypassthe instructions below and go on to the final step.

When the Install Tool evaluates the database structure it does so based on which extensions has been installed.Therefore you'll see a lot of tables listed here which the Install Tool claims are in excess!

Inside Typo3 - 13

Basically you should just remove any unused tables and fields (which does not have a yellow exclamation mark atit, which often indicates a user defined field). But because you are in the middle of an update you shouldwisely consider if some of the tables suggested to be removed actually contains important data for anextension you might have forgotten to install!

So here is what you do: Notice all tables which has records in them. Now think good if this table holds data for anextension which you haven't installed yet. If so, install the extension now and reload this screen. The tables shouldnot be listed anymore and you go on with your evaluation.

Notice: The table “static_dc_type” is an experimental system table and can safely be removed.

Cleaning up in the above case ended up looking like this with only some user fields and tables left:

But in all future development this is message worth figthing for:

(With a registered extension key you don't need to use the obsolete “user_” prefix for custom fields and tables -because there are NO such thing as custom fields and tables! There are only fields and tables as required by theinstalled extensions whether those are “custom” in your eyes or not...)

6: Finally consider this

• Are any cron-jobs configured for a script in the source code which has changed it's position now? Eg. direct-mail?

• Search for "media/scripts/" with the raw seach in Tools>DBint. If the string is found in a “TypoScript template”record as a TypoScript resource, eg. like:

plugin.tt_board_list.file.templateFile = media/scripts/board_template3.tmpl

you must substitute it with the proper path to the extension, eg:

plugin.tt_board_list.file.templateFile = EXT:tt_board/pi/board_template3.tmpl

(For details on this subject, see later in the document)

• There are still a bunch of scripts left in media/scripts/ folder which does not need any change (for now...). Oneof the most popular is “fe_adminLib” found in media/scripts/fe_adminLib.inc. For your information which scriptand some others does not require any action taken.

Inside Typo3 - 14

The steps in a quick overview:Here is a quick printable overview for those of you who has to go through tons of installations with these repeatedsteps:

1. Update static tables

2. Do SQL search for static templatesRemove depreciated static templates, add new extensionsMaybe do a SQL search again to make sure you got them all...Make sure “TS language” extensions were configured for default activation if you need that.

3. Add any other extensions you know are needed

4. Update / Clean up field/tables

5. Search for the string media/scripts/

Inside Typo3 - 15

Possible tough scenarios

Static template files with language definitionsIf you want to add localized values for some of the plugin extensions (such as guestbook, messageboard etc) addthe corresponding language extension:

But before it will work, you must

• either manually set up the language in your TypoScript template (Setup-field):

config.language = da

• or ask the extension to try to set the language by default (which may or may not work depending on yourtemplate):

Now all templates in the database should have danish set as language unless overridden in the individualtemplates (see option one above).

Inside Typo3 - 16

Extension does not substitute old plugin seemlesslyBy default static template files are added after other included static templates for any template record which is theRoot-flag set. That would look like this in the Template Analyzer:

However that was not the case on typo3.com because the template record “ext: www.typo3.com” has a basistemplate included (“Main template: Typo3 website”). Because of that, the inclusion of static templates (includingthe static template files set up by the loaded extensions) were loaded before the basis template. It looked like this:

Inside Typo3 - 17

This is a problem because the static file templates are using objects from the “styles.content (default)” statictemplate and therefore expects that to be included before them, so they can access the objects. So it didn't work.The solution could simply be to set this flag for the “ext: www.typo3.com” template record:

At least the message board was displayed now:

Inside Typo3 - 18

But obviously the template file was wrong! How come? Well, because the template file was defined as a constant inthe template record “Main template: Typo3 website” which happend to be included before all the static templatefiles - and therefore the constant had no effect!

Solution was to alter the default inclusion mode of static template files for two templates:

• For “ext: www.typo3.com” template record the value “Never include before this template record” was selected

• For “Main template: Typo3 website” the value “Always include before this template record” was selected.

Result:

Inside Typo3 - 19

... and it worked. Because now the static template files were included after any static template records (inparticular “styles.content (default)”) but before the “Main template: Typo3 website” template record (which definedthe constant setting up the template used for the message board).

And the board looked correct (apart from people posting too long lines....:-)

Where is the file formerly in media/scripts/ ?All plugins which has been converted into extensions has had their original files moved to misc/3.0.0/oldscripts/.You can copy that folders content into media/scripts/ and the problem is solved.

But the better way of course is to change the reference to the new location in the extension folder.

Inside Typo3 - 20

If the file defined is set up as a TypoScript file resource you can use the prefix EXT:[extension key] to refer to thefolder and the proper prefix will be added.

Example:

On Typo3 I used the template file

• media/scripts/board_template3.tmpl

for the template. That was moved to the extension folder, so I had to change the path to

• EXT:tt_board/pi/board_template3.tmpl

... where “tt_board” is the extension key for the plugin.

Inside Typo3 - 21