Video tutorial for upgrading a plugin to Joomla 1.6
Andrew Eddie
2 weeks after that (all going well). Here's the start of my
contributions to help developers on the journey of upgrading their
extensions. I went through the exercise of upgrading a plugin this
week and I've documented the things I had to deal with and created
this video tutorial:
http://www.theartofjoomla.com/home/9-developer/112-upgrading-a-plugin-to-joomla-16.html
Note that the changes to the XML manifest and language files equally
apply to Joomla 1.6 components, modules and templates so it's useful
to watch regardless of the type of extension you develop.
The full transcript is supplied so if you are interested in
translating it just shoot me a mail and we'll work out how that can be
done.
I hope you find this video useful.
Regards,
Andrew Eddie
http://www.theartofjoomla.com - the art of becoming a Joomla developer
Marius van Rijnsoever
My preferred method is described in:
http://www.netshinesoftware.com/component/option,com_myblog/Itemid,65/show,Creating-a-single-install-package-for-a-plugin-that-works-on-Joomla-1.-1.5-AND-1.6.html/
This allows people to have their component/plugin/module to be
installed on both Joomla 1.5 and 1.6. Branching of extentions is best
avoided if possible as that doubles the workload for developers.
Thanks, Marius
> --
> You received this message because you are subscribed to the Google Groups "Joomla! General Development" group.
> To post to this group, send an email to joomla-de...@googlegroups.com.
> To unsubscribe from this group, send email to joomla-dev-gene...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/joomla-dev-general?hl=en-GB.
>
>
Andrew Eddie
As I said, if you want to do it that way, then your tutorial is
certainly a way to do it :)
There are pro's and con's to both ways and maybe that would for the
basis of a good tutorial in itself because neither way is the "right"
way (I'm just telling you what my experience is having been in the
game as long as I have). As for me, I rather enjoyed stripping out
all of the junk and workarounds from my 1.5 extension that is now
supported natively in 1.6 ;) The problem does get pretty interesting
in components and modules because the CSS has changed a fair bit in
both the frontend and backend. That's one of the other reasons I'd
advocate making the break (and I'll be scaling back my 1.5 development
once 1.6 is released - for example, I'm going straight to 1.6 for a
subscriptions extension to take advantage of the new ACL, it's inane
to keep battling in 1.5 land with that sort of thing).
1.6 to 1.7 and beyond is a different matter though we are ending the
era of waiting 2-3 years for new core releases and I could see
multi-version support working in that case because the API changes
will be less drastic (one would hope anyway) and the near libraries
installer makes life a lot easier.
Anyway, thanks for the link to your tutorial. Devs can make an
informed decision looking at both ways and pick the method that best
suits them. Neither method is easier or better than the other, just
different. If you are supporting 1.5 and 1.6 your workload is doubled
anyway, one way or the other.
Oh, there is a third way and that's to include a 1.6 forward
compatibility layer in your 1.5 components, which I am doing in a
number of my newer extensions (but then, I always seem to be doing
crazy things like that, hehe).
Regards,
Andrew Eddie
http://www.theartofjoomla.com - the art of becoming a Joomla developer
Marius van Rijnsoever
I can't claim credit for that tutorial. it was created by netshine.
The more options the better, as each developer will choose the right
option for them. It all comes down to what that person want to achieve
and how complex the joomla plugin is. A handy trick that I am using
(again to avoid branching my components, a personal pet hate) is the
following code:
$version = new JVersion;
$joomla = $version->getShortVersion();
if(substr($joomla,0,3) == '1.6'){
$query = 'SELECT enabled FROM #__extensions WHERE
element=' . $db->Quote($element) . ' AND folder=' .
$db->Quote($folder);
} else {
$query = 'SELECT published FROM #__plugins WHERE element='
. $db->Quote($element) . ' AND folder=' . $db->Quote($folder);
}
Easy to detect Joomla 1.6 using JVersion and easy to handle issues
like renamed core tables.
Thanks again for you hard work, Marius
Royce
deeply embedded the logic is with J!1.5. I lucked out because I
pretty much followed the 'approved' MVC conventions for my component.
I was able to convert them in a matter of minutes (just changed the
$mainframe and the .xml file fields). On the other hand, I was
contracted to convert a very major J! component that was as far from
standard as imaginable. The conversion has been going on for over 3
months and there is no end in site!
I really wish I had kept a log of the changes we've had to make so
far. It would have certainly helped anyone else in the same boat.
Its been a totally disheartening task because the code wasn't well
organized and used every trick, work around, hack, etc.
Here is a short list off the top of my head of the gotcha's so far:
1. Language file - J!1.6 enforces strict rules for language
translations. No more spaces in the keys or values that aren't
enclosed in double quotes.
2. Changes to view parameters - J!1.6 has a strict new way of
specifying parameters for views. J!1.5 allowed a bit of freedom where
the parameters could be defined at the view.html.php level but now it
has to be at the tmpl level.
3. Plugins - J!1.6 now creates a different hierarchy structure for
plugin types. Files are no longer placed where they used to be, so if
your component expects them to be in a certain position, it won't
work.
4. Installation process - preflight, postflight, etc - These are new
events that can screw up an existing installlation process.
5. Custom fields - The entire process changed and now the fields must
inherit from J! base classes.
6. Admin template changes - Admin functions that depended on certain
functions, naming conventions etc no longer work.
7. ACL - Gone are the old user table fields of 'gid' and 'aid'. Its
been replaced by an incomprehensible ACL structure.
8. Renamed methods, table names, etc.
I am sure there were other problems, but that is what I can remember
right now. Its going to be extremely difficult for some complex
functions to convert to J!1.6. Its going to be worse than the
conversion from 1.0.x because there is no 'legacy' switch. The market
will get fragmented and users will be confused and frustrated.
Hate to be a downer, but that is the view from my trench.
Andrew Eddie
> Its really going to come down to how complex the function is and how
> deeply embedded the logic is with J!1.5. I lucked out because I
> pretty much followed the 'approved' MVC conventions for my component.
> I was able to convert them in a matter of minutes (just changed the
> $mainframe and the .xml file fields). On the other hand, I was
> contracted to convert a very major J! component that was as far from
> standard as imaginable. The conversion has been going on for over 3
> months and there is no end in site!
This only confirms what I've been preaching for years now ;) If you
are following "our" conventions, then you will have less pain than if
you aren't using the API as it is supposed to be used. That's just
life unfortunately. Look on the bright side, it's an employment
opportunity for you ;)
> 1. Language file - J!1.6 enforces strict rules for language
> translations. No more spaces in the keys or values that aren't
> enclosed in double quotes.
Correct. The win is that that language files are parsed many times
faster than the 1.5 method, giving us a good performance boost.
> 2. Changes to view parameters - J!1.6 has a strict new way of
> specifying parameters for views. J!1.5 allowed a bit of freedom where
> the parameters could be defined at the view.html.php level but now it
> has to be at the tmpl level.
I'd have to check the code again but yes, I believe we took out the
view parameters. It's not down to layouts.
> 3. Plugins - J!1.6 now creates a different hierarchy structure for
> plugin types. Files are no longer placed where they used to be, so if
> your component expects them to be in a certain position, it won't
> work.
If you are loading plugins correctly via the API then you won't be affected.
> 4. Installation process - preflight, postflight, etc - These are new
> events that can screw up an existing installlation process.
That could only be true if you put something strange in the new
events. If you don't use them, there is no possible way their
presence could adversely affect your site. You must be doing
something strange.
> 5. Custom fields - The entire process changed and now the fields must
> inherit from J! base classes.
This is no different from 1.5 inheriting from JElement. In 1.6 you
inherit from JFormField which is a much more robust class.
> 6. Admin template changes - Admin functions that depended on certain
> functions, naming conventions etc no longer work.
Can you expand on that. Like what?
> 7. ACL - Gone are the old user table fields of 'gid' and 'aid'. Its
> been replaced by an incomprehensible ACL structure.
Far from incomprehensible, we've cut the number of tables that the ACL
relies on in half and given them human understandable names. Yes,
there are changes involved if you are using 'gid' and 'aid' but they
are certainly not onerous and it's a small price to pay for people who
want to access the new ACL.
> 8. Renamed methods, table names, etc.
Correct. This has been advertised for some time now. We have not
made any table changes for nearly 6 years. It's time to clean some
things up.
> I am sure there were other problems, but that is what I can remember
> right now. Its going to be extremely difficult for some complex
> functions to convert to J!1.6.
Yes, for people that are doing strange things in their extensions
because they don't know the API, it's going to be very hard.
> Its going to be worse than the
> conversion from 1.0.x because there is no 'legacy' switch. The market
> will get fragmented and users will be confused and frustrated.
It will be no worse than when 1.5 came out and while there is no
hand-holding legacy mode, there is a very high degree of API backward
compatibility (providing you are using it). The goal is not to
eliminate confusion and frustration - you can't (so everyone just need
to get over that), but the life of a software developer is to manage
those problems when changes occur. The user base has been crying out
for particular features (better ACL, better categories, etc) and we
couldn't do that without making some significant changes. Some
developers will embrace those new changes (I'm building native 1.6
extensions and loving it) and some will fight against it because they
resist change. The call is yours as to whether you support 1.6 but I
will tell you this - it will be first in best dressed. Those that
rise to the challenge will be able to penetrate areas of the market
that they may not have been able to crack in 1.5-land. Look at it as
a huge opportunity to expand your business if you have one.
> Hate to be a downer, but that is the view from my trench.
You are just being realistic and we've been telling developers all
through the development process that these changes are coming.
Developing in 1.6 is faster and more flexible than 1.5 and those that
learn that art are going to go far. It also means that 1.6
extensions, by and large, will be of a higher quality because you
can't just cut corners as easily as you could - and I think that's a
good thing. The only real downer is that some developers are going to
have to upskill to keep up - but that's also a good thing.
The other thing to remember is that uptake of 1.6 will follow a
similar trend to 1.5. It took well over 6 months for 1.5 to really
bed down and it will take the same amount of time for 1.6 in my
opinion and, quite honestly, 1.6 makes quite a few 1.5 extension
obsolete while opening up new markets for new types of extensions.
It's all a balance but this is progress and there is no gain without
some pain. As for me, I can't wait for the day I can drop support for
my 1.5 extensions because I'm sick of including the workarounds to
make them work like they do in 1.6 ;)
Royce
cooperation and community education. I'm not making any comments on
whether the changes are good or bad, just that there are many and the
more they are documented (even in forum threads like this) the better
for the community as a whole.
My comment about user frustration and fragmentation is from my belief
that not all developers will make the switch to J!1.6. So a user will
be forced to choose between 1.5 and 1.6 based on what capabilities
exist for which platform. I know this is the same thing that happened
when we went from 1.0 to 1.5, but that legacy 'crutch' certainly made
the pill a bit easier to swallow. I'm sure some major components will
not make the switch so it will be very interesting times for the near
term ;-)
I don't know exactly how large the component I'm converting is, but it
is probably one of the largest in J! and one of the most popular. The
goal is to have one code base that supports both 1.5 and 1.6, so there
is a lot of conditional checking for versions. That wasn't my idea,
but that is what the end result is supposed to be. So something as
simple as the language translations may have 1000's of values and
places they are used and of course it has to be fixed in the .ini file
as well as the code. And guess what, all of the existing translations
themselves (e.g. spanish, french, etc) also have to be converted!
The new sys.ini language translation file is another new feature that
I didn't mention before. That seems to be used during the
installation process, but it took a lot of debugging to figure out
which variables are taken from that file and which are taken from the
original language file.
To follow up on a few of the other points:
Plugin installation - If you have multiple plugins for a group, J!1.5
would place the .php and .xml files under that group name, so all of
your plugins for that group would be on the same directory level. If
they all (or a component) needed access to a common directory under
that 'plugin group' they could get access from that top level in the
hierarchy. J!1.6 will now create a separate folder/directory for each
plugin in the group. So now the common directory that they need
access to is one level up! That is why I had to use the new install/
scriptfile.php and postflight() method, to check which version is
running and move the common files to the original place so that the
associated component would know where to find them.
Custom fields - This component made extensive use of them probably
30-40 or so, they all have to be rewritten to use the new inheritance
structure.
Admin Template - I honestly don't remember the exact issues, but it
has to do with the removal of the khepri template. I suppose the
direct access to that template was not authorized, but any function
that expects it to be there will need to change. So of course I had
to fix things that broke because that template isn't there in J!1.6.
Javascript - I didn't mention this before, but the includes/js library
was totally removed in J!1.6. Again, I don't know if access to that
library was 'supported', but components that used it for things like
the 'overlib' will not work. And yes, that was another 'gotcha' for
us.
Mootools switch - I didn't mention this either, but the change to the
new version will cause any existing JS that depended on the old
version to break. Yes, that hit us also. Nothing like having to dig
through old JS code and trying to find documentation on an old version
of software to see how to change it to make it compatible with the new
version.
ACL - I'll leave that for another thread ;-)
I could go on and on about our experience, its been quite a case study
in why developers should stick to approved API methods as much as
possible. For me, this process has been a well paid, but torturous
nightmare. I hope others have an easier go at it.
regards,
Royce
Marius van Rijnsoever
Like you said the more this is documented the better it is. I have
added my experiences so far to the Joomla wiki:
http://docs.joomla.org/Tutorial:Upgrade_Joomla_1.5_Extension_to_Joomla_1.6
Would you be able to add your tips and tricks when you have some time?
Thanks, Marius
Marius van Rijnsoever
>contracted to convert a very major J! component that was as far from
>standard as imaginable. The conversion has been going on for over 3
>months and there is no end in site!
I certainly feel your frustration, as everytime I think i get close to
having my component working on Joomla 1.6 another issue pops-up.
<start of rant>
It feels like it has been made as hard as possible to migrate
components to Joomla 1.6. My current frustration is that almost ALL
events have been renamed, meaning any plugin that uses events won't
work out of the box. The solution is to add a forward compatibility
layer to my components.
The question however is why firstly these events had to be renamed (it
adds no new functions and will break all old joomla extentions that
use events) and secondly why no backward compatibility layer was
added. Instead of this now every developer will have to start adding
code like (to handle the renamed event):
public function onUserLogout($user) {
$result = $this->onLogoutUser($user);
return $result;
}
</end of rant>
Ok that feel much better getting that off my chest. Marius
elin
We used to say do you want to develop for Beta Max or VHS ha ha ha, but now ... if that is how you are seeing your platform choices, well good luck but the world has passed you by.
Marius van Rijnsoever
I am all for moving forwards, the transition to make code compatible
with Joomla 1.6 is frustrating (even if your code is 100% Joomla 1.5).
With the transition from VHS to CD's you had dual player. Blue-ray
players are also compatible with CD's. The legacy mode allowed for a
smooth transition between Joomla 1.0 and Joomla 1.5. The frustrating
issue is that now all developers have to create their own legacy layer
(it would have been very easy to include this in the core for most
things). This will seriously hamper the uptake of Joomla 1.6 like
pointed out by other people.
With platform choices stability is an important factor. You can't
blame me for whinging about their 100% Joomla 1.5 code not working on
so many levels in Joomla 1.6 (like other people pointed out it takes
months for a medium sized extension). Especially since I am working
hard on overcoming there differences and documenting all required
changes for other developers on the joomla wiki.
But that is why my rant was inside a <start of rant> </end of rant>
tag (yes I know it is not valid xhtml), so you could ignore it if you
wished.
marius
elin
Royce
Can't wait for J!2.0 but this is what I want now AMOLED http://bit.ly/fszrbt
Royce
Tim Wattenberg
Am 18.12.10 02:00, schrieb elin: