Naming, Terminology and Understanding all the New Awesomeness that is Revolution

I’d love to see a tree diagram or mind map of relationships of the various technologies and their assigned names and descriptions. I don’t know if that can be done quickly but it sure would be helpful to me as the explanations here are still making me woozy.

Accuracy can impede understanding. Strengthening analogies will help and we ought not be afraid to use two or three words where they describe vs assigning a name can seem arbitrary (whether it is or not.)

For the benefit of those coming late to the party, this is a continuation of a discussion started elsewhere that we decided would benefit from public discussion.

There is much new terminology in Revolution. There has to be, because it has a lot of new and amazingly cool stuff in it. We’re seeing the first hints of a traditional disagreement between hard-core coders, who want to use precise terms like "amplitude", "attenuation," and "saturation" and marketing people who want to use terms like "brightness," "mute," and "color" (even if those terms aren’t quite correct) to make life easier for users and the product more attractive to potential adopters.

Let me insert a comment I made in the other discussion to put my take on this in perspective:

I should have mentioned how blown away I am by the increased overall usability and power of Revolution and how impressed I am by its design and robustness. In particular, the whole package system is a marvel and should get some kind of award.

In re-reading my posts, I didn’t mean them to sound so critical. I just wanted to suggest tweaking the user-interface (using the term very broadly) a little.

To answer dev_cw’s question, the terms we’re discussing here (vehicle, resolver, etc.) relate to the package builder script. They would only be seen by developers -- not by site designers/administrators. But, put another way, everyone who wants to do the MODx Revolution equivalent of putting something into the MODx repository would have to understand them. Hopefully, that would be a lot of people.

The payoff for both developers and users is that in Revolution, if you want to install a snippet, module, plugin, or even a group of elements that work together, you simply download the package (through the Manager!), select it, and click on "install." Done. Finito. No file copying, no cutting and pasting, no muss, no fuss. Updating to a new version and removing a package are just as easy.

To paraphrase splittingred, if you are a serious member of the MODx community, get yourself a copy of WAMP, MAMP, or XAMPP and install Revolution on your local machine. Play with it. If there are things that make you say "what the heck is this?" find out what they are and, most important, don’t just say "this is too confusing," try to suggest a way to improve things.

Oops, forgot to answer dev_cw’s question about what those things are so more people can join in here.

I described installing a package, but first the package has to be built. Let me describe my understanding of the package build script. OpenGeek and splittingred can correct anything I get wrong and add parts I leave out.

Using the current terminology (which is what we’ve been discussiing):

The package is everything you want to install and it can contain pretty much anything that’s in MODx -- snippets, chunks, system settings, plugins, files, lexicons (what is in language files in 0.9.6), etc. It can also include a PHP script that can be run during the install.

A package is actually just a wrapper for a collection of lexicon entries, system settings, vehicles, and maybe a context.

Each vehicle holds a single snippet, plugin, chunk, etc.

A vehicle (optionally) can also hold resolvers which come in three basic types:

File Resolvers bundle up collections of support files to be installed in the appropriate locations (e.g. images, css file, js files, etc.).
Validation Resolvers check to make sure it’s ok to install the package (they’re PHP scripts that can check whatever you want).
Script Resolvers contain PHP scripts that will be run on install (possibly to interact with the user and set options).

To build a package, the package build script creates the package with some parameters like "name" "version" etc., (optionally) adds a lexicon, system settings, and a context. Then it adds at least one vehicle and optionally attaches one or more resolvers to that vehicle. Then the complete package is then packed and saved to a zip file.

The focus of this mini-discussion is that we can use whatever names we want for the functions in this process as long as we follow the rules which, as I understand them, are:

1. A package has to have at least one vehicle. (I could be wrong on this one, but it will be a rare package that doesn’t.)
2. A resolver has to be attached to a vehicle.
3. A package can have more than one vehicle.
4. A vehicle can have more than one resolver.
5. You can have as many vehicles and resolvers as you want in your package as long as you follow rule 2.

"Passenger" has been suggested as a substitute for "resolver," but then you have the problem of having "file" passengers, "validator" passengers and "script" passengers.

Another suggestion is to replace "resolver" with three terms like "VehicleValidator," "VehicleFileTransport" and "VehicleScriptTransport" (in that case "resolvers" would probably still exist behind the scenes in the packageBuilder class).

Opinions invited . . .

The terms kind of confuse me as they stand. I’ll hopefully be making some packages and the terms "VehicleValidator," "VehicleFileTransport" and "VehicleScriptTransport" immediately make more sense to me. They describe the item (vehicle) and what is does (validate, Filetransport, ScriptTransport).

Chuck

Let me try and simplify this more so we have a more accurate understanding of what this is before we continue discussing new names for these things.

I. A Transport is a package which contains one or more Vehicles and a manifest file controlling the order the Vehicles are processed in.
  A. A Vehicle simply represents anything you want to distribute in a Transport.
    1. An xPDOVehicle is the default Vehicle class; it contains a Data Object, and optionally, any number of Validators, Resolvers, and/or Related Data Objects.
      a. A Data Object, or xPDOObject, is just a representation of a row in a database table in xPDO.
      b. A Validator is a user-defined script or predefined action that is evaluated before a Data Object is installed or uninstalled.
        i. php validators are php scripts that return true or false; if a validator returns false, installation/uninstallation of the object is aborted.
        ii. other validator types will be identified and implemented
      c. A Resolver is a user-defined script or predefined action that is evaluated after a Data Object is installed or uninstalled.
        i. php resolvers are php scripts that return true or false to indicate if the script was successful.
        ii. file resolvers are predefined actions that contain one or more files and define a target path where those files should be installed to/uninstalled from.
        iii. other resolver types will be identified and implemented
      d. Related Data Objects are additional table row objects that are directly related to the main Data Object via an Aggregate or Composite data relationship (an xPDO concept), and are included in the same Vehicle.
    2. Other Vehicle classes can be created and implemented to transport things besides xPDOObjects (xPDOFileVehicle is in development to just hold files unrelated to a specific xPDOObject).
[EDIT: Added missing Related Objects concept to the outline]

Maybe this outline can better help the understanding of how the code is architected and needs to be referred to in our nomenclature.  A glossary is coming and I would prefer if we all gain this understanding before we engage in these exercises to clarify the actual features and functionality the code supports.

Sorry this is not easy to grok immediately, but I think the concepts are about as simple as they can be, and super extensible.

BTW, I think VehicleValidator, etc. is redundant; when you are talking about Vehicles already anyway.  And VehicleFileTransport is super redundant when a Vehicle is part of a Transport already.  That would confuse me as a developer, to have Transports contain Vehicles and Vehicles containing more Transports as those terms imply.

Thanks Jason!
That helped a lot understanding (as much as I can understand those concepts, I am in the kiddie pool even more than Shane) and more importantly for me tie it all together.

Now this being said I think BobRay is right : words won’t mean anything until we really get into Revolution. It means install it, play with it, build a dummy site, peek in files and DB... In other terms, get our feet wet We might not have answers to everything but we sure will have better questions to ask and contributions to offer.

I for one have done quick testing but now I intend to port an existing website (a simple one) locally. This will help really getting into it !

Maybe I’m just old-fashioned, but "resolver" is perfectly clear to me. Every desired action is a "problem" to be "solved" (problem - I want this snippet; resolution - whatever it takes to properly install this snippet), and the "resolver" takes care of whatever needs to be done to "resolve" the "problem". A generic term like that is appropriate here, I opine, since we’ll want to do so many different things with Revolution. Trying to narrow down to more specific terms for the various "resolutions" of the various installation "problems" will just lead to frustration as more and more "problems" come up that the existing ... er, resolvers? don’t quite answer.

OK, thanks for giving me some water wings. After understanding the process a bit more I agree with Sottwell, ’resolver’ makes perfect sense. Passenger describes the relationship to the vehicle but not the action, I prefer to think of things in terms of function.

BTW, I think VehicleValidator, etc. is redundant; when you are talking about Vehicles already anyway. And VehicleFileTransport is super redundant when a Vehicle is part of a Transport already. That would confuse me as a developer, to have Transports contain Vehicles and Vehicles containing more Transports as those terms imply.

This makes sense also. I have a superficial view of this process and need to get my hands dirty before I have an opinion based on actual experience.

I like the resolver and validator also, and they seem a logical name for me, but I’m just the opposite of what this seems all to be about. What I don’t like is when something technical is trying to be named commonly, like if resolver would be named passenger. And keeping that in mind, I didn’t like the Transport and Vehicle names when I first heard them.

What I would like is that the Transport would be called Package and the Vehicle would be called Container.

I may as well be a ham because I am sufficiently glazed over. I’ve read and reread the thread(s) and installed Rev-a-4 (I’ve looked at the pics and still, I’m lost.

Here’s what I’ve got so far:

Transport is a packaged and zipped collection of resources that can be ported from one install to another.
Provisioner is a Transport Source Location/URI
Package is a packaged and zipped collection or resources that can be ported from one install to another.
Workspaces is a name assigned to the place where packages and provisioners are managed
Lexicon is a language assignment matrix analogous to a language definition file.
Foci (I haven’t figured out this term yet) My guess is that it is a language element classificiation.
Vehicles have something to do with transports; some sort of wrapper for pieces to make it work?
Resolver no clue at all what this does or why I even need to know what it does since I haven’t seen it yet.

I will keep playing with Revolution. I will reserve criticism until such point I can offer some suggestion for improvement.

The explanations are helping so keep dragging my stupid ass along and I’ll apply the diaper creme along the way.

Cheers,

Jay

[Update] I have figured out what foci are (the name could be more fuzzy) from this description from OpenGeek.

Foci are language element classes or groups.