SIMPLX_RPC

Package Description

UPDATE rc2

Much improved docs. 
Added option to turn on/off Snippet matching in the console.

WHATS THIS SNIPPET ANYWAY?

SIMPLX RPC is a remote method invocation Snippet which makes it possible to call the ModX API from the client browser using XMLHTTP or similar. This means that you can fetch (for now...) data from ModX without reloading the page. This means more interactive, dynamic, responsive, personal web sites :)

The RPC (Remote Procedure Call) capability has been missing for too long in ModX i think. Well it turned out to be a real piece of cake to code it (much thanks to the simplicity of the ModX API but also thanks to the built in support for json in PHP). So here you are ;)

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.

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.

WHY DID I MAKE THE SNIPPET?

Well because it was the simplest and most plug-n-play way to do it. Using Modx Connectors would in some cases be a better options, but it takes some reading and hacking to get it working. 

This Snippet is a really clean and easy to use solution for your ajax needs :)

Also, what you get out-of-the-box by making it a Snippet is the ability to have access control over the remote api using the built in ModX security (as the remote service is just a document in ModX).

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"}}