Wouldn't it be nice if whenever you need a parameter you could just ask for it by name? Lets say that you have a create order script and you want to pass the script the name, street and zip code of the customer. If you were stuck with just the regular old FileMaker functions there ain't no way that's happening. But after you are done with this post, you will be able to get the name of your customer with the simple function: GetParameter( "customerName" ).
Alright, since your interest is hopefully already piqued, I'm just going to go ahead and tell you the functions right away. There are three of them. I know that sounds like a lot but if you give me a chance to explain myself, trust me your going to love it and once you get used to them you'll never go back.
Name: PassParameter
Parameters: name, value
Formula:
"<:" & Substitute( name; ["="; "/="]; [":"; "/:"] ; [">"; "/>"]; ["<" ; "/<"] )
& ":=" &
Substitute( value; ["="; "/="]; [":"; "/:"] ; [">"; "/>"]; ["<" ; "/<"] ) & ":>"Name: DictGet
Parameters: dict, name
Formula:
Let( [
match="<:" & Substitute( name ; ["="; "/="]; [":"; "/:"] ; [">"; "/>"]; ["<" ; "/<"] ) & ":=";
pstart = Position(dict; match; 1; 1);
start = pstart + Length(match);
end = Position(dict ; ":>"; start; 1);
len = If(end = 0; 999999999; end - start)];
If (pstart = 0; "";
Substitute(Middle(dict; start; len); ["/:"; ":"]; ["/="; "="] ; ["/>"; ">"] ; ["/<" ; "<" ]))
)Name: GetParameter
Parameter: name
Formula:
DictGet(Get(ScriptParameter); name)
These different functions are probably a little bit confusing right now so lets go through them one by one.
<pre><code>PassParameter( name ; value )</code></pre>
This custom function is your bread and butter. You use it every time you want to pass a parameter to another script. name is the name of the parameter your are passing and value is the actual text that you want to send over. So for instance if you were sending the name of your customer to a script you would use:
<pre><code>PassParameter( "customer" ; "Joe Blow" )</code></pre>
If you want to pass multiple parameters to our order creation script would just string this custom function together using the ampersand like so:
<pre><code>PassParameter( "customerName" ; "Joe Blow" ) &
PassParameter( "street" ; "123 Any St." ) &
PassParameter( "zip" ; 85282 )</code></pre>
How it works: PassParameter() turns the name, value pairs that you pass in into a special format so that they are easy to manage. It basically puts two special characters in front of the name, between the name and value, and after the value. Basically if you were to say PassParameter( "customerName" ; "joe blow" ), this function turns your text into:
<pre><code><:customerName:=joe blow:></code></pre>
or in the case of multiple parameters as above it would look like this:
<pre><code><:customerName:=joe blow:><:street:=123 Any St.:><:zip:=85282:></code></pre>
This construct of name and value pairs is what we refer to as a dictionary. This becomes important because our next function operates on a dictionary. You'll notice in the actual definition of the function PassParameter() that I do a couple of substitutions. I use this process to escape the different characters that I use in my delimiters so that my scripts won't break when you send in those same characters. Don't worry though, when I get them back out I remove any extra characters that I added.
<pre><code>DictGet( dict, name)</code></pre>
The dict parameter in this custom function is, yup you guessed it, short for dictionary. The second parameter, ‘name', is just the name of a value that you would like to get out of the dictionary. So if you were to execute the following code:
<pre><code>DictGet( "<:customerName:=joe blow:><:street:=123 Any St.:><:zip:=85282:>" ; "customerName" )</code></pre>
It would return "Joe Blow". On it's own this DictGet function doesn't seem that useful but it is the workhorse of the three functions.
How it Works: DictGet() actually works as a basic text parser. It takes the name that you pass in and turns it into the format you would expect in the dictionary. If the name passed in is "customerName", then it would be turned into "<:customerName:=". The we take that weird looking text and search for it in the dictionary. If we find the weird string in the dictionary, then we return the value for it ("joe blow", otherwise we return an empty string (""). Pretty neat huh?
<pre><code>GetParameter( name )</code></pre>
This is the function you would use whenever you are trying to access data that was passed in using the PassParameter() function. It's is specifically designed to operate on a script parameter that contains a dictionary. It actually just pulls the value of the name you give it, out of the script parameter using the DictGet() function. Very Simple.... not a whole lot going on here.
Now that you have a pretty good understanding you are pretty much ready to enter into the world of named parameters. Once you get used to using these little gems, I am positive that you will never be able to go back to plain old vanilla script parameters ever again. There are a couple more benefits to using these functions such as using named values in your script results, nesting parameters and accessing multiple occurrences that I will probably get into a later date. For now… I hope these functions help make FileMaker Development a little easier for you.
More About Dictionaries: If you would like to get a little more in-depth into these functions there is a second post that adds functionality to this idea here: FileMaker Dictionary Functions.
NOTE: We had a couple of good comments from some of our early release readers. Genx who blogs on FileMakerMagazine.com added that he thought it would be much more visually appealing and easier to use XML style tags. I can't remember the exact reason why I didn't go this route... I am pretty sure it was because I wanted to have two delimiters at each break point in the name/value pair. He did convince us to change the names of the functions from our more nondescript names ( #() #P() ) we started with so that it would be easily understood what each one did. Another useful tip came from Fitch of pre1.com, who pointed out that another similar name/value pair implementation can be seen in Back Magic from SeedCode.com