Wiki

Clone wiki

mod_parse / Home

mod_parse

mod_parse is a Parse module for use in Corona SDK. It is not a full client, nor is it a plug-in, and is currently in beta. Read on for usage information or jump to the docs.

You need to sign up for the free Parse.com service to use the module.


Download the Parse module by clicking here.


Click here for a getting started tutorial.

Todo

  • Add Push notifications from phone.
  • Add Batch calls support.

Limitations

Parse's REST API does not currently support "installations" of Android devices, which is used to register a device to Parse.com for push notifications. This method is available in the module for iOS.

The module does not offer any interface for Parse's Role-based Access Control.

Usage

Make sure to include the "Internet" permission on Android in your build.settings:

--build.settings
settings = {
  androidPermissions = {
    "android.permission.INTERNET",
   },
}

To use the module you must first require it, then initialize it with your Parse information.

Require the module:

local parse = require( "mod_parse" )

Initialize

Pass your Application ID and REST API Key from your Parse account settings section:

parse:init( { appId = "PARSE_APP_ID", apiKey = "PARSE_API_KEY" } )

Debug Flags

You can set the following flags after you initialize the Parse module:

parse.showStatus = true|false -- outputs response info in the console
parse.showAlert = true|false -- show a native pop-up with error and result codes
parse.showJSON = true|false -- output the raw JSON response in the console

All debug flags default to false.

The parseRequest Event

The parse module will broadcast a parseRequest event anytime an action has completed, with details in the event. You can listen for it by setting up an event listener on the parse modules dispatcher property:

local function onParseResponse( event )
  if not event.error then
    print( event.response.value )
  else
    print( event.error )
  end
end
parse.dispatcher:addEventListener( "parseRequest", onParseResponse )

Event Properties

A parseRequest event has the following properties:

name

The event name. Returns "parseRequest" as the only event type.

requestId

Contains the original networkRequestId that was generated when first calling a particular parse module method. If you capture the initial networkRequestId and store it, you can use the requestId to filter incoming messages.

local myNetworkRequestId
local function onResponse( event )
  if event.requestId == myNetworkRequestId then
    print( "Hey, it's me!" )
  end
end
parse.dispatcher:addEventListener( "parseRequest", onResponse )

myNetworkRequestId = parse:getMe()

requestType

The type constant of the request ( parse.USER, parse.LOGIN, etc )

response

The payload. The response property contains a table of properties returned from Parse.com based on your request. See the Parse.com REST API documentation for what the return payload looks like for each method type.

local function onPlayer( event )
 print( event.response.score )
end
parse:getObject( "Player", "player-obj-id", onPlayer )

code

Error code. If there was no error, the code will be nil.

error

The error string. If there was no error, it will be nil.

results

If a response contains multiple records, you can access them from the results property, which is a table array of results. It's an alias for response.results. It can also be used to check if there are multiple results. If there are no results, the results property will be nil.

Canceling Requests

While it's better to let the calls complete naturally and deal with any errors that come up, you can also cancel a request specifically, as long as you capture the initial networkRequestId. For example:

local networkRequestId = parse:getUser( "a-user-id" )

--LATER...

--let's cancel
parse:cancelRequest( networkRequestId )

Formatting Module Keys

All keys in the data tables passed to the module are wrapped in brackets ( [ ] ). This ensures that the keys will be recognized as strings, which is required by the Parse service.

Even if you're passing a variable as a key name, you need to wrap it in brackets. Some examples:

--regular string
parse:logEvent( "Share", { ["screen"] = "splash" } )

--as a variable
local key = "screen"
parse:logEvent( "Share", { [key] = "splash" } )

You do not need to put brackets around values. This is incorrect:

parse:logEvent( "Share", { ["screen"] = ["splash"] } ) -- INCORRECT

Global Listener Override

You can override the global listener for any of the modules methods -- per call -- for more granule event handling. Inspect this code as an example:

--global listener
local function onParseResponse( event )
  if not event.error and event.requestType == parse.LOGIN then
    print( event.reponse.sessionToken )
  end
end
parse.dispatcher:addEventListener( "parseRequest", onParseResponse )

--uses global listener
local requestId1 = parse:loginUser( loginData )

--uses overridden listener for this call
local function onLogIn( event )
  print( event.reponse.sessionToken )
end
local requestId2 = parse:loginUser( loginData, onLogIn )

NOTE: Any methods that provide an overridden listener will NOT trigger the global one for that call.

Module Docs

View all of the module methods in the Parse Module Docs.

Updated