Macros [parse.macro]¶

While the Parse plugin allows you to go deep into the REST API, there is always room for shortcuts. Macros allow you to perform pre-built functionality that extends the Parse REST API specification.

You can also add your own Macros that can be used globally wherever you can access the parse object. There are a number of common Macros that come by default.

Linking¶

.linkObjectToUser¶

Link an arbitrary Object to a User.

Parameters:

linkColLabel
className
objectId
userId (objectId)

  parse.macro.linkObjectToUser('toy', 'Toys', 'toy_id', 'user_id')
  :response(cb)

.linkFileToUser¶

Link an uploaded File object to a User.

Parameters:

fileColLabel
fileUri
userId (objectId)

  parse.macro.linkFileToUser('avatar', 'file_uri', 'user_id')
  :response(cb)

Note

The fileUri is returned when a file is uploaded. You can find it in the name key in the response.

.linkInstallationToUser¶

Link an Installation to a User.

Parameters:

installColLabel
installId (objectId)
userId (objectId)

  parse.macro.linkInstallationToUser('user', 'installation_id', 'user_id')
  :response(cb)

.linkFileToObject¶

Link a File to an arbitrary Object.

Parameters:

fileColLabel
fileUri
className
objectId

  parse.macro.linkFileToObject('snapshot', 'file_uri', 'Pics', 'pic_id')
  :response(cb)

.linkUserToObject¶

Link a User to an arbitrary Object.

Parameters:

userColLabel
className
objectId
userId (objectId)

  parse.macro.linkUserToObject('user', 'Runners', 'runner_id', 'user_id')
  :response(cb)

.linkObjectToUser¶

Link an arbitrary Object to a User.

Parameters:

objectColLabel
className
objectId
userId (objectId)

  parse.macro.linkObjectToUser('food', 'Food', 'food_id', 'user_id')
  :response(cb)

.linkObjects¶

Links one Object to another.

Parameters:

objectColLabel
className
objectId
toClassName
toObjectId

  parse.macro.linkObjects('ageGroup', 'Toy', 'toy_id', 'Group', 'group_id')
  :response(cb)

Auth Data¶

Using Parse-Server?

The self-hosted Parse-Server does not support Facebook or Twitter login.

.addTwitterAuth¶

Add Twitter Authentication data to a User.

Parameters:

authDataTable
userId (objectId)

  local auth_data =
  {
    id = "12345678",
    screen_name = "ParseIt",
    consumer_key = "SaMpLeId3X7eLjjLgWEw",
    consumer_secret = "SaMpLew55QbMR0vTdtOACfPXa5UdO2THX1JrxZ9s3c",
    auth_token = "12345678-SaMpLeTuo3m2avZxh5cjJmIrAfx4ZYyamdofM7IjU",
    auth_token_secret = "SaMpLeEb13SpRzQ4DAIzutEkCE2LBIm2ZQDsP3WUU"
  }

  parse.macro.addTwitterAuth( auth_data, 'user_id' )
  :response(cb)

.addFacebookAuth¶

Add Facebook Authentication data to a User.

Parameters:

authDataTable
userId (objectId)

  local auth_data =
  {
    id = "123456789",
    access_token = "SaMpLeAAibS7Q55...",
    expiration_date = "2012-02-28T23:49:36.353Z"
  }

  parse.macro.addFacebookAuth( auth_data, 'user_id' )
  :response(cb)

.addAnonAuth¶

Add a UUID as a custom authentication method.

Parameters:

uuid (lowercase-alpha-numeric)
userId (objectId)

  parse.macro.addAnonAuth('uo3m2avzxh5cj...', 'user_id')
  :response(cb)

Users¶

.findUserById¶

Finds a User by supplied id.

Parameters:

userId (objectId)

  parse.macro.findUserById( 'user_id' )
  :response(cb)

.findUserByEmail¶

Finds a User by supplied email.

Parameters:

email

  parse.macro.findUserByEmail( 'user@email.com' )
  :response(cb)

.findUserByUsername¶

Finds a User by supplied username.

Parameters:

username

  parse.macro.findUserByUsername( 'user_name' )
  :response(cb)

Key Search¶

.findWhereGreater¶

Find a Class key greater than the supplied value.

Parameters:

className
key
value

  parse.macro.findWhereGreater( 'Toys', 'stock', 12 )
  :response(cb)

.findWhereLess¶

Find a Class key less than the supplied value.

Parameters:

className
key
value

  parse.macro.findWhereLess( 'Toys', 'stock', 3 )
  :response(cb)

.findWhereEqual¶

Find a Class key equal to the supplied value.

Parameters:

className
key
value

  parse.macro.findWhereEqual( 'Toys', 'kind', 'car' )
  :response(cb)

.findWhereEqualOrGreater¶

Find a Class key equal to or greater than the supplied value.

Parameters:

className
key
value

  parse.macro.findWhereEqualOrGreater( 'Toys', 'stock', 5 )
  :response(cb)

.findWhereEqualOrLess¶

Find a Class key equal to or less than the supplied value.

Parameters:

className
key
value

  parse.macro.findWhereEqualOrLess( 'Toys', 'stock', 5 )
  :response(cb)

.findWhereNotEqual¶

Find a Class key not equal to the supplied value.

Parameters:

className
key
value

  parse.macro.findWhereNotEqual( 'Toys', 'color', 'red' )
  :response(cb)

.findWhereTrue¶

Find a Class key equal to true.

Parameters:

className
key

  parse.macro.findWhereTrue( 'Toys', 'new' )
  :response(cb)

.findWhereFalse¶

Find a Class key equal to false.

Parameters:

className
key

  parse.macro.findWhereFalse( 'Toys', 'inStock' )
  :response(cb)

Counters¶

Counters allow in place number increment and decrement. To add to the column property supply a positive number. To decrease the value, use a negative number. This will only function properly on number based columns.

.updateCounter¶

Parameters:

counterColLabel
amount (can be negative)
className
objectId

Adding 1 to the score column

  parse.macro.updateCounter('score', 1, 'Scores', 'score_id')
  :response(cb)
  -- score is now 1

Adding 10 to the score column

  parse.macro.updateCounter('score', 10, 'Scores', 'score_id')
  :response(cb)
  -- score is now 11

Removing 5 from the score column

  parse.macro.updateCounter('score', -5, 'Scores', 'score_id')
  :response(cb)
  -- score is now 6

Geo Searches¶

Geo Searches require a GeoPoint column on the class.

.geoSearchWithinBoundary¶

Find Objects within the given coordinates. You must provide two GeoPoints; one for the southwest corner, and one for the northwest corner. This creates your boundary.

Parameters:

className
southwestLatitude
southwestLongitude
northeastLatitude
northeastLongitude

  parse.macro.geoSearchWithinBoundary( 'Sales', 10.0, -23.0, 22.0, -11.0 )
  :response(cb)

.geoSearchWithinRadius¶

Find Objects within given radius. Max distance is 100 miles.

Parameters:

className
latitude
longitude

  parse.macro.geoSearchWithinRadius( 'Sales', 10.0, -23.0 )
  :response(cb)

.geoSearchWithinMiles¶

Find Objects in a radius, within the specified miles.

Parameters:

className
latitude
longitude
withinMiles (100 max)

  parse.macro.geoSearchWithinMiles( 'Sales', 10.0, -20.0, 5 )
  :response(cb)

.geoSearchWithinKms¶

Find Objects in a radius, within the specified kilometers.

Parameters:

className
latitude
longitude
withinKms

  parse.macro.geoSearchWithinKms( 'Sales', 10.0, -20.0, 15 )
  :response(cb)

.geoSearchWithinRadians¶

Find Objects in a radius, within the specified radians.

Parameters:

className
latitude
longitude
withinRadians

  parse.macro.geoSearchWithinRadians( 'Sales', 10.0, -20.0, 123 )
  :response(cb)

Custom Macros¶

Creating your own Macros is very simple and allows you to reuse calls throughout your application.

A Macro is basically just a returned parse.request without the :response method attached to it. The response is added when you actually use the Macro.

Adding a Macro

.add¶

Adds a new request Macro to the system.

Parameters:

macroName (no spaces)
macroRequest

  parse.macro.add( "getUsersOlderThan", function( age_limit )
    return parse.request( parse.User.query )
    :where( { age = { ["$gt"] = age_limit } } )
  end)

Using a Macro

Once you've added your Macro, you can call it anywhere you can access the parse object. Here is where the :response gets added as well.

  parse.macro.getUsersOlderThan( 30 )
  :response(cb)

Removing a Macro

.remove¶

Parameters:

macroName

In the rare case you need to remove a Macro:

  parse.macro.remove( "getUsersOlderThan" )
  -- If you try to call this Macro now, you
  -- will get a runtime error. So beware.