Encouraging Recommended Snippet Parameter Conventions

I've written a blog about Unexceptional 5 Parameters that All MODX's Snippets Should Have.
In summary, there are:

• &toArray
• &tpl
• &css
• &js
• &toPlaceholder

There are too many snippet parameters out there to be remembered, I have an idea about making a convention to make the developer's life easier.

Tell me what you think.

cheers.

kind of a standard for snippet calls? like the idea.

I like it too, although I sometimes separate the css and js properties (they're not called parameters any more, BTW) to give users more flexibility with their locations like this:

• &cssPath
• &cssFile
• &jsPath
• &jsFile

------------------------------------------------------------------------------------------
PLEASE, PLEASE specify the version of MODX you are using.
MODX info for everyone: http://bobsguides.com/modx.html

I've thought about this over the years and have made the exact same type of proposal before and while this would be helpful for some it will also reach it's possible limits very fast. It would be nice if some used consistent names like &tpl where there is a single output wrapper for he Snippet, this doesn't work with multi part snippet output like in the case of Wayfinder or Quip.

To me we are trying to solve two problems: one remembering what properties are available to a snippet and 2 to avoid confusion between the two. The first can be solved by the Snippet developer creating property sets for the Snippet that will allow users to drag and drop snippets into views be they templates or resources etc. This enables people to be prompted to fill out the snippet properties in the form as needed. Secondly, and more importantly, consistent documentation with all properties listed and organized with complete descriptions and where possible examples, especially where it comes to output wrappers.

There may be other ways to make this easier to remember and use but MODX properties are just like any other programming language variable and the variable name is entirely up to the developer and related to the specific problem the snippet (or whatever, since all elements can have Properties) is there to solve.

I will say the most frustrating thing for me is to go to a new snippet and the only place the Properties can be found is in the code itself and second to that, in the property set but having little or no documentation.

I wonder if a better standard would be for more complete descriptions, examples and properties documentation with an easy to access reference while working on your projects.

Awesome!

I believe what we want to achieve is some general "properties" (thanks to Bob for the reminder) that basically are used for the minimum output.
That's why I only proposed those 5 minimal properties (I welcome more suggestions).
Regarding to template and wrapper templates, let's agree on something.
&tpl = wrapper?
or &tplWrapper = wrapper, and &tplRow = row?
or &wrapperTpl, and &rowTpl ?

As Jay said, we can urge the developers to fulfill the completeness when the snippet is released, eg: properties when it's built, the documentation when it's released, etc etc.

Because there is no standard, then there is no obligation.

MODX even can add the required checkboxes to the extra page when developers want to upload their new packages, to remind about this standard. eg:

[ ] Completed properties
[ ] Documentation : [....................................]
[ ] Example page : [....................................]

At least, we have to start something here.

I agree that it's up to the developer. But when people keep asking about MODX's standard (including docs and examples), then the Open Source community behind and around MODX should build the same standard.

I just realized this MODX's new tagline:

creative freedom

But it doesn't mean that the uploaded packages to the MODX's extra repository loose their control.
If developers want to join the collaboration, there is a standard should be follow.

"With great power comes great responsibility." This is my gift, my curse. (Peter Parker)

So, it's our gift, and our curse.

May be a set of star ratings can also be the standards:
[**] examples
[****] documentation
[***] properties

Hmm....
Is there any person that's interested to review MODX's extras?
Not MODX, but the extras.

Here are some semi-random thoughts on this...

I personally don't think we should enforce property naming standards. It is the same idea as enforcing class name and class namespacing in CSS when building MODX websites. It should be up to the individual developer. Could we have recommended naming conventions? Sure. Should we document those? Absolutely. Should we show examples of doing it right? Without question. Not to say we shouldn't help add-on contributors to make better more useful add-ons but for the sake of the very few properties that might be common across the ecosystem I think it will be a wasted effort.

What makes sense to me is to develop a style manual that shows what makes a high quality Snippet from Property naming (in a way that makes sense and that will immediately bring meaning to those using it), shows how to include a properly defined property set, shows what constitutes a good description and examples of how to show excellent examples. This should not be the same as the developing HTML5 spec (which won't be official until 2014-15) but more like the Elements of Style: A set of ideals and suggestions but ultimately it's up to the author to determine course and consumer of that output to determine it's worth.

I've also mentioned a number of times, there are folks who build add-ons for the express purpose of releasing them to the MODX ecosystem. And then there is the majority of add-ons that are built in the midst of a project that the dev felt might be useful and the wanted to share and so they do. I don't think we're at the stage of saying no to people who want to share their add-on because it doesn't meet the standards someone else sees fit for the best add-ons. See below for my thoughts on your rating suggestions.

It would be cool if busy add-on devs could release an add-on but flag it that it's up for adoption or in need of contribs to help bring it up to a higher level of quality.

Not having access to clear information of the snippet and its use is far worse than the idiosyncrasies between naming of properties where one developer might use "levels" and another "depth" both could mean the same thing but no one is better than the other and making one a standard to me is missing the point.

I really love the ideas of reviews for facets of the add-on you suggest @goldsky a sort of TripAdvisor for Extras rating on a set of predefined attributes as you mentioned. I think just making it possible to rate and review add-ons will help improve the overall useful ness and in addition increase the profile of incredibly useful add-ons that others might not know of but rate extremely high.


Improving /extras/ and Package Management and possibly allowing somehow to link directly to add-on documentation from inside the MODX manager via right click on the snippet or some reasonalble shortcut that doesn't require googling 20 times every time you want to use a snippet you don't use frequently.

It would be cool if busy add-on devs could release an add-on but flag it that it's up for adoption or in need of contribs to help bring it up to a higher level of quality.

This is a great idea, IMO. I think many of us see nice extras that are kind of thrown together and semi-undocumented but hesitate to offend the original developer by fixing them up.


I think the ratings are a great idea too. Some possible rating types:

Documentation and tutorials
Ease of Installation
Reliabliity
Code quality
Usefulness
Overall value

The links to Docs and GitHub are already there in Package Management if the author has done the readme.txt file properly.

------------------------------------------------------------------------------------------
PLEASE, PLEASE specify the version of MODX you are using.
MODX info for everyone: http://bobsguides.com/modx.html

Quote from: smashingred at May 17, 2012, 08:17 AM

Not having access to clear information of the snippet and its use is far worse than the idiosyncrasies between naming of properties where one developer might use "levels" and another "depth" both could mean the same thing but no one is better than the other and making one a standard to me is missing the point.

Actually, this is the reason why I encourage the property naming standard.

Imagine all the confusion we have to deal with because of this, and just like you mentioned, we have to google the DOCS countless just to find the correct parameters for the particular snippet.
We have more unnecessary clone properties other than those levels and depth, like template directives. @CHUNK/CHUNK/modChunk ? @CODE/@INLINE/inline ? Do we really need to define the &tplPath?

I agree the importance of the DOC+examples.
Also agree that for some reason, as you mentioned, the devs don't give a complete documentation for a simple snippet (btw, flagging is a great idea, leaving a notification to other devs for a help).
But if it happens and luckily they use the same property's names, I bet the other users don't have to wonder what their meanings are, what the property names are, how to write it down (camelCase, PascalCase, with_underscore?). Even for the snippet's names, eg: getResources/getPage, UltimateParent/FormIt, simplx_rpc. Is it good to use number in it? eg: [!easy2!]

Another interesting thing is that they are all written in ASCII (I could not imagine to have a [ [галерея]] snippet, including the non-ASCII properties).
But is it wrong to have one? No, if the user target is indeed only for that particular area, like Tax counter or ZIP look up.
If that's only a technical reason, no problem. Let's say that on the standard.
If one day someone finds a work around on that matter, let's improve the standard again.
(AFAIK, some people in asia countries don't use english not because of the ability, but the accessibility. Please don't say MODX ignores them. They are a good market.)

It's not about judging which one is better, but it's about to make an agreement to use the same property name for the same purpose. It's what a standard stands for. An agreement.

Just like you have the left steering wheel cars in your country, and we have the right steering wheel in here. Both are correct, because they are applied to each road standard.
We can choose to use different one, with an awareness that we would have difficulties for the position dependence, like paying the toll gate.


@Bob,
Do you care to elaborate more about the Code Quality?
AFAIK, some people stand for a different code styling. Is that the case?
Btw, that's a people like you who has a great reputation on MODX usability, but not in the MODX's core team inner circle, can start a valid and independent review (although it should be opened for more responses).

At the end,
If the SNIPPET will be a subject for the certificate examination, then it is no doubt that we must have a BASIC STANDARD for that, including the docs and proper examples like @Jay said.
Otherwise, I'm saying it frankly, it's only a joke.
I will not take any exam based on a loose subject.
I don't mind to take the core questions, as it only has one standard.
Please see this one as a whole picture, not a subjective opinion. [ed. note: goldsky last edited this post 14 years, 4 months ago.]

Quote from: goldsky at May 17, 2012, 09:49 PM

@Bob,
Do you care to elaborate more about the Code Quality?
AFAIK, some people stand for a different code styling. Is that the case?
Btw, that's a people like you who has a great reputation on MODX usability, but not in the MODX's core team inner circle, can start a valid and independent review (although it should be opened for more responses).

Thanks for the compliment. I was just tossing out ideas. I didn't have anything specific in mind. I know how I like my code to look, and AFAIK, almost all MODX code is in K&R style. I would hesitate to dictate code standards for others, though.

With code quality, I was thinking that it would be a rating of the readability, comments, correctness, and efficiency of the code. The more I think about it, though, a code quality rating probably doesn't make sense because so many users wouldn't be qualified to give such a rating, but the system would force them to do so. Unlike you and me, many users of MODX extras will never even look at the code.


------------------------------------------------------------------------------------------
PLEASE, PLEASE specify the version of MODX you are using.
MODX info for everyone: http://bobsguides.com/modx.html