From 3a831a7baba0df0e137e7c9a03a775767c6cdb3f Mon Sep 17 00:00:00 2001 From: gered Date: Wed, 1 Jun 2016 17:32:24 -0400 Subject: [PATCH] add doc comments --- .../src/views/reagent/sente/client.cljs | 25 +++++++++++++-- .../src/views/reagent/sente/server.clj | 32 +++++++++++++++++-- 2 files changed, 53 insertions(+), 4 deletions(-) diff --git a/views.reagent.sente/src/views/reagent/sente/client.cljs b/views.reagent.sente/src/views/reagent/sente/client.cljs index 485669c..f11905e 100644 --- a/views.reagent.sente/src/views/reagent/sente/client.cljs +++ b/views.reagent.sente/src/views/reagent/sente/client.cljs @@ -22,16 +22,27 @@ (reset! send-buffer [])) (defn on-open! + "should be called when a new Sente connection is established. ev is the event + map provided by Sente where id = :chsk/state, and :open? = true. make sure + to call this function on all connection open events, not just the first one." [sente-chsk-map {:keys [event id client-id] :as ev}] (flush-send-buffer! sente-chsk-map) (client/on-open!)) (defn on-receive! + "should be called whenever a new message is received by Sente from the server. + ev is the event map provided by Sente where id = :chsk/recv. if this function + returns true it means the received message was for views.reagent and your + application code does not need to handle the event itself." [sente-chsk-map {:keys [event id client-id] :as ev}] (let [[event-id event-data] event] (client/on-receive! event-data))) -(defn event-msg-handler +(defn default-event-msg-handler + "very basic Sente event handler that can be used with Sente's start-chsk-router! + which makes sure on-open! and on-receive! are called when appropriate. if your + application does not need to do any custom Sente event handling, then you can + opt to use this event handler." [sente-chsk-map {:keys [event id client-id] :as ev}] (let [[ev-id ev-data] event] (cond @@ -43,7 +54,17 @@ (on-receive! sente-chsk-map ev)))) (defn init! + "performs initial configuration necessary to hook Sente into views.reagent as the + client/server messaging backend. should be called once on page-load after the + Sente channel socket has been created (via make-channel-socket!). + + extra available options specific to views.reagent/sente: + + :use-default-sente-router? + - if set, enables the use of a default Sente event handler (set via Sente's + start-chsk-router!). if your application does not need to respond to any + Sente events itself, then you may wish to use this option." [sente-chsk-map & [options]] (reset! client/send-fn #(send-fn sente-chsk-map %)) (if (:use-default-sente-router? options) - (sente/start-chsk-router! (:ch-recv sente-chsk-map) #(event-msg-handler sente-chsk-map %)))) + (sente/start-chsk-router! (:ch-recv sente-chsk-map) #(default-event-msg-handler sente-chsk-map %)))) diff --git a/views.reagent.sente/src/views/reagent/sente/server.clj b/views.reagent.sente/src/views/reagent/sente/server.clj index f41f90c..01ecbb3 100644 --- a/views.reagent.sente/src/views/reagent/sente/server.clj +++ b/views.reagent.sente/src/views/reagent/sente/server.clj @@ -13,25 +13,53 @@ ((:send-fn sente-chsk-map) uid [:views/refresh [view-sig view-data]])) (defn on-close! + "should be called when a client's Sente connection is closed. ev is the event + map provided by Sente where id = :chsk/uidport-close." [^Atom view-system {:keys [event id uid client-id ring-req ?reply-fn] :as ev}] (server/on-close! view-system uid ring-req)) (defn on-receive! + "should be called whenever a Sente event is raised that is *not* a connection + closed event (:chsk/uidport-close). ev is the event map provided by Sente + for the event. if this function returns true it means the received message + was for views.reagent and your application code does not need to handle the + event itself." [^Atom view-system {:keys [event id uid client-id ring-req ?reply-fn] :as ev}] (server/on-receive! view-system uid event ring-req)) -(defn event-msg-handler +(defn default-event-msg-handler + "very basic Sente event handler that can be used with Sente's start-chsk-router! + which makes sure on-close! and on-receive! are called when appropriate. if your + application does not need to do any custom Sente event handling, then you can + opt to use this event handler." [^Atom view-system {:keys [event id uid client-id] :as ev}] (if (= id :chsk/uidport-close) (on-close! view-system ev) (on-receive! view-system ev))) (defn init! + "initializes the views system and adds Sente-specific configuration to it to + enable the necessary hooks into views.reagent. this function acts as a direct + replacement to calling views.core/init!, so are able to initialize both views + and views.reagent by calling this function. the arguments and return value are + the same as in views.core/init! so see that function for more information. + + extra available options specific to views.reagent/sente: + + :context-fn + - a function that accepts an initial context map created by views.reagent and + allows your application to add any info necessary to the context map passed + to various view system functions (such as auth-fn, namespace-fn, etc). + + :use-default-sente-router? + - if set, enables the use of a default Sente event handler (set via Sente's + start-chsk-router!). if your application does not need to respond to any + Sente events itself, then you may wish to use this option." ([^Atom view-system sente-chsk-map options] (let [options (-> options (assoc :send-fn #(views-send-fn sente-chsk-map %1 %2)))] (if (:use-default-sente-router? options) - (sente/start-chsk-router! (:ch-recv sente-chsk-map) #(event-msg-handler view-system %))) + (sente/start-chsk-router! (:ch-recv sente-chsk-map) #(default-event-msg-handler view-system %))) (views/init! view-system options) (server/set-context-fn! view-system (:context-fn options)))) ([sente-chsk-map options]