Bug In Adobe Documentation: Getting Variables with Period References

[Homestar9]

There appears to be a significant bug in Adobe's ColdFusion Documentation on getting variables with period references.

Under the "getting a variable" heading it shows the following sample code:

<cfoutput>myVar.a.b is: #Variables["myVar.a.b"]#</cfoutput>

However, you can't reference a struct key like that in any version of ACF.  Here's a snippet that will throw an error every time you try to execute it (change the server to try different versions).

Here's the code:

<cfscript>
variables.myVar.a.b = "apple";
writeDump( variables[ "myVar.a.b" ] );
</cfscript>

Oddly enough, I feel like CFML should work as the documentation describes.  It is too bad that it does not.

[Priyank Shrivastava.]

Hi,

I will take a look and log a bug with documentation if it needed correction.

[Charlie Arehart · Accepted solution]

Homestar9, while we await Priyank's further assessment of the docs, I'll assert that things are actually partly right and partly wrong. As is often the case with the CF docs, especially larger pages like that, they may reflect changes made over the years--both in CF and by different contributors to the docs--which may not always be as well-reconciled as they should be.

So first, it's not really right to say that "you can't reference a struct key like that in any version of ACF", when you show the use of the code:

<cfoutput>myVar.a.b is: #Variables["myVar.a.b"]#</cfoutput>

In that I mean you really CAN reference "a struct key" like that, if in this case the struct being referred to is the variables scope itself, which (like all scopes) can indeed be treated like a struct. It just depends on how one was setting the variables. For example, if one had done this (as tags or script):

variables["myVar.a.b"]="apple"

That would indeed have created a variable of that name (in quotes), and so the code above would "work".

Of course, your code shows using this instead:

variables.myVar.a.b = "apple"

And in that case, as the docs there do explain correctly, that would create a struct of the name myvar, with a struct of the name a, with a key of b. And so perhaps you may have meant "you can't refer to myvar that way, if it is a struct", and that is indeed true.

FWIW, it goes on to note that with scopes like cookie or client, you don't even need the quote around the variable name (when set), so this example of using ["myvar.a.b"] works also (reverting to a variant of their tag-based example):

<cfset cookie.myVar.a.b = "This is a test">
<cfoutput>#cookie["myvar.a.b"]#</cfoutput>

And note that they don't actually show trying to output variables["myvar.a.b"] on the page. Instead they show client["myvar.a.b"] (which is out of the blue, since the example above didn't set that). If they HAD shown your code, that would indeed be wrong.

I know all this could seem a quibble. But since part of the page was talking about "variables with periods in the name", there are indeed these differences worth distinguishing, there and in any assertions about what's there. 🙂

All that said, I'm agreeeing that the page is a bit of a mess there, with inconsistencies in some other wording and examples. And I agree that a reader could be led to make mistakes, so good on you for pointing it out.

Again, hopefully Priyank will be able to get things improved.

[Homestar9]

Hi Charlie,

You're totally right. I assumed that section was referring to `variables.myVar.a.b` as a path of nested struct keys and not a single key named `myVar.a.b`.    I think with a little cleaning up and expanding on the sample code, Adobe could make the explanation a little clearer.  The first thing I think of when I see period notation like that is that the value represents a nested struct - but maybe that's just me.

[Saurav_Ghosh]

Hi Charlie,

Thanks for the clarification. I'd like to fix this page with better samples. Could you please recommend a few changes to this page? Also, I'd like to update the content accordingly. The samples below will also be updated:

<cfscript>

variables["myVar.a.b"]="apple"

writeOutput(myVar.a.b)

writeDump(myVar.a.b)

</cfscript>

<cfset cookie.myVar.a.b = "This is a test">
<cfoutput>#cookie["myvar.a.b"]#</cfoutput>

<cfoutput>myVar.a.b is: #myVar.a.b#</cfoutput>
<cfoutput>myVar.a.b is: #Variables["myVar.a.b"]#</cfoutput>

[Homestar9]

My recommendation would be to make sure that examples use more "real world" variable naming conventions. It's not good practice to name variables ambiguous things like "x" or "y", and code examples should reflect that.

I would also use language that is suited towards someone that might just be getting started programming in ColdFusion.  IMO documentation should read like a beginner's tutorial and not a technical whitepaper. Documentation should be informal, inviting, and user-friendly.  You wouldn't want to scare off anyone who's using CFML for the first time - especially for a page that talks about how to use a fundamental part of the language.

I also believe that including comments in code examples is a good idea.
If I were writing documentation on getting values from structs, I would probably change it to something like this:

// set the value of the 'firstName' key inside of a structure.
user.firstName = "Dave";

// the following ways of outputting the value of 'firstName' are equivelant.
writeDump( user.firstName );
writeDump( user[ "firstName" ] );

If you are looking for inspiration, I very much like the way Ortus put together the introduction to CFML programming here: https://modern-cfml.ortusbooks.com/
I believe that if Adobe made their documentation this user-friendly we would see greater CFML adoption from younger programmers that are just getting started out.