#deluge script

[rhynedesign]

Zoho Creator Map Function (Beginners)

View this Post on the Zoho Creator Forum

Hello Zoho Creator fans,

I thought I would make a post about some info, tips, ideas, I have around the the Zoho Creator "map" feature....

The map feature can be extremely poweful if you know how to use it. Unfortunately, there isn't a ton of documentation in the Wiki about it's cababilities..

First talk about what a Zoho Creator map is....

A map holds data! You put data in it by first creating a key and then adding a value.

This is called a key, value pair. This key,value concept is used in well known data documents like XML & JSON. And guess what!? Outputted ZC Maps ARE VALID JSON! (Later tutorial)

Maps are great for the following things.......

1. Structuring your data

2. Passing MANY VARIABLES from a form to a funtion or vice versa. (Instead of say one string/Int,List value which can save you much loading and development time)

3. Ceating input agnostic data sets.. (later)

4. Posting JSON to API's using the postURL()/getURL() functions (later)

5. Creating multidimensional traversable arrays just like in other scripting languages (GREAT! later)

  Creating a map... (It's so easy...)

//first name a variable.....

myMap = map();

So you just created a map myMap is the variable that holds your map data and map();

Now, we just need to add data to it!

myMap.put("key1","value1");

So "key1" is your key and "value1" is your string value associated with the "key1" key...

Let's add some more keys!

myMap.put("key2",2);

myMap.put("field3",false);

Ok, so now we have added two more keys to our "myMap" map and we added some values.. The "key2" key holds an integer, and "key3" holds a bool value..

Notice that you I CAN NAME MY KEYS WHATEVER I WANT! This is VERY IMPORTANT! If you have been playing with Zoho Creator Deluge Script for a while you will start to realize that you cannot dynamically change the "name" of a variable, but since our keys arent' actually a true variable we can dynamically name them.. We will talk about this more later but trust me this is a fantastic little detail that can be uber powerful if you know how to use it.

  Getting Data from your LOCAL map.....(this is easy too!)

//Let's get "key1" from myMap

myKeyValue = myMap.get("key1");

There... now myKeyValue will == "value1"

  Getting map values stored in a function....

FIRST IN MOST CASES IT'S A BAD IDEA TO CALL A MAP FUNCTION LIKE THIS....

myKey1Value = thisapp.mapFunction().get("key1");

myKey2Value = thisapp.mapFunction().get("key2");

Why? Because unless you added a paramter to the map function to only run a certain part of the map, the FUNCTION IS RUNNING THE WHOLE SCRIPT just to get your one map value... So each time you make a call to this mapfunction you are running the entire script. This won't slow you down with a small function but if you are making calls to web services or collecting records this is just NOT good form...

Like in all good programming it's better to save operations and create A LOCAL map variable... Here's how....

Store your map function key, value pairs in A NEW local variable....

myNewLocalMap = map.put(thisapp.mapFunction());

Now all your keys and values from your map function are IN YOUR LOCAL SCRIPT. Then you just get your values the same way as we did above....

myKeyValue = myNewLocalMap.get("key1");

  Ok, there is more to come...

In my next post I will give the goods. This is just a basic post.

Stephen Rhyne

Owner

Rhyne Design

[rhynedesign]

Zoho Creator Map Function (Intermediate)

View Post on Zoho Creator Forum

This is a follow up post to map tutorial (Beginners)

Hello ZC fans,

I in the last post I discussed some of the basics about the map() function/feature. The last thing I discussed in the post was how to pull in map values from a map function (in functions tab) to a local script (form, view).

But what if you wanted to do the opposite? What if you wanted to transfer a map from a form or view to a function.

Pass a local map variable from form or view to a function

First let's make our map

myMap = map(); myMap.put("key1","value1"); myMap.put("key2",2); myMap.put("key3",false);

Now let's send this map variable to a function

thisapp.PushmapFunction(myMap);

There! now your map keys and values are ready to be manipulated by your function!

You will find that sending maps to functions is a very useful way to send a lot of parameters to a function quickly.. Sending a single map to your function can save you time and confusion later. They also give you a little more flexibility.

Here's a sample function that could be a little cubersome. It looks like this when you call it.....

thisapp.myCrazyFunction(input.field1, input.field2, input.field3, input.field4, input.field5, input.field6, input.field7, input.field8, input.field9);

This is TOTALLY A VALID FUNCTION! But what if you wanted to change the form field type of input.field2 from a string value to a long value? ZC functions require you to assign an input type to each function parameter. So since you already set "myCrazyFunction" to take a string value by changing input.field2 from string to long, your function becomes invalid.

You would either need to convert input.field2 to a string value (field2_str = field2.toString();) or you would need to change "myCrazyFunction" to except a long value.

If you create and pass a single map variable that holds all your 9 form input field values YOU BYPASS the individual field types. This keeps your function valid and saves you time! (this works the same way for lists).

Now don't get me wrong.. Parameters are a good thing and there are many places where sending individual parameters is a better practice.

The truly powerful feature about maps is that keys can be dynamically named.. You can do some wonderful stuff when you combine the traversable/looping power of lists WITH the "key/value" feature of maps.

"keys can be dynamically named.... "

If you don't know what I mean by this then let's take look at the following INVALID ZC SCRIPT...

value_list = {1,2,3,4,5}; for each value in value_list { value+"value" = value; }

What I was trying to do is dynamically name the variables in the loop. So that I come up with something like this...

value1 = 1;, value2=2; value3 = 3, value4=4;

BUT YOU CAN'T DO THIS IN ZOHO CREATOR. You cannot name variables dynamically. You CAN do this in a full featured scripting language. However, ZC is purposely stripped down. (That's the beauty of it!)

Just so you know... in PHP naming variables is simple..  ${"value".1}  = 1 renders to $value1 = 1.

Anyways this isn't a PHP tutorial. Back on track... :)

Now let's look at the same sort of list loop but this time we are going to use a map and THE ZC DS WILL BE VALID SCRIPT!

value_list = {1,2,3,4,5}; myMap = map();

for each value in value_list { myMap.put("value"+value,value); }

So what does this give us?

  myMap = {value1=1, value2=2, value3=3, value4=4, value5=5};Now we can get all of our "value_list" values by using a key! myMap.get("value1") == 1;So dynamic naming of keys is again so powerful. And this is all possible because keyvalues are string values NOT a true variable. To hammer down my point of the power of dynamic naming of keys even more. Let's look at the following very powerful piece of code... Put all your form fields and form values into a map variable WITH 7 LINES OF CODE!fields = getFieldNames();form_map = map();for each field in fields{ value = getFieldValue(field); form_map.put(field, value);}fields = getFieldNames(); returns a string list of all of the form field names.form_map = map(); creates a new mapfor each field in fields{} is a loop we use to populate form_map map variablevalue = getFieldValue(field); by first creating a list of the field names in the firstline we are able to loop through the form and get the field values for each field!form_map.put(field, value); now we just put our field name from the list as our key and the valuewe got using the list as our value.ISN'T THAT COOL?! With just 7 lines of code we were able to take all the data from theform and turn it into a map! You could take this form_map and pass it to a functionor you could pass it to a postURL() function that takes the VALID JSON and posts it toan outside server PHP script to save to a database! Whatever you want. The point is that lists and maps a just great to use together. Here's another example of how we can use a list and a map together to create powerfulcode. Let's take our fields list and our form_map and send them to a function! //form side send list and map to functionthisapp.myMapFunction(fields, form_map);//on the function endvoid myMapFunction(list fields, map form_map){ for each field in fields { if(!field.contains("client_")) { form_map.remove(field); } } request_map = map(); request_map.put("form_map",form_map); xml_response = postUrl("http://RESTresourceExample.com",request_map,false); response = xml_response.get("responseText"); response = response.executeXPath("/response/result/message/text()"); return response;}So in this last example we...1. looped through each field name that we got from the form2. We validated that the form field HAD THE STRING "client_" in it. (This means thatyou can change which fields get used in your script SIMPLY BY CHANGING/APPENDING YOUR FIELDNAME! This is a great tool to use if you are building marketplace apps as you give the usermore control without knowing DS)3. We removed any map key,value pairs that didn't match the "client_" field name validation4. We sent the map/JSON to a RESTful resource/web service to be processed. 5. We get the response... I hope you found these things useful.. In the next post I will be focusing on moreadvanced map function snippets and I'll post my FAVORIATE ZC discovery of all time!Hopefully it's something new to the community. Maybe it's not. If you have ideas or other great Map tricks! PLEASE POST THEM!

[rhynedesign]

Zoho Creator Map Function (Advanced)

 This is a follow up post to the following two other posts....

1. Map Tutorial (Beginners)

2. Map Tutorial (Intermediate) 

In this post I am going to talk about some more advanced ideas concepts in regards to using maps and lists together.

If you are reading this you are already aware of the power of using lists and maps together to create powerful DS scripts.

I'm going to cover HOW TO COMBINE A ZC MAP AND A ZC LIST TO CREATE MULTI-DIMENSIONAL ARRAYS( Think form records stored in script format).

In PHP it's very easy to create a multi-dimensional array (many map variables inside a big list) and encode

this into JSON... A PHP multidimensional associative array looks like this....

$client_array = array(

     "client_address"=>array(

       "street"=>"PO Box 1000",

        "city"=>"Seattle",

         "state"=>"WA",

          "zip"=>"98122"

      ),

     "contact_info"=>array(

     "mobile"=>"555-1212",

      "email"=>"[email protected]"

     )

);

In the above PHP example the $client_array would be a ZC Deluge Script list() where list.size() == 2.

the client_address and client_info arrays would be ZC Deluge Script map()'s

Stephen, Why would I want to make a multi-dimensional array in Zoho Creator? 

1. Store records in script format to be added to a new application upon loading it for the first time. (instead of XML or a getURL() call)

2. Convert cumbersome XMLList()'s to an easy list/map format...

Replace  _.executeXPath("/row/blah/blah/text()"); with a simple map.get("key"); 

NOTE: Try executing an XPath on an xmlList you called through a function! Your Xpath variable will come back null! This solves that problem/bug. (Let me know if you have solved this issue in the past.)

3. Store huge amounts of structured records data IN a variable to be looped through later. 

Reason for coming up with this idea.

Recently I have been doing a lot of Zoho Creator API work with PHP & jQuery/Javascript coding using the JSON feed instead of XML... and I LOVE IT!

JSON is such a great data format and it's so easy to traverse over/iterate through the records in JSON..

Example: Traversing over JSON in Javascript

for (i = 0; i < length; i++) {                     var name = suppliers[i].name;                     var address = suppliers[i].address;                     var zoho_id = suppliers[i].zoho_id;                     });

Now back to Zoho Creator Maps! Zoho Creator Maps ARE VALID JSON when you output them to string..

But, at first I was completely unable to traverse over ZC Maps like you do in regular scripting (like the above JS example).

If you have noticed there is no "for each" option in the map manipulations on the script builder menu AND there isn't really a clear cut way to store key,value pairs in a regular list. (You could mess with indexes or create text deliminators and stuff but it's sort of a bad way of doing things.)

So I tried putting map() variables inside a list. This way I could store my maps inside a format that Zoho Creator permits looping.

If you try to put a map() variable inside a list this is what you get.......

Error at line : 13 Unsupported type given as argument

BUT! What if you convert your map variable to a STRING! Then your list is just holding text (text that is perfectly willing to be converted back into a map later AND is perfectly willing to be saved in a list!)

Let's look at an example of how we can create a MULTI-DIMENSIONAL ARRAY in Zoho Creator....

Creating a multi-dimensional array in Zoho Creator

list test.array_encode() {     start_list = {"node1", "node2", "node3", "node4"};     end_list = List();     for each r in start_list     {         map = map();         map.put("field1", 1);         map.put("field2", 2);         map.put("feild3", 3);         map.put("field4", 4);         stringMap = map;         end_list.add(stringMap.toString());     }     test_list = list();     for each test in end_list      {          map = test.toMap();          test_list.add(map.get("field1"));         }     info test_list;     return end_list; }

1. We created a function that returns a list

list test.array_encode() {}

2. We created a "start_list" with node1 through node 4. 

    start_list = {"node1", "node2", "node3", "node4"};

 The nodes are simply a list telling us how many iterations we are going to have. This could instead be a collection list of records or rows in an XML list perhaps.

3. Now we create an "end_list" this list will hold our key/value pairs (created by the map function).

end_list = List();

In our PHP example the end_list would be the $client_array variable and the "r" variable in the loop would be each array inside the $client_array (separated by commas).

4. We create a new map, PUT our keys and values into the map, then convert it to a string!

map = map();         map.put("field1", 1);         map.put("field2", 2);         map.put("feild3", 3);         map.put("field4", 4);         stringMap = map;         end_list.add(stringMap.toString());

OUTPUT FROM HERE!

 [{"field4":4,"feild3":3,"field1":1,"field2":2}, {"field4":4,"feild3":3,"field1":1,"field2":2}, {"field4":4,"feild3":3,"field1":1,"field2":2}, {"field4":4,"feild3":3,"field1":1,"field2":2}]

5. LET'S TEST IT!

    test_list = list();     for each test in end_list      {          map = test.toMap();          test_list.add(map.get("field1"));         }     info test_list;

Here we create a "test_list" to grab our "values" from the array. We create a new map variable "map" then convert the map string BACK INTO A MAP. Then we just add the the map value to our list and "debug/Info" the test_list..

SURE ENOUGH THE "test_list" comes back with

1, 1, 1, 1

ISN'T THAT GREAT! If you start to think about it more you will see the similarities to the "for each record" function

but instead of using form field names to get your value you use the map's key value!

I hope you find great use out of this concept! Soon I will be posting some more ways to incorporate it into your DS scripts LIKE converting XML to ZC arrays without mapping hundreds of XPaths, storing many records inside ONE record, etc.

PLEASE let me know if you have ideas or suggestions on how to make this concept better. I am always open to ideas. If you have any questions you can go to my website, or post it here as a comment on the forum.

Stephen Rhyne Owner Rhyne Design

[rhynedesign]

Easy Zoho Creator Form CSS with ZCStyles (Free on ZC Marketplace)

Just whipped up a little ZC function that makes it super easy to customize the look of  ALL your forms in all your applications. I got tired of having to make markup changes in many, many html views and links when using the form customization parameters.

Get it here on the marketplace