Transform

Transform

##.transform( function )

Transform allows you to modify your objects within your collection. You can replace or add to existing properties. You can create as many .transform() calls as you want. This will permanently transform your collection. You can use this to map properties from an ajax call or creating new compound properties.

Example 1 - Compound Value

If you had the following collection and you wanted to have a property with the full name. You would use .transform() to create the new property.

var data = [
               {
                   "first_name": "Don",
                   "last_name": "Fisher"
               },
               {
                   "first_name": "April",
                   "last_name": "Smith"
               },
               {
                   "first_name": "Ariel",
                   "last_name": "Jackson"
               }
           ];

var people = new JSQL(data);
people.transform(function(obj){
   obj.full_name = obj.first_name + ' ' + obj.last_name;
});

Any function passed into .transform() will have an object passed as an argument. This allows you to have access to the current objects properties for modification. In this example we're simply adding first and last names together. There is no need to return a value. This is what our new collection will look like.

people.get();

/* result
/*-------------------------------------------------------*/
[
    {
        "first_name": "Don",
        "last_name": "Fisher",
        "full_name": "Don Fisher"
    },
    {
        "first_name": "April",
        "last_name": "Smith",
        "full_name": "April Smith"
    },
    {
        "first_name": "Ariel",
        "last_name": "Jackson",
        "full_name": "Ariel Jackson"
    }
]
*/-------------------------------------------------------*/

Example 2 - Property Mapping

There is a third party API you want to use but provides data in a different format, you can use transform to modify the format of the objects. Your system expects cammelCase but you "get_this". Here is how you would modify your data.

var dataFromApi = [
                    {
                        "user_id": 1,
                        "name": "Don",
                    },
                    {
                        "user_id": 2,
                        "name": "April",
                    },
                    {
                        "user_id": 3,
                        "name": "Ariel",
                    }
                ];

var people = new JSQL(dataFromApi);

// convert the object
people.transform(function(obj){
   obj.userId = obj.user_id  // create new property
   delete obj.user_id;       // remove old property
}).get(); 

/* result
/*-------------------------------------------------------*/
[
    {
        "userId": 1,
        "name": "Don",
    },
    {
        "userId": 2,
        "name": "April",
    },
    {
        "userId": 3,
        "name": "Ariel",
    }
]
/*-------------------------------------------------------*/

What we did here was create a new property called "userId" and passed in the value of obj.user_id. Then we deleted obj.user_id since we did not need that property anymore.

Many more examples to use transform coming soon!