Terms for MODx things in Revolution?

I’ve been working on a style guide for my book (and, hopefully, also for the MODx docs and promotional materials).

I found myself stumbling on the definitions of the following terms in MODx Revolution:

add-on
component
add-on component
asset
element
package
parameter
property
file
resource
document
page/Web page

One of the most difficult parts of learning MODx is getting handle on the terminology. I’m wondering if we can cut this list down somewhat or at least agree on the definitions.

If add-on, component, and add-on component are truly synonyms, we should pick one and ditch the rest. Presumably, we’d keep component based on the dir. name.

Let me throw these out for discussion. I don’t know if they work or not, but it will be a starting point:

• Add-on (I’m suggesting we dump this one).


• Add-on component (ditched as redundant).


• Asset - Anything installed in the MODx /assets directory. Includes components, libraries, image files, CSS files, JS files (what else?).


• Component - A collection of one or more assets (or elements?) that meet a particular need. (Usually installed in a single subdirectory under assets/components?)


• Element - A single Template, Template Variable, Chunk, Snippet, Plugin, or Category visible in the Manager Elements tree.


• Package - A collection of one or more assets or components that meet a particular need. Usually installed in assets/components using the Package Installer in the Manager.
• System Setting - A single variable visible in the Manager System Settings grid and available site-wide.
• Property Set - A set of variables used for a particular purpose. These are like System Settings, but are only available to the individual elements they are attached to. Property Sets can be attached to more than one element.


• Property - a single member of a property set.


• Category - an optional name that can be attached to elements to organize them in the Elements tree in the Manager.


• Parameter - a property’s value sent individually in a snippet call.



• File - a single physical file anywhere in the MODx site.


• Resource - a single document, Web link or Symlink visible in the Manager Resource tree.


• Document - a document-type resource.


• Page/Web page - A single web page of a MODx site rendered in a browser.
• Weblink - A traditional hyperlink to any URL, inside or outside the MODx site.
• Symlink - A reference to a local MODx document. The document’s content will replace the symlink.
• Static Resource - A reference to a file on the MODx site. The reference will be replaced by the contents of the file with no MODx tag processing.

It would be great to make this heirarchical or at least get rid of the many-to-many relationships, but I don’t see any way to do it.
One package can contain multiple components and I think one component could require multiple packages (e.g. SPForm + Captcha).

BTW, I don’t think always using "resource" instead of "document" when referring to a document in the Manager is a good idea. I don’t see what it gains us and it leads to a really confusing situation in the Manager menu system:

Resources -> Create
Resource
Web link
Symlink
Static Resource

If web links, symlinks and static resources are resources, they should appear again under "Resource" leading to an infinitely nested menu.

If it’s a resource and it’s not a web link, symlink, or static resource, isn’t it a document? If so, let’s call it that, at least in the Manager.

The plan, I believe, is to eventually allow parsing static resources. Why ditch "add-ons" (3rd party extras added to a MODx installation such as menu builders, form process and any other extra functionality)? The reason I’m in favor of keeping it is that it makes a bit more clear the 3rd party nature of such elements/assets. I tend to think "Assets" could lead to confusion too, since they can technically be in any directory you choose.

On that front, and to be in line with the new marketing/support site, could "components" be simply "extras"?

Likewise "Package" definition needs to be expanded in scope too since it can contain DB info that’s loaded and also MODx docs/weblinks/symlinks/static resources. On that note, I like calling web pages web pages. That makes more sense (under the Resources menu, which likewise makes sense). "Document" is probably more correct since it can also output XML page, CSS file, JS file and other formats we’ve not thought of yet.

I’m all for a glossary, thanks Bob. I’m also all for a file system explanation of the layout in Revo. And pictures. Definitely pretty pictures.

All of the concepts in Revolution have already been described in detail and with concise terminology in various places throughout the forums here (see the Roadmap especially). If you need me to provide a single glossary of the Revolution code and the concepts that have gone into it, I will be glad to do so, along with notes on how each was derived from and is different than the more familiar and already accepted concepts in Evolution. Most of the confusion comes from everyone reverting to the familiar terminology when concepts seem the same as they ever were on the surface, but are handled differently in the code. If we can get the new points to arise out of the old, and show the full relation between them, well, that should be the goal anyway. I’d really like to see us focus on documenting this stuff the way it was intended (i.e. ask questions if you don’t understand the concepts or intentions) rather than arguing about terminology. Once we all understand it, then we can work on building consensus to rename things if necessary.

This is the most important part of Revolution acceptance, being able to accurately convey the structure of the code and the capabilities provided by the product. If developers cannot recognize the code architecture and be able to easily relate it to user experience in MODx, we have an epic fail.

As for Extras, well, this is synonymous with Components, which are generic terms for anything you can install (manually or via a package) in the MODx framework. These are then divided into Add-Ons, components that do not extend or change the behavior of the core, and Extensions, which do extend or change the core.

Then it’s Web Resources (Documents, Weblinks, Symlinks, Static, etc.) and Content Elements (Templates, Chunks, Snippets, TVs, Plugins, etc.). New are Properties and PropertySets, though Properties are just what we’ve always referred to as snippet/plugin "parameters" expanded to apply to all Content Elements. Then there are Settings, for System, Context, and User.

And I’m not going to go through the Transport Package arguments again. If there are still questions or issues there, let’s discuss in the thread focusing on that.

Quote from: OpenGeek at Feb 22, 2009, 11:54 AM

All of the concepts in Revolution have already been described in detail and with concise terminology in various places throughout the forums here (see the Roadmap especially).  If you need me to provide a single glossary of the Revolution code and the concepts that have gone into it, I will be glad to do so, along with notes on how each was derived from and is different than the more familiar and already accepted concepts in Evolution.

This is central to my point. The concepts and terms have in many cases been "described" but not "defined."  Huge difference, IMO.  For example, the description you give below of Components ["anything you can install (manually or via a package) in the MODx framework"] would include everything from huge projects like TInyMCE down to a single new system setting, a document alias, or a chunk that holds the Webmaster’s name. I don’t mean to be difficult, but if those aren’t all components (and the fact that I don’t know for sure tells us something), we need to tighten the definition. 

Similarly, Addons [components that do not extend or change the behavior of the core] will be hard to get a handle on. IMO, most users who read this don’t know which of the things they see on the screen are produced by core behaviors and which aren’t. And you could argue that everything you do in MODx changes the behavior of the core in some way since it changes what the core puts on the screen. By that standard, there would be no add-ons (probably not what we had in mind with the term).

Please don’t misunderstand my post. My *main* goal was to get clear definitions of the terms, not to change or delete them.  The inaccuracy of my definitions reflects not a desire to change things but:  a) my own density and b) the fact that there is no single place to look for definitions of the terms. I’ve actually been working with components, add-ons, extras, etc. for some time and you can see how bad my grasp of the terms is from my definitions above and I’ve read every Forum post that describes them.

A comprehensive glossary would be a tremendous asset (especially for anyone writing a book on MODx).  I absolutely need to know exactly what the terms mean, whether they’re capitalized, and things like whether PropertySet is one word or two. 

I’d really like to see us focus on documenting this stuff the way it was intended (i.e. ask questions if you don’t understand the concepts or intentions) rather than arguing about terminology.  Once we all understand it, then we can work on building consensus to rename things if necessary.

This is the most important part of Revolution acceptance, being able to accurately convey the structure of the code and the capabilities provided by the product.  If developers cannot recognize the code architecture and be able to easily relate it to user experience in MODx, we have an epic fail.

Agreed (and mainly why I started this thread).

As for Extras, well, this is synonymous with Components, which are generic terms for anything you can install (manually or via a package) in the MODx framework.  These are then divided into Add-Ons, components that do not extend or change the behavior of the core, and Extensions, which do extend or change the core.

Then it’s Web Resources (Documents, Weblinks, Symlinks, Static, etc.) and Content Elements (Templates, Chunks, Snippets, TVs, Plugins, etc.).  New are Properties and PropertySets, though Properties are just what we’ve always referred to as snippet/plugin "parameters" expanded to apply to all Content Elements.  Then there are Settings, for System, Context, and User.

And I’m not going to go through the Transport Package arguments again.  If there are still questions or issues there, let’s discuss in the thread focusing on that.

LOL!  No argument here . . . I’ve come to love the Transport Package terminology.

@Jason - Don’t miss miss my post above this one.

@Ryan - If Components = Extras, we should pick one. I’d vote for Components since I’ve never seen "Extras" before your post.

I thought I’d try again and give Jason a head start on a Glossary. I’m not prepared to defend any of these, just putting down my current understanding of things (and cursing BB code).

[table]
[tr][td]Acceptable[/td][td]Unacceptable[/td][td]Definition and notes[/td][/tr]
[tr][td]Add-on[/td][td]addon[/td][td]A MODx Component that does not change the behavior of the core; Package is preferred if discussing Package Management[/td][/tr]
[tr][td]Administrator[/td][td]administrator[/td][td]Always capitalized when referring to the MODx User level or a Back-end Administrator[/td][/tr]
[tr][td]asset[/td][td][/td][td]A single piece of a Component that is stored in the file system. Usually in the /assets directory or a location defined by MODX_ASSETS_PATH; includes libraries, image files, CSS files, JavaScript files, class files, php include files, etc.[/td][/tr]
[tr][td]article[/td][td][/td][td]Not a MODx term[/td][/tr]
[tr][td]Back-end[/td][td]backend[/td][td]The MODx Manager – always capitalized[/td][/tr]
[tr][td]backup and back up[/td][td][/td][td]Back up is the verb form, as in "always back up your site;" otherwise, use “backup” as in "don’t forget to keep a site backup .zip file"[/td][/tr]
[tr][td]Category[/td][td][/td][td]An optional name that can be attached to elements to organize them in the Elements Tree in the MODx Manager; always capitalized when referring to Element Categories set in the Manager[/td][/tr]
[tr][td]command[/td][td]comand[/td][td]Double “m”[/td][/tr]
[tr][td]checkbox[/td][td]check box[/td][td]Always a single word[/td][/tr]
[tr][td]Component[/td][td][/td][td] A MODx Add-on or Extension;  always capitalized[/td][/tr]
[tr][td]Context[/td][td][/td][td]A collection of settings that control a particular MODx site or Manager instance; a site can have multiple contexts and a context can be shared by multiple sites[/td][/tr]
[tr][td]Context Setting[/td][td][/td][td]A single variable that controls a Context and that is available only in a specific Context or Contexts[/td][/tr]
[tr][td]cPanel[/td][td]Cpanel, CPanel[/td][/tr]
[tr][td]CSS[/td][td]css[/td][td]Always capitalize except in code or when a file extension[/td][/tr]
[tr][td]database[/td][td]data base[/td][td]Always one word[/td][/tr]
[tr][td]dial-up[/td][td]dialup dial up[/td][td]Always hyphenated[/td][/tr]
[tr][td]Document[/td][td][/td][td]A document-type Resource visible in the MODx Resource Tree[/td][/tr]
[tr][td]Document Id, Document Identifier[/td][td][/td][td]An unique integer identifying a specific MODx Document (also called a Document Identifier, Resource Id or Resource Identifier); always capitalized; visible in parentheses next to the Document name in the MODx Resource Tree[/td][/tr]
[tr][td]Element[/td][td][/td][td]A single Template, Template Variable, Chunk, Snippet, Plugin, or Category visible in the Manager Elements Tree; always capitalized when referring to MODx Elements[/td][/tr]
[tr][td]e-mail[/td][td]email[/td][td]E-mail at the beginning of a sentence; e-mail otherwise[/td][/tr]
[tr][td]Extension, Core Extension[/td][td][/td][td]A MODx Component that changes the behavior of the core; Package is preferred if discussing Package Management[/td][/tr]
[tr][td]File[/td][td][/td][td]A single physical file anywhere in the MODx site; capitalized only when referring to a specific MODx Menu or Menu choice[/td][/tr]
[tr][td]file name[/td][td]filename[/td][td]Two words except in code[/td][/tr]
[tr][td]File Resolver[/td][td][/td][td]Part of a Transport Package that copies files from the package to the appropriate location at the site[/td][/tr]
[tr][td]Front-end[/td][td]frontend, Frontend[/td][td]The MODx site as seen by the public or logged-in web users (i.e. not the Manager); always hyphenated and capitalized[/td][/tr]
[tr][td]gateway[/td][td]gate way[/td][td]Always one word[/td][/tr]
[tr][td]GPL, GPL License[/td][td][/td][td]The GNU General Public License; a widely used free software license[/td][/tr]
[tr][td]GUI[/td][td][/td][td]Graphical user interface; any user interface that relies primarily on visual effects and mouse actions rather than the keyboard and text[/td][/tr]
[tr][td]hard disk[/td][td]hard-disk, harddisk[/td][td]Two words; no hyphenation[/td][/tr]
[tr][td]hardware[/td][td]hard-ware[/td][td]Always one word[/td][/tr]
[tr][td]home page[/td][td]homepage[/td][td]The page accesses by yoursite.com. AKA the MODx “Site Start;” always two words[/td][/tr]
[tr][td]HTML[/td][td]HTM html[/td][td]Always capitalized, except in code or when a file extension[/td][/tr]
[tr][td]JavaScript[/td][td]javascript Java Script[/td][td]One word but with the J and S capitalized[/td][/tr]
[tr][td]keyboard[/td][td]key board[/td][td]Always one word[/td][/tr]
[tr][td]Lexicon[/td][td][/td][td]A set of language strings used in the Front-end or Back-end of a MODx site; allows MODx to be deployed in multiple languages[/td][/tr]
[tr][td]Lexicon Topic[/td][td][/td][td]A subset of language strings from a particular Lexicon[/td][/tr]
[tr][td]license[/td][td]licence, lisence[/td][td]Capitalized when referring to the GPL License, BSD License, etc.[/td][/tr]
[tr][td]login, logout;logon, logoff[/td][td][/td][td]The noun form; always one word, one “g” as in “enter your login information;” login and logout are preferred[/td][/tr]
[tr][td]log in, log out; log on, log off[/td][td][/td][td]The verb form for the act of logging in to or out of a Web site; log in and log out are preferred; only capitalized at the beginning of a sentence[/td][/tr]
[tr][td]maintenance[/td][td]maintainence, maintanence, maintanance[/td][/tr]
[tr][td]Manager[/td][td]manager[/td][td]Always capitalized when referring to the MODx Manager interface or to Manager Users[/td][/tr]
[tr][td]Manager User[/td][td]manager user[/td][td]Always capitalized[/td][/tr]
[tr][td]Menu[/td][td]menu[/td][td]Always capitalized when referring to a specific MODx Menu[/td][/tr]
[tr][td]Menu Item[/td][td]menu item[/td][td]Two words and capitalized when referring to a specific item on a MODx menu[/td][/tr]
[tr][td]metadata[/td][td]meta data[/td][td]Always one word[/td][/tr]
[tr][td]Module[/td][td]module[/td][td]Always capitalized when referring to a MODx Module or to MODx Modules in general[/td][/tr]
[tr][td]MODx[/td][td][/td][td]The MODx product; always in this form in written text; pronounced “MOD-ex” with the “O” as in “body”[/td][/tr]
[tr][td]MODX Core[/td][td][/td][td]The files residing in the MODx /core directory containing the basic functions for supporting a MODx site[/td][/tr]
[tr][td]MODx Tag[/td][td][/td][td]A MODx Element, Resource, link, or Placeholder as it appears in the code of a Document or Element to be read by the MODx Parser[/td][/tr]
[tr][td]MODx Parser[/td][td][/td][td]The MODx engine that parses input to replace MODx Tags with the appropriate content[/td][/tr]
[tr][td]multitasking[/td][td]multi-tasking multi tasking[/td][td]Always one word[/td][/tr]
[tr][td]MySQL[/td][td]mysql MYSQL[/td][/tr]
[tr][td]News Feed[/td][td]newsfeed Newsfeed[/td][td]Two words, always capitalize when referring to a specific News Feed[/td][/tr]
[tr][td]OK[/td][td]Ok, ok[/td][td]capitalize both letters[/td][/tr]
[tr][td]online[/td][td]on-line on line[/td][td]One word[/td][/tr]
[tr][td]Open Source (OS)[/td][td]open source[/td][td]Two words, both capitalized[/td][/tr]
[tr][td]overwrite[/td][td]over write over-write[/td][td]Always one word[/td][/tr]
[tr][td]Package, Transport Package[/td][td][/td][td]A collection of one or more assets or components that meet a particular need; usually installed in assets/components using the Package Installer in the Manager; always capitalized when referring to MODx Packages[/td][/tr]
[tr][td]Parameter[/td][td][/td][td]A property’s value sent individually in a snippet call preceded by an ampersand (&); always capitalized when referring to a MODx parameter[/td][/tr]
[tr][td]password[/td][td]pass word[/td][td]Always one word[/td][/tr]
[tr][td]PHP[/td][td]php[/td][td]Always capitalize except in code or as a file extension[/td][/tr]
[tr][td]platform[/td][td][/td][td]Always one word[/td][/tr]
[tr][td]Plugin(s)[/td][td][/td][td]One word, always capitalize when referring to the MODx Plugins[/td][/tr]
[tr][td]PostScript[/td][td]Post Script post-script[/td][td]One word; capitalize P and S[/td][/tr]
[tr][td]privilege[/td][td]privilage, privledge,[/td][td]Spelled with –ege at the end[/td][/tr]
[tr][td]proofread[/td][td]proof-read, proofed, proof read[/td][td]Always one word[/td][/tr]
[tr][td]Property[/td][td][/td][td]A single member of a MODX Property Set; always capitalized when referring to a MODx Property[/td][/tr]
[tr][td]Property Set[/td][td][/td][td]A set of variables used for a particular purpose; these are like System Settings, but are only available to the individual elements they are attached to; property Sets can be attached to more than one element; two words except in code, both capitalized when referring to a MODx Property Set[/td][/tr]
[tr][td]questionnaire[/td][td]questionare[/td][td]Spell with a double n and end with –aire[/td][/tr]
[tr][td]Resource, Web Resource[/td][td][/td][td]A single Document, Weblink, Symlink, or Static Resource visible in the Manager Resource Tree; always capitalized when referring to MODx Resources[/td][/tr]
[tr][td]Resource Id, Resource Identifier[/td][td][/td][td]An integer uniquely identifying a MODx Resource[/td][/tr]
[tr][td]Resolver[/td][td][/td][td]Part of a Transport Package; may be a file resolver or a script resolver; capitalized[/td][/tr]
[tr][td]Resource Tree[/td][td][/td][td]The hierarchical list of MODx Resources visible on the left side of the MODx Manager[/td][/tr]
[tr][td]Script Resolver[/td][td][/td][td]Part of a Transport Package that executes a PHP script written by the Package developer, sometimes in response to user input.[/td][/tr]
[tr][td]Site Start[/td][td][/td][td]The home page of a MODx site; set via the site_start System Setting[/td][/tr]
[tr][td]software[/td][td]soft ware soft-ware[/td][td]Always one word[/td][/tr]
[tr][td]source code[/td][td]sourcecode[/td][td]Always two words[/td][/tr]
[tr][td]Static Resource[/td][td][/td][td]A MODx Resource referring to a file on the MODx site; the reference is replaced by the contents of the file with no MODx Tag processing[/td][/tr]
[tr][td]style sheet[/td][td]stylesheet style-sheet[/td][td]Two words no hyphen[/td][/tr]
[tr][td]subdirectory[/td][td]sub-directory sub directory[/td][td]One word[/td][/tr]
[tr][td]Symlink[/td][td][/td][td]A MODx Resource which is a reference to a local MODx document; the document’s content will replace the Symlink[/td][/tr]
[tr][td]System Setting[/td][td][/td][td]A single variable visible in the Manager System Settings grid and available site-wide; both words capitalized[/td][/tr]
[tr][td]Tab[/td][td][/td][td]Capitalized when referring to a specific Tab in the Manager[/td][/tr]
[tr][td]Tag[/td][td][/td][td](See MODx tag)[/td][/tr]
[tr][td]toolbar[/td][td]tool bar tool-bar[/td][td]Always one word[/td][/tr]
[tr][td]Transport Package[/td][td][/td][td]A collection of MODx Components and/or Resources packaged for automatic installation to a MODx site[/td][/tr]
[tr][td]URL[/td][td]Url url[/td][td]Capitalized except in code[/td][/tr]
[tr][td]User[/td][td]user[/td][td]When referring to a specific User or type of user in MODx, always capitalized[/td][/tr]
[tr][td]User Setting[/td][td][/td][td]A variable, usually set in the Manager, that is linked to a single User.[/td][/tr]
[tr][td]Vehicle[/td][td]vehical[/td][td]Part of a Transport Package[/td][/tr]
[tr][td]Web[/td][td]web[/td][td]Capitalized except when using to  the things spiders build[/td][/tr]
[tr][td]Weblink[/td][td][/td][td]A MODx Resource referring to a traditional hyperlink to any URL, inside or outside the MODx site; always one word and capitalized when referring to a MODx Weblink; Web link when referring to hyperlinks in general[/td][/tr]
[tr][td]Web page[/td][td][/td][td]A single Web page of a MODx site rendered in a browser; often a single Document but not always[/td][/tr]
[tr][td]Web site[/td][td]website Web Site web site[/td][td]Web is short for World Wide Web, a proper noun[/td][/tr]
[tr][td]World Wide Web (WWW)[/td][td]Worldwide Web[/td][td]Capitalize, as it is a proper noun; three separate words; capitalize the abbreviation (except in URL’s)[/td][/tr]
[/table]

Note:

http://svn.modxcms.com/docs/display/revolution/Glossary+of+Revolution+Terms

has been up for a while. We can (and should) easily expand this.

I’ll chime in more on terminology soon, as well as provide you some definitions, but wanted to get this link out there.

Thanks for reminding me. Three questions:

1. Isn’t a Validator a third kind of Resolver? Or have we separated it because it’s a pre-processor?

2. In our discussions, we’ve been using both Vehicle and Transport Vehicle. I’d prefer having Transport Vehicle as the Glossary entry with AKA Vehicle. When the Glossary gets bigger, it will put the Transport stuff together. Ditto for Transport Vehicle Resolver and Transport Vehicle Validator.

3. If the Validator returns false, is it the Vehicle that aborts or the whole package?

Quote from: BobRay at Feb 23, 2009, 01:07 AM

1. Isn’t a Validator a third kind of Resolver? Or have we separated it because it’s a pre-processor?

Separated; pre-processor with it’s own types...

Quote from: BobRay at Feb 23, 2009, 01:07 AM

2. In our discussions, we’ve been using both Vehicle and Transport Vehicle. I’d prefer having Transport Vehicle as the Glossary entry with AKA Vehicle. When the Glossary gets bigger, it will put the Transport stuff together. Ditto for Transport Vehicle Resolver and Transport Vehicle Validator.

xPDOVehicle and xPDOTransport are the classes, and I refer to them as Transports and Vehicles. You can add Transport for clarity if you want, but I think it’s good that someone knows what Vehicle generally means in the MODx paradigm. Similar issue with (Web) Resources and (Content) Elements, maybe even (Content) Tags. Short and long-forms will be used in speaking of these things...

Quote from: BobRay at Feb 23, 2009, 01:07 AM

3. If the Validator returns false, is it the Vehicle that aborts or the whole package?

Just the vehicle; handling dependencies between multiple vehicles in a package is the responsibility of the builder via the Validator scripts, etc. Keep in mind, this behavior is determined by the Vehicle class implementation and could be modified or extended by providing custom Vehicle classes.

All,

I’ve updated the Glossary page with some more correct terminology; we’ll further this as we get nearer to beta.

http://svn.modxcms.com/docs/display/revolution/Glossary+of+Revolution+Terms

Quote from: OpenGeek at Feb 23, 2009, 08:03 AM

xPDOVehicle and xPDOTransport are the classes, and I refer to them as Transports and Vehicles. You can add Transport for clarity if you want, but I think it’s good that someone knows what Vehicle generally means in the MODx paradigm. Similar issue with (Web) Resources and (Content) Elements, maybe even (Content) Tags. Short and long-forms will be used in speaking of these things...

What do you think of changing the Manager menu labels to Web Resources and Content Elements?