wmexamples / README

Bryan Fink bd68f40 





Bryan Fink e70c0b5 



Bryan Fink bd68f40 




Bryan Fink e70c0b5 



Bryan Fink bd68f40 






Bryan Fink e70c0b5 



Bryan Fink bd68f40 



Bryan Fink e70c0b5 


Bryan Fink bd68f40 




Bryan Fink e70c0b5 



Bryan Fink bd68f40 




Bryan Fink e70c0b5 



Bryan Fink bd68f40 
Bryan Fink e70c0b5 



Bryan Fink 2346bc4 











Bryan Fink 8f1c89c 















Bryan Fink a0bb705 













Bryan Fink a8b6066 





















Title: README for wmexamples
Author: Bryan Fink
Source URL: http://bitbucket.org/bryan/wmexamples/
Created: 2009.May.18
------

wmexamples is a demonstration Webmachine application.  It contains a
handful of Webmachine resources that I have posted elsewhere, but have
chosen to assembled here to show off.  To run this application, you'll
need:

- Erlang - http://erlang.org/
- Webmachine - http://bitbucket.org/justin/webmachine
- ibrowse - http://code.google.com/p/erl-ibrowse/

Note: ibrowse is only needed for the CouchDB proxy resource.  If you
will not be using couchdb_proxy, you can remove the dependency on
ibrowse by commenting out the "ensure_started(ibrowse)" and
"application:stop(ibrowse)" lines in src/wmexamples.erl.


Installation
---

Checkout/unpack wmexamples.

If the directory in which wmexamples lives also contains webmachine
and ibrowse, you should be all set.  If not, you'll need to change the
symlinks in wmexamples/deps to point to where webmachine and ibrowse
are installed.

cd wmexamples
make

If everything makes fine, run ./start.sh or ./start-dev.sh, then point
curl or a browser at http://localhost:8000.  You should get a "Hello,
new world" message back.


Example Resources
---

The best place to determine what resources are enabled is in
priv/dispatch.conf.  That file describes the dispatch table for this
Webmachine application, and also contains helpful comments.  Other
short descriptions of what examples are included are below.


CouchDB Proxy Resource
---

couchdb_proxy.erl describe a proxy resource for exposing raw CouchDB
through a webmachine app.  It does very minimal request processing -
only fixing Location headers such that clients of the webmachine
resource direct their requests properly.

To use couchdb_proxy.erl in your own application, copy the file to
your application's src tree, and also make sure the ibrowse is started
before any requests are made to the resource (wmexamples starts
ibrowse at startup in wmexamples.erl).

Environment Variable Resource
---

env_resource.erl was a sample resource for demonstrating
implementations of several Webmachine resource functions.  The goal of
this resource was to expose the ability to inspect and modify
OS-environment variables.

The story of env_resource's development is available in five blog
posts starting at http://blog.beerriot.com/2009/04/13/
simple-webmachine-proper-http-resources/

Sample Trace Resource
---

The Webmachine trace utility is available at
http://localhost:8000/wmtrace/ while this application is running.

Four example trace files have been included in the "traces" directory.
They are named example-trace-CODE.wmtrace, where CODE is the HTTP
status code the resource returned at the end of the request.

The sample trace files were generated with the sampletrace_resource,
which is included and exposed at http://localhost:8000/sampletrace
That resource isn't good for much other than generating those simple
examples, but I thought it best to include it for demonstration
purposes.

POST Example (wwwform -> json)
---

formjson_resource.erl is mainly an example of how one might handle a
POST in a webmachine resource.  process_post/2 demonstrates how to
grab the request body out of the ReqData (wrq:req_body/1), and push a
response body into one (wrq:append_to_response_body/2).

Issuing a GET to formjson_resource will encode the query parameters of
the request as JSON, and return that encoding in the response body.

Issuing a POST to formjson_resource will assume that the body of the
request is application/x-www-form-urlencoded data, re-ecode it as
JSON, and return that JSON in the response body.

Dispatch Reloader
---

dispatch_watcher.erl defines a gen_server that can be started in the
background, and will watch dispatch.conf for changes, reloading it
when necessary.

By default, it checks "priv/dispatch.conf" for updates once a second.
This behavior can be changed by passing the configuration parameters:

  {dispatch, Path}: where Path is a string describing the path of an
                    alternate dispatch file
  {interval, Time}: where Time is an integer number of milliseconds
                    describing how long to wait between checks for
                    updates to the dispatch file

wmexamples starts dispatch_watcher by including a supervisor child
specification in the return value of wmexamples_sup:init/1.  It could
be started instead by appending "-s dispatch_watcher" to the final
command of start-dev.sh, to get a dev-vs-production kind of
configuration.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.