davide / ewgi_examples Goto Github PK

Ewgi Examples

	An OTP application that serves as testing ground for the current
	ewgi gateway implementations (so far: inets, mochiweb and yaws)
	and includes some ewgi middleware examples (the basic ones
	are part of this project while the more generic ones are/should
	be located in the ewgi repository).
	
	On the long run all middleware present in the ewgi project should have
	a working example in this project/repository -> having working 
	examples makes a ton of difference on *whatever* adoption! :)


Pre-requirement:
	- ewgi installed under your erlang libs directory
		or
	- accessible under the deps folder

Starting the server:
	./start.sh default

	This will read the config/default.config configuration file and boot
	the webservers listed there.
	By default two servers are started:
		- mochiweb on port 80
		- yaws on port 443 serving HTTPS requests
		  (a self-signed certificate is provided and should work, if not just
		   create your own: http://www.akadia.com/services/ssh_test_certificate.html)
		
	Both webservers are configured to present an index page with links
	to try out the ewgi middleware that comes bundled with the ewgi and
	ewgi_examples projects.


First steps!

	After browsing through the examples you'll probably want to figure out
	how everything is connect. It's quite simple: in the src directory we
	have a supervisor (ewgi_examples_sup.erl) responsible for booting the
	ewgi webservers (as specified in the config/default.config file).
	The webservers are designed to serve as an ewgi gateway and
	immediately after it you'll have a glimpse of your first ewgi middleware.
	
	In this example that middleware is a dispatcher 
	(src/middleware/ewgi_examples_dispatcher.erl) that analyses the 
	requested url to determine where to route the request next.

	Open the src/middleware/ewgi_examples_dispatcher.erl file and take
	over a piece of url and start testing out your own ewgi middleware.

	Checkout the ewgi_api module (in the ewgi project) for loads of
	functions that help in managing the ewgi_context() - no need for
	handling the tuples explicitely. :)

	Another thing... If the ewgi project is build with the debug flag then
	you'll be able to see your generated ewgi responses before they are
	handled by the webserver.


Terminology

	Ewgi Application:
		- a 1-arity function that receives an ewgi_context() and
		   returns another ewgi_context().
		   The great advantage of Apps is that they allow the creation of
		   complex stacks by simply chaining functions together.

	Ewgi Middleware:
		- any N-arity function that takes an ewgi_context() input
		  and returns another ewgi_context().
		
		- the recommended way to create ewgi middleware is to
		  define it as a 2-arity function that receives the ewgi_context()
		  as the first argument and a list of parameters as the second
		  argument. Like so:
		  
			my_middleware(Ctx, [Arg1, Arg2, ...]) ->
				Ctx1 = <do something>,
				Ctx1.
		  
		  This convention/restriction from the generic "ewgi middleware"
		  definition defines a stable interface that developers can
		  count on when reading/integrating 3rd party middleware.
		
	The ewgi_application module contains useful functions for
	creating / managing ewgi applications. 
	
	As an example... one of those useful functions is
	ewgi_application:mfa_mw/3 which allows turning a ewgi middleware
	into a ewgi application (something important if you need to combine
	it with other ewgi apps):
		MyApp = ewgi_application:mfa_mw(?MODULE, my_middleware, [Arg1, Arg2, ...])
	
	After which you can use it like this:
		MyApp(Ctx)
		
	or in a more complex stack:
		session_mw(cache_mw(MyApp(Ctx)))


What else?

	If you have ideas/patches/itches join us at
	http://groups.google.com/group/ewgi. :)
	
	That's about it. Hack away!