Upgrade Guide#

This topic was split from "[+summary+] deprecated?"
I love the new documentation, but I'd like to see a list of all the major changes like this. I'm not referring to a changelog, but rather an actual list that shows you summary is now introtext, tplAltRow is now tplAlt. These were a couple of changes that I had to make in which I really had to dig to find. I know it's covered in the normal documentation, but it was not clear to me that they had actually been changed to something else. The summary, which I couldn't figure out why it was broken on my site, I just learned out in this thread.

I'd love to help, so if can, please let me know what I can do.

A migration guide would indeed be good. For example, "To make your existing ditto calls work the same, addblah, blah2`, and change the following templates: ..."

http://mirror3.cvsdude.com/trac/ditto/codebase/wiki/Upgrade#Version1to2

Thanks Mark... for a quicker reference, here's the guide with some questions that I personally would like expanded upon:

1) Upgrade Ditto per the instructions in install.txt
2) Make sure you change the deprecated parameters to their new equivalents using the parameter list located here: http://ditto.modxcms.com/files/snippet-ditto-php.html

Number 1 I get.

Number 2, not so much. In fact, not at all. With a quick glance I don't see any reference to the old vs. the new. A guide listing what was changed specifically would be REALLY helpful.

3) If you are using [+summary+] in your templates append &extenders=`summary` to your Ditto call
4) If you have [*fields*] in your [+content+] make sure Ditto already has access to them in the form of [+field+]. If you need to add a field but not have it displayed use the &hiddenFields parameter

Number 3 is straightforward. Number 4 completely confuses me and could use a bit clearer explanation.

5) (optional) Remove all tv prefixes

You might consider rewording step 5 for clarity. Keep in mind unless you're building new sites every day with ditto, it's easy to set it up and not remember the intricacies a few weeks or months later. Maybe something along the lines of:

5) Remove the "tv" prefix from Template Variables (TV) used in your templates/calls. For example, if you were using a "foo" TV, Ditto pre-2.0 required prepending it with "tv": &param=`tvfoo`. Ditto 2 deprecates this requirement so you could write it as &param=`foo`. The same holds true for Ditto templates. [+tvfoo+] would more simply and intuitively be just [+foo+].

Of course it's been a few weeks since I've created a ditto call from scratch so I'm not sure if this is exactly accurate!

i am having same problems like you ryan.

i am totally confused - and i thought i would get stuff like that. ;-)

Thanks for posting that, Ryan. I thought it was just me!

I can't fault Mark, though. He's already provided plenty of great documentation to a great product and if I were in his shoes, I'd be spending time perfecting the product rather than writing documents and answering silly requests.

Anyhow, here's more along the lines of what I had in mind. This isn't complete by any means and I probably don't have the terminology exact, but this is what I was referring to: http://ditto.campfiresites.com/

Eventually, I'd like to see the same thing available for Wayfinder.

Does this idea seem like something that might help people in this and other similar situations?

Quote from: ZAP at Mar 10, 2007, 10:06 AM

You know I was thinking that it might be a good idea if all snippet developers started dealing with backwards-compatibility the same way. There are a ton of changes between ditto 1 and 2 for example, and it can mean that you need to make a lot of changes to all of your snippet calls if you upgrade. At the same time, as a developer it's a drag to have to be saddled with supporting all past versions when you probably had good reasons for making the changes in the first place.

What if all snippet developers started adding a common parameter (&backwardsCompat=`1`) to all snippets that would when set run a function with a standard name that did all of the variable conversion and whatever else were necessary to make things work the old way. Then developers could keep the vast majority of this code in one standard place (keeping the new code neater), and users who don't need the old methods would not set that parameter. If you had a site with a lot of old snippet calls and you wanted to upgrade them all you could set this parameter in the new snippet itself and that way avoid having to change all of your snippet calls throughout your site).

What do others think of this idea?

I think it honestly adds a lot of bloat to snippets. Documenting the changes is entirely reasonable, though I would think that changing the snippet name (e.g., Ditto2) would also be a good solution. There is a boatload of stuff that needs to change with Tiny MCE 2.10 for example, and it'd be a lot easier to make a new one than worrying about upgrades. Snippets that are functioning should be able to be more easily excluded from upgrades.

I was actually thinking that this might reduce the bloat. A lot of the major snippets already include backwards-compatability code (including Ditto), but it's scattered throughout the snippet and therefore difficult to debug and maintain. If it were all in one place then developers could keep track of it better and users could decide whether to include it (add bloat) or not (it could even be a separate included file if people think that would make it more efficient).

As an example, if this parameter were set people wouldn't need to set the summary extender or remove the tv prefixes or change hiddenTVs to hiddenFields, etc. The backwardsCompat funtion would just set those variables and then pass them on to the snippet as if they'd been set the new way. Other more complex conversions could also take place in this function, but the snippet itself wouldn't need to have all that code mixed in.

I already do this myself when there are major changes in new versions of snippets. I create some quick parameter-translation or other update code and add it to the beginning of the snippet. If you have a site with a whole lot of snippet calls, this can save you a great deal of downtime in the update process.

To quote from er16004;

He's already provided plenty of great documentation to a great product and if I were in his shoes, I'd be spending time perfecting the product rather than writing documents and answering silly requests.

I respectfully disagree. On the contrary, the documentation lacks one essential ingredient; how to use the product. If there were good examples of how to use the syntax there would be fewer questions in the forum. It is no use to document a piece of software and leave out the how-to-use-it.
For example, if I sat you down in a 737-800 cockpit and said "execute a fullly automated cat.3 approach - and everything you need is in front of you" - you wouldn't have a clue how to start - clear as glass to me though.
It's the same with software. Good tools require instructions from the creator on the use.
Cheers,
HalD