SIMPLX_RPC

Package Description

AJAX made really simple

SIMPLX RPC is a remote method invocation Snippet. It makes it possible to call the MODx API from the client browser using XMLHTTP, or, from another app. This means that you can, as an example, read and update data from MODx without reloading the page. This in turn means more interactive, dynamic, responsive, personal web sites :)

This Snippet simply wraps the MODx API (http://wiki.modxcms.com/index.php/Ja:API:DocumentParser) with the JSON-RPC protocol (http://groups.google.com/group/json-rpc/web/json-rpc-1-2-proposal). It should match the documented API spot on i think.

Screencast

http://www.youtube.com/watch?v=B3BWLg87zyE

JSON RPC 2.0 Compliant

As of version 0.6.1 SIMPLX RPC is fully compliant with the JSON RPC standard. JSON RPC is a port of the popular XML RPC standard which is used as a service layer by many systems on the market today. If you want to integrate MODx using XML RPC i can recommend a PHP script which handle conversion between the two, http://code.google.com/p/json-xml-rpc/ 

Note

Note that this implementation uses named parameters. This means that the parameters collection must be represented as a JavaScript object with key/value pairs. This ensures that parameter sequence is not an issue when calling in method calls.

SIMPLX RPC will in the near future remove all MODx API methods which have been marked as "deprecated" by the MODx team. Please use Snippet matching and wrap your own "procedures" in Snippets. This is good design as it abstracts code into logical components; it also offers maximum security options using ACL's etc. 

Have Fun :)

Usage/Installation Instructions

INSTALLING

Real easy. Get it using the Package Management (recommended!), or,  just paste the Snippet code in a new Snippet and name it SIMPLX_RPC. Then make a new template and paste in only the empty call to this snippet WITH CACHING TURNED OFF ([[!SIMPLX_RPC]]).

The Snippet will now read the HTTP GET/POST header and do all the magic, including returning json data.

To get the Snippet working please,

• create one page which uses the SIMPLX RPC template. This is the page which will act as a access point for all RPC calls. Remember to set appropriate access permissions for this page. 
  
  
• create another page using the SIMPLX RPC EXAMPLE template. This example template has some really nice sample/debug features!
  
  
• Test out the SIMPLX_RPC_EXAMPLE Snippet which shows you how to query getResources.  

The Examples Console

The console on the example page is really cool :D 

It lets you make test calls to your site and try out templating etc. 

• The "Query Config" tab
  shows the current json config object. Initially it contains a param called "dummyResponse". As long as this param has a value other than "", no remote call will be made. This is to make testing easy. To start using your ModX site to get actual "live" data, just remove the "dummyResponse" value and set the other params to match your setup (url, pageid which uses the SIMPLX_RPC template, Snippet name and parameters).
  
  
• The "Template" tab
  contains the jQuery Template html code. This can be updated and viewed "live".
  
  
• The "JSON Result" tab
  shows the current response from the server.

EXAMPLES USING MODX API FUNCTIONS

By next release all methods except "runsnippet" will be removed. I am considering porting these legacy functions to Revo to help the community.

{"id":"1","method":"modx.getpageinfo","params":{"pageid":"3","fields":"pagetitle"}}

{"id":"1","method":"modx.runsnippet","params":{"snippetname":"ditto","tpl":"[+title+]

[+summary+]"}}

{"id":"1","method":"modx.runsnippet","params":{"snippetname":"Wayfinder","startId":"0"}}

{"id":"1","method":"modx.db.select","params":{"fields":"email","from":"user_attributes","where":"internalKey=1","orderby":"internalKey"}}

{"id":"1","method":"modx.getchunk","params":{"chunkname":"navigation"}}

{"id":"1","method":"modx.gettemplatevaroutput","params":{"docid":"3","idnames":"template variable name"}}

{"id":"1","method":"modx.getdocuments","params":{"ids":[2,3,4],"published":"1","deleted":"0","fields":"pagetitle,id","where":"","sort":"id","dir":"ASC","limit":"100"}}

 USING SNIPPET MATCHING

The first Wayfinder example shows how to force Snippet Matching using a querystring parameter when the default Property Set parameter is set to false (0).

The second example shows how the url looks when you have set the default Property Set parameter to true (1).

http://www.mysite.com/?id=5&simplxrpc={"id":"1","method":"Wayfinder","params":{"startId":"0"}}&usesnippetmatching=1

http://www.mysite.com/?id=5&simplxrpc={"id":"1","method":"MySnippet","params":{"myParam":"hello"}}