Descriptive Terminology = "Semantic Intuitiveness"? (was: MODScripts?)

Adam,

Thanks for your tips on other kind of modules.

Hi everyone,

I have been doing quite a bit of reading on Modx and getting a bit confused at time about terminology and here are some of my thought regarding Modx terminology.

Template Variables and Widget are tightly related! Template variables are making lot of sense to be called "Content Fields" and since "Widget" is to modified the behavior of TV. So I think it would make sense to call them "ContentFields" for "Template variables" and "ContentFieldModifiers" for "Widget" and "@ Binding".

Note: add @ Binding to be parted of "ContentFieldModifiers"

Chunk and Placeholders are the same thing except "chunk" is static and "placeholders" is dynamic. So I think it would make sense to call them "StaticMacro" for "Chunk" and "DynamicMacro" for "Placeholders"

What do you think?

Thanks

Some new thoughts on this stuff after reflecting on all the suggested names and ideas for simplification, though I may be over-simplifying at this point:

Content Objects - I think field and variable are both inconcise in this case; our current TV’s and future enhancements to them have a wide enough scope to be labeled more generically as Objects. This also opens the door for hierarchical relationships among Content Objects. Maybe even the ability to build them from Content Classes?

Content Classes - Widgets become any kind of transformation a Content Object might require for rendering purposes (e.g. output of content objects), so why not build them from classes where they inherit the kinds of behaviors / transformations / triggers they need. We basically then create an extensible site model, based on solid OO concepts, where advanced users can author new Classes that could represent anything from a chunk of content to persitence of a user-defined object (custom database table).

We could then get rid of every other kind of resource, making them a set of core Content Classes for things such as PHP scripts (e.g. snippets), HTML (e.g. chunks), and templates. We could probably even use Content Classes to describe Plugins and Modules as well, though I’m still thinking on this one. Placeholders just become transient instances of Content Objects (e.g. not persisted, but created on the fly by other CO’s)?

Again, all this is just conjencture; a result of thinking about how to simplify the system even more, and make it super usable by beginners and geeks alike. Classes and objects may not even be the write terminology, but I thought it might better convey the general idea. Tell me if I’m taking this way too far too fast. ;-)

Jason,

I like it a lot, but worry that anybody but experienced developers would have a clue as to what the stufff was. As me to explain classes and objects and you’ll get an idea of what I mean.

Now, how we build it beneath the phraseology is another issue entirely.

Blast from the past bump in preparation for the new core ... now is the time to simplify.

Though I agree about simplifying I think we should not overdo it either.

I’ll quote Jeff Veen from his famous "Making A Better Open Source CMS" :

Stop it with the jargon already. I don’t know what a portlet is. Or a component, module, block, or snippet. The last system I evaluated had something called "mambots" which, to me, sounded like robotic assistance for breast feeding. Are you making up words to promote your differentiation in the market? Because it is confusing. Please just use simple words to describe the things your system does.

I know one of the simplification people have in mind is : snippets + chunks = a single item (to be named). Not sure... Those two items don’t do the same thing at all. It wouldn’t fit a task based approach to merge them.

If we stick to Veen’s "describe what it does", let’s examine what each of MODx components do :

Chunks

What do chunks do ?

Enable content re-use.
Pure and simple.

Notice I am not digging into the nature of the content (what it is), but what it does). To me the re-usability is the core of the concept, even more than the "bits of content" part (a chunk can contain a lot of things after all).

Should we rename it, I would start brainstorming on the re-use part.

Snippets
Snippets process content and perform operations on it (filter, sort, querry... whatever).

I don’t think "Processor" or "ContentProcessor" is sexy though , but with a bit brainstorming...

Plugins
Plugins listen to system events and process content/perform operations on it upon the event’s occurence in the parsing order.

I guess what differientiate a snippet from a plugin is the ability to listen to system events, plus the fact it can operate frontend and backend

Modules
Modules expand the core features.

Does not mean I think "CoreXt" or "CoreXtension" would be sexy...


Sorry if this is a bit abstract and/or inaccurate (no coder as you know).

I think whatever perspective we choose we should keep in mind it’s about being coherent and understood. For me, using a task based approach (what does a component do ?) is more coherent than a nature based approach (what does the component contain ? php, hmtl, js....).

Yet, it’s not easy since for each component we have different perspective :

• Scope (where is the component used ?) : frontend or/and backend ? Snippets and chunk operate frontend, Plugins both, Modules backend...
• Nature (what is the nature of the component ?) : snippets are php, chunks are html or js or css or text, plugin are php, modules are php

Anyway, here were some first thoughts about this...
But it’s bound to be inaccurate since the new core means different components, doesn’t it ?

I’ll have to catch up on this whole thread, but firstly:

I vote against any use of "Class" or "Object" within end-user names for things.

David gets it right with the task-based approach; I think the other key area is differentiation. To the non MODxer, Chunk and Snippet are interchangeable, as are Module and Plugin. But before we can look at giving clear labels to things, we need to add to David’s list two forgotten components:

Document
Possibly the biggest component of MODx, yet easy to overlook.

Template
More specifically a Document template; many snippets use chunks as templates and that’s an area of confusion.

And yes, we need some indication of the 1.0 goal in order to rename things, but then it also seems that delineating things helps firm up the 1.0 goal, and seeing how the real-world has adapted to MODx from the Tech Preview days to now is enlightening.

Example: A chunk is reusable content? So is [*content*] from a document, and many users are (via Ditto or other snippets) using variables from other documents (including TVs) in much the same way as one might expect a chunk to be used. The main reason for that is that you can edit documents and TVs in QuickEdit, and you can’t give users access to editing Chunks without giving them access to Snippets. In some cases this ends up with one TV that is used all over the site, either by inheritance or direct reference.

Also, everything is reusable, so I don’t see reusability as the point of Chunks.

No, it is in comparison with a document that the point of a Chunk becomes clear - it is a document variable without a document. So if the document is not the parent, what is? Must be the site. So: Site Variable. Give it the same powers and types as a Template Variable and you’ve got something pretty nifty.

But wait.. Chunks have two uses. Is there any benefit in being able to create a Ditto Chunk Template from an @BINDING? Probably not. But then, Ditto only uses Chunks because it’s the only thing available.

Semantically, it would be better for Ditto templates to be types of template. It would be smart if snippets could register their own Types Of Template.. and it sounds from all of Jason’s stuff like it is doable.

As for frontend/backend... Plugins work with the parser, which will ultimately be the same parser front-end and back.
Snippets can be executed after saving, so they’re not entirely frontend.

As I think Plugins and Modules are insufficiently distinct names by themselves, I’d suggest that we use the alliterative names Parser Plugins and Manager Modules (with Plugins and Modules becoming shorthand).

I would be in favour of renaming Snippets to Scripts, or possibly, under the same deal, Script Snippets.

So. To recap: the way I see things is:

Documents (as now)
Document Variables (formerly Template Variables)
Site Variables (extend main Chunks functionality)
Templates (as now)
Ditto Templates (added by snippet, take over some Chunks functionality)
Document Types (see elsewhere)
Script Snippets (formerly Snippets)
Manager Modules (formerly Modules)
Parser Plugins (formerly Plugins)
Manager Skins
Manager Shells (I guess that’s a new one)
Widgets (as now)
@ Binding (as now)

OK, so Parser Plugins is not very user-friendly, but I think it’s clearer from this that if I want to add some front-end functionality, I’m going to add a Script Snippet. There are people who will consider all add-ons to be plugins!

Oh, and just to add, if Documents becomes Resources, as stated by Jason over at http://modxcms.com/forums/index.php/topic,8548.msg61634.html#msg61634 in the Rethinking MODx thread, then the above becomes
Resources
Resource Variables
but I’m not so sure about
"Resource Types", as to me that should be "image" / "document" rather than the template-esque categorisation I had in mind.

But still, the debate on end-user terminology is meaningless without knowing how things work in the core and how they will be edited and used. Actually, I think we have to cross reference Jason’s recent words here.

Documents = Resources.
All Other Components = types of Element.

Quote from: OpenGeek at Nov 07, 2006, 12:14 PM

Here’s some glimpses at how I envision, and have implemented the simplification of terminology in my rewritten core. I’ve got it down to two basic concepts which I think would greatly simplify the learning curve of MODx...

Resources.
Documents, web links, or any other request "controller" (from MVC terminology) is going to generically be called Resources, because these are essentially virtual web resources that are accessible by a URL, or Uniform Resource Locator. Resources are assigned a base content element (see below) and can return any type of valid web content. A resource can then be as simple as a page or as complex as an Ajax or XML web services response.

Elements.
The re-usable building blocks of every resource are templates, chunks, snippets, TVs, plugins, etc. All of these become a type of Element. This is any element that defines source content and is expected to return a result when processed, be it a logical result, or content. Everything from the default content, to custom metadata, to complex TV-like controls, to PHP scripts can be attached as a Base Content Element (i.e. current MODx template, except it can be any kind of Element, including a snippet or TV) to a Resource, added to a Resource via an explicit relationship (ResourceElements), or related to any other Element (this will allow the current TV relationship directly with templates, as well as allow dependencies between all the other types of elements). Finally, consider that we can then define a class of Element that can represent permissions and is responsible for deciding if the user has permission for a particular element (piece of content or logic/behavior)...

Let me stop there, and see what kind of response this gets. There are additional concepts to talk about in regards to Elements for defining input controls and output widgets like TV’s currently allow, but I’d like to focus on validating these basic concepts in the context of this discussion first, and appreciate any of your thoughts on this, before I continue...

Woosh, I just throwed a few things to start the discussion, but I have to bow to the clarity of you posts here !

I think we’re getting somewhere.
Thanks for pointing to Jason’s post, missed that one...

Jason’s post is BIG. I think we need to see how things roll in that other thread before picking things up here.
The current terminology isn’t all that bad; the longform Parser Plugins, Manager Modules, Script Snippets etc may serve as a stopgap to something, but really we need to figure out where everything is going to be in 1.0 and start to rename things to fit that vision. If something changes drastically, I think a new name is helpful.

Chunks might end up being called Global HTML Element. Snippets may end up as Script Elements (indeed, quite possibly Global Script Elements and Resource Script Element).

Hmmn. I’m not happy with Resource. I don’t think it works as a prefix the same way that Document does. I mean, currently snippets ARE resources. So while a snippet that was specifically tied to a resource is as logically a Resource Script Element as a Document Script Element would be, it just seems odd.

More to the point, if we’re heading in that direction, 0.9.5 needs a menu title change..

Quote from: PaulGregory at Nov 07, 2006, 02:21 PM

Hmmn. I’m not happy with Resource. I don’t think it works as a prefix the same way that Document does. I mean, currently snippets ARE resources. So while a snippet that was specifically tied to a resource is as logically a Resource Script Element as a Document Script Element would be, it just seems odd.

More to the point, if we’re heading in that direction, 0.9.5 needs a menu title change..

I agree, 0.9.5 needs to get rid of any reference that links the idea of Resources to the various soon to be Elements, and Resources has always been the wrong wording in my mind for the various components that make up MODx add-ons.

But a Resource is accepted terminology for anything accessible via URL though, and I am pretty inflexible with changing Resource to anything else; after all an AjaxDocument or SOAPDocument is a misnomer, and would be more confusing in the long run; Documents/Pages are only a single type of web resource that can be served by URL and constructed using MODx Elements, and I don’t want the concept to be masked with improper semantics.