Skip to content
Newer
Older
100644 168 lines (112 sloc) 6.06 KB
70d1414 @ohpauleez README update
authored
1 shoreleave
2 ==========
1ec7b96 @ohpauleez Quick drop
authored
3
4e70162 @ohpauleez Update README.mkd
authored
4 A smarter client-side in ClojureScript
1ec7b96 @ohpauleez Quick drop
authored
5
638bb3f @ohpauleez Update README.mkd
authored
6 ###Shoreleave is a collection of integrated libraries that focuses on:
1ec7b96 @ohpauleez Quick drop
authored
7
70d1414 @ohpauleez README update
authored
8 * Security
9 * Idiomatic interfaces
10 * Common client-side strategies
11 * HTML5 capabilities
12 * ClojureScript's advantages
1ec7b96 @ohpauleez Quick drop
authored
13
8eae822 @ohpauleez Moved the project, leaving this here for overall docs
authored
14 Installing and using
15 --------------------
16 You can pull all the pieces of Shoreleave into your project by adding the following to your `project.clj`
17
18 ```clojure
19 (defproject ...
20
21 :dependencies [[org.clojure/clojure "1.4.0"]
e3fa59d @ohpauleez Update README.mkd
authored
22 [shoreleave "0.2.2"]
23 [shoreleave/shoreleave-remote-noir "0.2.2"]
8eae822 @ohpauleez Moved the project, leaving this here for overall docs
authored
24 ...
25 ]
26 ...
27 )
28 ```
29
e3fa59d @ohpauleez Update README.mkd
authored
30 Individual utilies can be pulled in with `[shoreleave/UTILITY "0.2.2"]`. See the specific repo/artifact names below.
8eae822 @ohpauleez Moved the project, leaving this here for overall docs
authored
31
4e70162 @ohpauleez Update README.mkd
authored
32 Overview
33 ----------
34 Shoreleave has support for the following:
35
e3fa59d @ohpauleez Update README.mkd
authored
36 ### Common client-side interactions
37
38 * An idiomatic interface to cookies
39 * An idiomatic interface to browser history (with extended support for HTML5 History API)
40 * BlobBuilders and on-demand asset building
41 * (Coming soon) An idiomatic interface to browser storage (Local Storage, Session Storage, and App Cache)
42 * Common auxiliary functions out-of-the-box to handle query strings, browser-repl, hash strings, and CLJS/JS interop
43
4e70162 @ohpauleez Update README.mkd
authored
44 ### A remotes package
45
46 Shoreleave's remotes package includes XHR, Pooled-XHR, JSONP, and HTTP-RPC capabilities.
47
d9d63d4 @ohpauleez Update README.mkd
authored
48 CSRF protection is built in if your Clojure server is using the [ring-anti-forgery](https://github.com/weavejester/ring-anti-forgery) middleware.
4e70162 @ohpauleez Update README.mkd
authored
49
d9d63d4 @ohpauleez Update README.mkd
authored
50 The HTTP-RPC allows for exposing a server-side namespace as a client-side API, via a single server-side call, `remote-ns`.
51
52 A typical [Noir](http://www.webnoir.org/) setup might look like:
4e70162 @ohpauleez Update README.mkd
authored
53
1cde309 @ohpauleez Cleaning up the README a little
authored
54 ```clojure
55 (ns example
8eae822 @ohpauleez Moved the project, leaving this here for overall docs
authored
56 (:require [example.api] ; You don't have to pull this in, but it is suggested
57 [noir.shoreleave.rpc :as rpc]))
4e70162 @ohpauleez Update README.mkd
authored
58
1cde309 @ohpauleez Cleaning up the README a little
authored
59 ;; ...
60
61 ;; The Base Web Server
62 ;; ---------------------
63 ;; Serve every view file found in `src/example/views`
64 (server/load-views "src/example/views/")
65
66 ;; Remote Namespaces
67 ;; -----------------
68 (rpc/activate-remotes!)
8eae822 @ohpauleez Moved the project, leaving this here for overall docs
authored
69 (rpc/remote-ns 'example.api :as "api")
a70bef7 @ohpauleez Fixed up some typos
authored
70
1cde309 @ohpauleez Cleaning up the README a little
authored
71 ;; Middleware
72 ;;-----------
73 (server/add-middleware ring.middleware.gzip/wrap-gzip)
74 (server/add-middleware ring.middleware.file-info/wrap-file-info)
75 (server/add-middleware ring.middleware.anti-forgery/wrap-anti-forgery)
76 ```
77
78 You can also define single "global" rpc functions:
a70bef7 @ohpauleez Fixed up some typos
authored
79
1cde309 @ohpauleez Cleaning up the README a little
authored
80 ```clojure
81 (defremote ping []
82 (do
83 (println "Pinged by client!")
84 "PONG - from the server"))
85 ```
4e70162 @ohpauleez Update README.mkd
authored
86
87 ### A pub/sub abstraction (and implementations)
88
d9d63d4 @ohpauleez Update README.mkd
authored
89 _Why would I ever want to use this?_
90
a70bef7 @ohpauleez Fixed up some typos
authored
91 Shoreleave's pub/sub system enables you to completely decouple parts of your app and declaratively bind them together.
4e70162 @ohpauleez Update README.mkd
authored
92 New features and functionalities can be built by composing pre-existing services/publishables.
93
d9d63d4 @ohpauleez Update README.mkd
authored
94 Additionally you can express cross-cutting functionality (like logging or metrics reporting) as a service.
95
96
97 _Reactive ClojureScript_
98
a70bef7 @ohpauleez Fixed up some typos
authored
99 This gives you the heart of Reactive JavaScript (RxJS), without the additional verbs (both a benefit and a tradeoff).
4e70162 @ohpauleez Update README.mkd
authored
100 It's often most beneficial to use DOM listeners as entry-points into the pub/sub system.
101
102 - - -
103
d9d63d4 @ohpauleez Update README.mkd
authored
104 Shoreleave's pub/sub system is built upon two protocols: "brokers" and "publishables"
4e70162 @ohpauleez Update README.mkd
authored
105
4b1f807 @ohpauleez Small update about pubsub and web workers
authored
106 Out of the box, Shoreleave allows you to publish funtions, atoms, web workers, and anything that implements (str ...)/.toString, as topics.
5dea624 @ohpauleez README now includes updated bus information
authored
107 The `simple` pub/sub bus has very little overhead, but operates synchronously. You can trade-off some performance for an async bus, the `event` pubsub bus.
4e70162 @ohpauleez Update README.mkd
authored
108
4b1f807 @ohpauleez Small update about pubsub and web workers
authored
109 (In-progress) The cross document bus has a small amount of overhead, but allows you to publish and subscribe from/to functions that live in other web workers
d9d63d4 @ohpauleez Update README.mkd
authored
110 or windows (in-browser concurrency for "free").
4e70162 @ohpauleez Update README.mkd
authored
111
5dea624 @ohpauleez README now includes updated bus information
authored
112 In most cases, the simple bus is the best choice.
113
4e70162 @ohpauleez Update README.mkd
authored
114 ### Common external API support
115
116 Shoreleave has JSONP-wrapped support for external APIs including:
117
118 * Google Maps
d9d63d4 @ohpauleez Update README.mkd
authored
119 * DuckDuckGo Zero-Click
4e70162 @ohpauleez Update README.mkd
authored
120 * (Coming soon) Wikipedia and Alpha
121
f4cc3ee @ohpauleez Typo
authored
122 ### An enhanced ClojureScript experience
4e70162 @ohpauleez Update README.mkd
authored
123
124 * A `Function` object that supports metadata
91b0b59 @ohpauleez Update to reflect newest pieces
authored
125 * The ability to create embedded web workers
70d1414 @ohpauleez README update
authored
126
e3fa59d @ohpauleez Update README.mkd
authored
127
8eae822 @ohpauleez Moved the project, leaving this here for overall docs
authored
128 Where's the code?
129 -----------------
c262344 @ohpauleez Update master
authored
130 Shoreleave is a big project and has been split up into smaller pieces within the [Shoreleave organization](https://github.com/shoreleave):
8eae822 @ohpauleez Moved the project, leaving this here for overall docs
authored
131
132 * [shoreleave-core](https://github.com/shoreleave/shoreleave-core) - [Marg docs](http://shoreleave.github.com/shoreleave-core/)
d5020fd @ohpauleez Fixed broken link
authored
133 * [shoreleave-browser](https://github.com/shoreleave/shoreleave-browser) - [Marg docs](http://shoreleave.github.com/shoreleave-browser/)
8eae822 @ohpauleez Moved the project, leaving this here for overall docs
authored
134 * [shoreleave-pubsub](https://github.com/shoreleave/shoreleave-pubsub) - [Marg docs](http://shoreleave.github.com/shoreleave-pubsub/)
135 * [shoreleave-remote](https://github.com/shoreleave/shoreleave-remote) - [Marg docs](http://shoreleave.github.com/shoreleave-remote/)
04c2f5a @ohpauleez Update README.mkd
authored
136 * [shoreleave-remote-noir](https://github.com/shoreleave/shoreleave-remote-noir) - Temp [Marg docs](http://shoreleave.github.com/shoreleave-remote-noir/)
137 * [shoreleave-services](https://github.com/shoreleave/shoreleave-services) - Temp [Marg docs](http://shoreleave.github.com/shoreleave-services/)
8eae822 @ohpauleez Moved the project, leaving this here for overall docs
authored
138 * [shoreleave-worker](https://github.com/shoreleave/shoreleave-worker) - [Marg docs](http://shoreleave.github.com/shoreleave-worker/)
139
140
70d1414 @ohpauleez README update
authored
141 Plays well with others
142 ----------------------
a70bef7 @ohpauleez Fixed up some typos
authored
143 Shoreleave makes no assumptions about other libraries you might be using in your app.
d9d63d4 @ohpauleez Update README.mkd
authored
144
145 I have found it to pair particularly well with [Enfocus](https://github.com/ckirkendall/enfocus)
70d1414 @ohpauleez README update
authored
146
147
148 Examples and usage
149 ------------------
e3fa59d @ohpauleez Update README.mkd
authored
150 Please the github doc pages (ie: Marginalia docs) above for library specifics.
151
152 There is a community-contributed [demo app](https://github.com/robert-stuttaford/demo-enfocus-pubsub-remote) thanks to the hard work of [Robert Stuttaford](https://github.com/robert-stuttaford)
153
154
155 Google Group and General Help
156 ------------------------------
f51615f @ohpauleez Update README.mkd
authored
157 There is a [Shoreleave CLJS](https://groups.google.com/forum/#!forum/shoreleave-cljs) Google Group. Please feel free to post all questions and general comments there.
e3fa59d @ohpauleez Update README.mkd
authored
158
159 Additionally, you can ping `ohpauleez` in #clojure on Freenode.
160
70d1414 @ohpauleez README update
authored
161
162 License
163 -------
1ec7b96 @ohpauleez Quick drop
authored
164 Copyright (C) 2012 Paul deGrandis
165
166 Distributed under the Eclipse Public License, the same as Clojure.
167
Something went wrong with that request. Please try again.