Yet, that's only partially true... the migrator component has some really handy tools implemented to do its thing with your component too...
Assumptions...
If you got to this page, I'll be assuming a few things: for starters you're familiar with the great Migrator component. You'll find more about this component on Pasamio Project's FRS site. You've probably been using it to migrate a site to Joomla 1.5.x … and I might assume that you bumped into some tables that weren't migrated because the add-on was missing... Furthermore, I'll be assuming that you know some elementary PHP, SQL and the very elementary basics of the Joomla framework (mostly Joomla 1.0). This hand-out is meant for all of us (inclusing myself) who wrote some tiny little component in Joomla 1.0, and now want to make the leap to 1.5 – but already have a load of SQL data they don't want to manually input again (possibly on half a dozen sites). My last assumption is that you're too lazy too do all the work manually (counting myself in again)... and you'd prefer some simple script doing it for you. In the examples, we'll be assuming default settings for your Joomla site location... if you've changed them, you'll know.
Why not?
On almost every forum out there tackling Joomla, you'll find one or another posting complaining about the lack of a migrator add-on for this or another component out there. Probably the most important reason for those add-ons not being there, is because there's no simple step-by-step tutorial out here (on the web). There are a few (more technical) explanations out there, that go into the deeps of the mechanics of the migrator component... but for me they rather scared me away than encourage me to look into it. But that was until today: today I actually opened the code... and looked into the “plugins” folder of the component. Then I ordered them according to file size, and opened the tinyest one of them: Wow man! This is really easy!! The easy approach: it's a “black box” So what this component actually does in all its nitty gritty details? I don't have to know that. All I need to know is: what should I feed it, so it burps out a nice great Joomla 1.5 compatible SQL result?
Most component tables: nothing needs to change...
I guess for over 99% of the components out there, the SQL tables won't need to change if you migrate the component (not talking about the code here... just the content) I don't think this can get much easier... except maybe if the component itself would automatically migrate all tables without plugin in this manner... We'll have a look at “poll_data.php” – the plugin that migrates the data for the polls. This data can be found in the table jos_poll_data. The code actually starts at line 20 with the definition of a class - everything prior is purely informative (so we won't tackle these in here).
Code: Select all
1 - class Poll_Data_ETL extends ETLPlugin {
2 -
3 - var $ignorefieldlist = Array();
4 - var $valuesmap = Array();
5 -
6 - function getName() { return "Poll Data ETL Plugin"; }
7 - function getAssociatedTable() { return 'poll_data'; }
8 -
9 - function mapvalues($key,$value) {
10 - switch($key) {
11 - default:
12 - return $value;
13 - break;
14 - }
15 - }
16 -}Step 1: naming the class: the name of the table + ETL (line 1)
There's a default class that should be used as base for all migration classes
Step 2: Defining some variables we'll be needing (line 3 and 4)
There's a couple of variables that can be used to refine the migration process (for more info, read the next paragraph):
We're only initializing these two variables, and leave them empty: no changes have to be done to our table content.
If you do need changes to happen... do read on (and I hope others will add to the discussion)
Step 3: Showing our name (for the overview) (line 6)
This isn't that critical, but quite important if you only want to migrate certain tables... It's a description of the table we're tackling with this plugin - a small typo won't break it (but will express you lack of discipline)
Here you'll need to change the text inside the string:
Code: Select all
function getName() { return "My favorite component core table ETL Plugin"; }This line implements the function that will tell the migrator what table to look for. Here too, you'll be putting your specific value. On this line, a typo will obviously break the process as the table wouldn't be found...
Code: Select all
function getAssociatedTable() { return 'favorites_data'; }The mapvalues function is a core function, as it alters the content inside the fields... but since we don't need to change anything, we just keep the minimal function and don't change it.
Step 6: Save the file
You'll be giving the plugin the right name: the same name as the associated table.
I immediately saved it inside the "plugins" folder of the migrator component, but installing it from inside the component shouldn't be that hard...
A little bit deeper: Looking at the Black Box!
So let's just see this migrator as a black box... Here, we have 2 questions:
1) What do we need to feed it?
Its internals already suck in the database tables information needed. No need to worry about that.
So we need to add the things that change. Herefore, we need to create a class extending the basic class (ETLPlugin). This class offers some tools that will define the differences:
(information comes from the nicely commented PHP code itself)
Variables:
- $ignorefieldlist - List of fields to ignore
- $newfieldlist - List of fields to add (with blank values)
- $valuesmap - List of field values that need mapping/transformation
- $namesmap - List of field names that need mapping/transformation
- getName() - Returns the name of the plugin
- getAssociatedTable() - Returns the table that this plugin transforms
- getTargetTable() - Returns the table that this plugin transforms its data into (by default same one as AssociatedTable in prior function)
- getEntries() - Returns the number of entries in the table
- mapValues($key,input) - Maps old params to new params (Run before mapNames !!) (default: same $input value)
- mapNames($key) - Maps old names to new names (useful for renaming fields) (default: $key)
- getWhere() - Returns an SQL where clause (default: empty)
- getSQLPrologue() - Generates any SQL statements that need to be completed before the rows are generated (default: empty)
- getSQLEpilogue() - Generates any SQL statements that should be completed after the rows are generated (default: empty)
- Finally there's the doTransformation function, that does all the magic... you shouldn't be overwriting this one unless you really know what you're doing (in that case: please advance to the last paragraph... and read that )
Basically the box spits a chunk of code and appends it to the long list of all the other altered information - in a way that the Joomla 1.5 installer can understand it. (for the curious ones: it's plain text, mostly SQL... read it if you feel challenged)
Changes are needed...
So there are some situations where you will actually need to convert information... There are a few things that can commonly change:
- fields used for connection with other tables
- configuration parameters need to be saved conform Joomla 1.5 specs
- you've discovered a flaw and want to take the opportunity to refine your table settings
I hope this thread will open some awareness that it's not really that difficult to write a migrator plugin for whatever component you (or someone else) wrote... Maybe this thread could also point to places where you (or others) already created third party plugins for the Migrator.
