5 | src 6 | ├── core.cljs <--- entry point, plus history, routing, etc 7 | ├── db.cljs <--- schema, validation, etc (data layer) 8 | ├── views.cljs <--- reagent views (view layer) 9 | ├── events.cljs <--- event handlers (control/update layer) 10 | └── subs.cljs <--- subscription handlers (query layer) 11 |12 | 13 | For a living example of this approach, look at the [todomvc example](https://github.com/day8/re-frame/tree/master/examples/todomvc). 14 | 15 | ## The Gotcha 16 | 17 | If you adopt this structure, there's a gotcha. 18 | 19 | `events.cljs` and `subs.cljs` will never be `required` by any other 20 | namespaces. To the Google Closure dependency mechanism, it appears as 21 | if these two namespaces are not needed and it doesn't load them. 22 | 23 | And, if the namespaces are not loaded, the registrations in these namespaces will 24 | never happen. And, then you'll be staring at your running app very 25 | puzzled about why none of your events handlers are registered. 26 | 27 | Once you twig to what's going on, the solution is easy. You must 28 | explicitly `require` both namespaces, `events` and `subs`, in your `core` 29 | namespace. Then they'll be loaded and the registrations (`reg-sub`, `reg-event-fx`, 30 | etc) will occur as that loading happens. 31 | 32 | ## Larger Apps 33 | 34 | Assuming your larger apps have multiple "panels" (or "views") which are 35 | relatively independent, you might use this structure: 36 |
37 | src 38 | ├── core.cljs <--- entry point, plus history, routing, etc 39 | ├── panel-1 40 | │ ├── db.cljs <--- schema, validation, etc (data layer) 41 | │ ├── subs.cljs <--- subscription handlers (query layer) 42 | │ ├── views.cljs <--- reagent components (view layer) 43 | │ └── events.cljs <--- event handlers (control/update layer) 44 | ├── panel-2 45 | │ ├── db.cljs <--- schema, validation. etc (data layer) 46 | │ ├── subs.cljs <--- subscription handlers (query layer) 47 | │ ├── views.cljs <--- reagent components (view layer) 48 | │ └── events.cljs <--- event handlers (control/update layer) 49 | . 50 | . 51 | └── panel-n 52 |53 | 54 | 55 | ## Namespaced Ids 56 | 57 | As an app gets bigger, you'll tend to get clashes on ids - event-ids, or query-ids (subscriptions), etc. 58 | 59 | One panel will need to `dispatch` an `:edit` event and so will 60 | another, but the two panels will have different handlers. 61 | So, how do you avoid a clash? How do you distinguish between 62 | one `:edit` event and another? 63 | 64 | Your goal should be to use event-ids which encode both the event 65 | itself (`:edit` ?) and the context (`:panel1` or `:panel2` ?). 66 | 67 | Luckily, ClojureScript provides a nice easy solution: use keywords 68 | with a __synthetic namespace__. Perhaps something like `:panel1/edit` and `:panel2/edit`. 69 | 70 | You see, ClojureScript allows the namespace in a keyword to be a total 71 | fiction. I can have the keyword `:panel1/edit` even though 72 | `panel1.cljs` doesn't exist. 73 | 74 | Naturally, you'll take advantage of this by using keyword namespaces 75 | which are both unique and descriptive. 76 | 77 | ## Navigation 78 | 79 | 80 | How do I switch between different panels of a larger app? 81 | 82 | Your `app-db` could have an `:active-panel` key containing an id for the panel being displayed. 83 | 84 | 85 | When the user does something navigation-ish (selects a tab, a dropdown or something which changes the active panel), then the associated event and dispatch look like this: 86 | 87 | ```clj 88 | (re-frame/reg-event-db 89 | :set-active-panel 90 | (fn [db [_ value]] 91 | (assoc db :active-panel value))) 92 | 93 | (re-frame/dispatch 94 | [:set-active-panel :panel1]) 95 | ``` 96 | 97 | A high level reagent view has a subscription to :active-panel and will switch to the associated panel. 98 | 99 | ```clj 100 | (re-frame/reg-sub 101 | :active-panel 102 | (fn [db _] 103 | (:active-panel db))) 104 | 105 | (defn panel1 106 | [] 107 | [:div {:on-click #(re-frame/dispatch [:set-active-panel :panel2])} 108 | "Here" ]) 109 | 110 | (defn panel2 111 | [] 112 | [:div "There"]) 113 | 114 | (defn high-level-view 115 | [] 116 | (let [active (re-frame/subscribe [:active-panel])] 117 | (fn [] 118 | [:div 119 | [:div.title "Heading"] 120 | (condp = @active ;; or you could look up in a map 121 | :panel1 [panel1] 122 | :panel2 [panel2])]))) 123 | ``` 124 | -------------------------------------------------------------------------------- /docs/EPs/003-ReusableComponents.md: -------------------------------------------------------------------------------- 1 | ## EP 003 - Enabling Creation Of Reusable Components 2 | 3 | > Status: Placeholder. Don't bother reading yet. 4 | 5 | ### Abstract 6 | 7 | This EP proposes changes to facilitate easier use of React's Context feature. 8 | XXX to make it easier to write more complex Reusable components. 9 | 10 | ### Background 11 | 12 | React components form a tree, with values being passed down 13 | through the hierarchy in the form of `props`. All very functional. 14 | 15 | Except there are some problems: 16 | - it can be a PITA to pass every little bit of data through many, many layers. 17 | Manual and time-consuming. 18 | - often we don't want to burden intermediate layers with knowledge about 19 | what leaf nodes needed. That kind of "unnecessary knowing" leads to 20 | various kinds of fragility. 21 | - if we are using someone else's layout components, we may have not have 22 | control over what they pass to children. 23 | 24 | [Algebraic Effects](http://math.andrej.com/eff/) are intended to help solve 25 | these kinds of problems in a functional way, but that's not our world. 26 | 27 | The solution available in React is called `Context`. It is a mechanism for allowing 28 | data to be "shared" globally within a given tree of React components 29 | (without it needing for it to be passed/threaded through all layers of that tree). 30 | 31 | [React's context docs are here](https://reactjs.org/docs/context.html). 32 | 33 | ### Components 34 | 35 | `re-com` is a library which supplies reusable Reagent widgets. And `widgets`, 36 | like a datepicker, are the simplest kind of components. 37 | 38 | `re-com` components are reusability because they take `an input stream` of data 39 | and they 40 | 41 | achieves reusablity by passing in values and supplying callbacks. This works at 42 | the level of simple widgets. 43 | 44 | But re-frame components need to subscribe and dispatch. 45 | 46 | XXX talk about `dispatch back` rather than `callback` 47 | 48 | XXX need to identify the part of `app-db` on which `event handlers` and `subscriptions` should operate. 49 | 50 | 51 | -------------------------------------------------------------------------------- /docs/EPs/004-ViewRegistration.md: -------------------------------------------------------------------------------- 1 | ## EP 003 - View Registration 2 | 3 | > Status: Placeholder. Only scribbles. Don't read yet. 4 | 5 | 6 | ### Abstract 7 | 8 | Broadbrush: 9 | - views will be registered via a new `re-frame.core/def-view` function 10 | - like other re-frame registration functions, `def-view` associates a `keyword` with a (reagent) render function 11 | - the registered view keyword (eg: `:my-view`) can be used in hiccup to identify the renderer. eg: `[:my-view "Hello world"]` 12 | - `def-view` allows various values to be `injected` as args into the view render 13 | - see https://github.com/reagent-project/reagent/issues/362 14 | 15 | Why: 16 | - removing (render) functions from hiccup will make hiccup even more data oriented. Symptoms include helping with various state machine ideas. 17 | - injection of `dispatch` and `subscribe` will help view functions to be slightly more pure. `dispatch` still kinda a problem. 18 | - ijection of `context` which will help with "multiple re-frame apps on the one page" problem 19 | 20 | What might need to be injected (as args) into a view: 21 | 22 | - `subscribe` and `dispatch` 23 | - a `frame` supplied via `context` (subscribe and dispatch obtained from frame) 24 | - other context: data from higher in the DOM tree 25 | - animation? CSS ? 26 | 27 | XXX searches up the DOM hierarchy looking for a `frame` context then extracts dispatch and subscribe. Sounds inefficient. 28 | 29 | ### Code Doodle #1 30 | 31 | Associate the keyword `:my-view-id ` with a renderer using `def-view`: 32 | ```clj 33 | (def-view 34 | :my-view-id 35 | 36 | ;; indicate what `context` is required 37 | [:dispatch :subscribe :context XXX] 38 | 39 | ;; the renderer 40 | ;; last argument `context` is a map of: 41 | ;; - `:subs` - a vector of subscription values? 42 | ;; - :dispatch and :subscribe 43 | ;; - :context - a vector of context values 44 | ;; 45 | (fn [a-str context] 46 | (let [XXXX] 47 | ))) 48 | ``` 49 | 50 | Use of `:my-view-id `: 51 | ```clj 52 | [:my-view-id "Hello"] 53 | ``` 54 | 55 | ### Code Doodle #2 56 | 57 | Associate the keyword `:my-view-id ` with a renderer using `def-view`: 58 | ```clj 59 | (def-view 60 | :my-view-id 61 | 62 | ;; injection function 63 | ;; indicate what subscriptions we wish to obtain 64 | ;; obtain a dispatch for use 65 | ;; get the context id if you want to 66 | ;; 67 | :subscriptions 68 | (fn [_ id] 69 | {:subs [[:item ]] 70 | :context ["name1", "name2")}) 71 | 72 | 73 | ;; the renderer 74 | ;; last argument `ins` is a map of: 75 | ;; - `:subs` - a vector of subscription values? 76 | ;; - :dispatch and :subscribe 77 | ;; - :context - a vector of context values 78 | ;; 79 | (fn [a-str ins] 80 | (let [XXXX] 81 | ))) 82 | ``` 83 | 84 | Use of `:my-view-id `: 85 | ```clj 86 | [:my-view-id "Hello"] 87 | ``` 88 | 89 | ### Code Doodle #3 90 | 91 | `[:something arg1 arg2]` 92 | 93 | ```clj 94 | (def-view 95 | :something 96 | (fn [arg1 arg2] 97 | ;; obtain dispatch and subscription 98 | ;; obtain a subscription or two 99 | ;; add a key on the component 100 | (fn [arg1 arg2] 101 | )) 102 | 103 | ``` 104 | 105 | ## Misc Notes 106 | 107 | - reagent hiccup will be changed/monkey-patched so that views can be identified by keyword 108 | - Views are the leaves of the signal graph. They need to subscribe and dispatch. 109 | - how to obtain other pieces of `context` (beyond the current frame) 110 | 111 | 112 | XXX There's a nasty problem with frames and subscriptions. How does the signal function know what frame to create new subscriptions against??? 113 | 114 | ## Usage 115 | 116 | 117 | -------------------------------------------------------------------------------- /docs/EPs/README.md: -------------------------------------------------------------------------------- 1 | EP 2 | 3 | This directory contains re-frame "Enhancement Proposals" (EPs), one per file. 4 | 5 | ## Status 6 | 7 | Each EP proceeds through the following stages: 8 | - **Placeholder** - skeleton at best. One day someone might write something. 9 | - **Drafting** - some writing and thinking has been done, but it may be incoherent and/or wrong. 10 | - **UnderReview** - ready for general discussion in a specifically created (repo) Issue. 11 | - **Accepted** or **Rejected** 12 | - **Released** 13 | 14 | 15 | ## List 16 | 17 | - [EP 001 - Capture Handler Metadata](001-CaptureHandlerMetadata.md) - Drafting 18 | - [EP 002 - Multiple re-frame Instances](002-ReframeInstances.md) - Drafting 19 | - [EP 003 - Reusable Components Via context](003-ReusableComponents.md) - Placeholder 20 | - [EP 004 - View Registration](004-ViewRegistration.md) - Placeholder 21 | - [EP 005 - State Machines](005-StateMachines.md) - Placeholder 22 | 23 | -------------------------------------------------------------------------------- /docs/FAQs/BestPractice.md: -------------------------------------------------------------------------------- 1 | 4 | # 5 | 6 | 7 | ## Question 8 | 9 | What are the current best practices? 10 | 11 | ## Answer 12 | 13 | To grasp best practices: 14 | 15 | 1. Read through the re-frame documentation. 16 | 2. Review example projects, like this [RealWorld example](https://github.com/jacekschae/conduit). The [Resources doc](http://day8.github.io/re-frame/External-Resources/#examples-and-applications-using-re-frame) provides further examples. 17 | 18 | Keep in mind, best practices evolve over time. Here are some of the more recent ideas. 19 | 20 | ### Use Namespaced Keywords 21 | 22 | In the interests of minimalism, the docs don't use namespaced keywords for ids (event ids, subscription ids, etc), but in prectice you should. 23 | 24 | You can use either synthetic or real namespaces in your ids, but some experienced re-framers claim you should only use real namespaces. I remain unconvinced. Shrug. 25 | 26 | Tip: tooling like `clojure-lsp` can help you to navigate to where an event id or subsription id is registered. 27 | 28 | ### Structuring `app-db` 29 | 30 | While using `app-db` as a simple map works well in many situations, if you want more structure, consider using a library like [doxa](https://github.com/ribelo/doxa) or [relic](https://github.com/wotbrew/relic). 31 | 32 | ### Use the `:fx` effect 33 | 34 | While event handlers can return a map of arbitrary effects, it is now recommended that they only return 35 | a map containing two standard keys `:db` and `:fx`. Learn more [here](https://day8.github.io/re-frame/api-builtin-effects/#fx) and [here](http://day8.github.io/re-frame/releases/2020/#110-2020-08-24). 36 | 37 | ### Compose Event Handlers 38 | 39 | Event handlers can be composed of other functions through the use of the `:db` / `:fx` effect pattern, which is described [here](https://github.com/day8/re-frame/issues/639#issuecomment-682250517) 40 | 41 | ### Avoid Placeful Events 42 | 43 | Originally, it was recommended that events be a vector like this `[:some-event-id arg1 arg2]`. This works reasonably for simple cases, but it does introduce fragility for more complex use cases due to the lnherent "placefulness" of vectors. 44 | 45 | A better practice is to encapsulate the "args" into a single map: `[:some-event-id {:x arg1 :another arg2}]` 46 | 47 | And then to optionally use the `unwrap` middleware on the associated event handlers. See [here](http://day8.github.io/re-frame/api-re-frame.core/#unwrap) 48 | 49 | -------------------------------------------------------------------------------- /docs/FAQs/DB_Normalisation.md: -------------------------------------------------------------------------------- 1 | 2 | 5 | # 6 | 7 | ## Question 8 | 9 | `app-db` contains a `map`. How do I store normalised data in a `map`, 10 | bettering mirroring the structure in my server-side database? 11 | 12 | ## Answer 13 | 14 | These libraries might be interesting to you: 15 | 16 | - [compound](https://github.com/riverford/compound) 17 | - [SubGraph](https://github.com/vimsical/subgraph) 18 | - [pull](https://github.com/juxt/pull) 19 | - [reflet](https://github.com/zalky/reflet) - use normalised and non-normalised data in the same `app-db` 20 | 21 | See also [this comment](https://github.com/day8/re-frame/issues/304#issuecomment-269620609). 22 | 23 | If you want to go whole hog and ditch `app-db` and embrace DataScript, 24 | then you might find [re-posh](https://github.com/denistakeda/re-posh) interesting. 25 | -------------------------------------------------------------------------------- /docs/FAQs/DoINeedReFrame.md: -------------------------------------------------------------------------------- 1 | 2 | 5 | # 6 | 7 | ## Question 8 | 9 | Reagent looks terrific. So, why do I need re-frame? What benefit 10 | is there in the extra layers and conceptual overhead it brings? 11 | 12 | ## Answer 13 | 14 | Yes, we agree, Reagent is terrific. We use it enthusiastically ourselves. And, yes, we'd agree that if your application 15 | is small and simple, then standalone Reagent is a reasonable choice. 16 | 17 | But it does only supply the V part of the MVC triad. As your application 18 | gets bigger and more complicated, you *will* need to find solutions to 19 | questions in the M and C realms. 20 | 21 | Questions like "where do I put control logic?". 22 | And, "how do I store and update state?". 23 | And, "how should new websocket packets be communicated with the broader app"? Or GET failures? 24 | And, "how do I put up a spinner 25 | when waiting for CPU intensive computations to run, while allowing the user to press Cancel?" 26 | How do I ensure efficient view updates? How do I write my control logic in a way that's testable? 27 | 28 | These questions accumulate. 29 | 30 | Reagent, by itself, provides little guidance and, so, you'll need to 31 | design your own solutions. Your choices will also accumulate and, 32 | over time, they'll become baked into your codebase. 33 | 34 | Now, any decision which is hard to revisit later is an architectural decision - 35 | "difficult to change later" is pretty much the definition of "architecture". So, 36 | as you proceed, baking your decisions into your codebase, you will be 37 | incrementally growing an architecture. 38 | 39 | So, then, the question is this: is your architecture better than re-frame's? Because 40 | that's what re-frame gives you ... an architecture ... solutions to the 41 | various challenges you'll face when developing your app, and mechanism for implementing 42 | those solutions. 43 | 44 | Now, in response, some will enthusiastically say "yes, I want to grow my own 45 | architecture. I like mine!". And fair enough - it can be an interesting ride! 46 | 47 | Problems arise ONLY when this process is not conscious and purposeful. It is a 48 | credit to Reagent that you can accelerate quickly and get a bunch of enjoyable 49 | early wins. But, equally, that acceleration can have you off the road 50 | in a ditch because of the twists and turns on the way to a larger application. 51 | 52 | I've had many people (20?) privately say to me that's what happened to them. 53 | And that's pretty much the reason for this FAQ - this happens a bit too often 54 | and there's been a bit too much pain. 55 | 56 | So, my advice is ... if your application is a little more complicated, 57 | be sure to make a conscious choice around architecture. Don't think 58 | "Reagent is all I need", because it isn't. One way or 59 | another you'll be using "Reagent + a broader architecture". 60 | 61 | ## Example Choices Made By re-frame 62 | 63 | 1. Events are cardinal. Nothing happens without an event. 64 | 2. Events are data (so they are loggable, and can be queued, etc). 65 | 3. Dispatched events are handled async - they are put in a queue and handled very soon, but not now (for a variety of subtle reasons). 66 | 4. For efficiency, subscriptions (reactions) should be layered and de-duplicated. 67 | 5. Views are never imperative or side effecting (best effort). 68 | 6. Unidirectional data flow only, ever. 69 | 7. Interceptors over middleware. Provide cross cutting concerns like logging and debugging. 70 | 8. Event handlers capture control and contain key logic. Ensure purity via coeffects and effects. 71 | 9. All state is stored in one place. 72 | 10. State is committed-to transactionally, never incrementally or piecemeal. 73 | 74 | Hmm. I feel like I'm missing a few, but that's certainly an indicative list. 75 | 76 | re-frame is only about 750 lines of code. So its value is much more in the honed 77 | choices it embodies (and documents), than the code it provides. 78 | 79 | ## What Reagent Does Provide 80 | 81 | Above I said: 82 | > Reagent, by itself, provides little guidance ... 83 | 84 | which is true but, it does provide useful building blocks. If you do want to create 85 | your own architecture, then be sure to check out Reagent's `track`, `reaction` and `rswap`. 86 | 87 | There's also other Reagent-based architectures like [keechma](https://github.com/keechma/keechma) and 88 | [carry](https://github.com/metametadata/carry) which make different choices - ones which may 89 | better suit your needs. 90 | -------------------------------------------------------------------------------- /docs/FAQs/FocusOnElement.md: -------------------------------------------------------------------------------- 1 | 2 | 5 | # 6 | 7 | ## Question 8 | 9 | How do I switch "focus" to a particular HTML element? 10 | 11 | ## HTML autofocus 12 | 13 | Perhaps you can use the `autofocus` HTML element attribute like this: 14 | ```cljs 15 | (defn view 16 | [] 17 | [:input {:type "text" :id "my-id" :auto-focus true]) 18 | ``` 19 | 20 | But this might not work in Safari these days (Safari is the new IE 6 of browsers). 21 | 22 | Instead, you could use a more portable (but more complicated) version of this approach, which uses React `refs` with a Form-3 component: 23 | ```clj 24 | (defn my-input [] 25 | (let [ref (atom nil)] 26 | (r/create-class 27 | {:component-did-mount 28 | (fn [_] 29 | (.focus @ref)) 30 | :reagent-render 31 | (fn [_] 32 | [:input {:ref #(reset! ref %)}])}))) 33 | ``` 34 | 35 | A terse way of achieving the same outcome is: 36 | ```clj 37 | [:input {:ref #(when % (.focus %)}] 38 | ``` 39 | 40 | But all these approaches only cause focus once, when the widget is first rendered. You may need to have more control than that. 41 | 42 | ## Reagent after-render 43 | 44 | If you want to switch focus between elements after they have first rendered, 45 | you can create an `effect handler` which uses Reagent's `after-render` API to 46 | register a function that will imperatively set focus: 47 | ```clj 48 | (re-frame.core/reg-fx 49 | :focus-to-element 50 | (fn [element-id] 51 | (reagent/after-render #(some-> js/document (.getElementById element-id) .focus)))) 52 | ``` 53 | _WARNING_: as written, this code will fail silently if `element-id` is not found. If you use this 54 | code fragment, you may want to detect and report that problem. 55 | 56 | You can then use this effect within your event handler: 57 | ```clj 58 | (re-frame.core/reg-event-fx 59 | :something 60 | (fn [cofx event] 61 | {:db .... 62 | :focus-to-element some-element-id})) 63 | ``` 64 | 65 | This assumes you can compute or obtain the `some-element-id` value 66 | for the HTML element on which you want focus. 67 | 68 | One small trick: we perform the imperative focus using 69 | `Reagent/after-render` because sometimes the target 70 | HTML element won't exist in the DOM until after the rendering 71 | which occurs in the next animation frame. 72 | -------------------------------------------------------------------------------- /docs/FAQs/FullStackReframe.md: -------------------------------------------------------------------------------- 1 | 2 | 5 | # 6 | 7 | ## Question 8 | 9 | I'm interested in taking the re-frame concepts and applying them to 10 | my entire Client/Server stack. 11 | 12 | ## The Short Answer 13 | 14 | You'll want to investigate CQRS. 15 | 16 | ## The Longer Answer 17 | 18 | 1. Perhaps watch [Bobby Calderwood's video](https://www.youtube.com/watch?v=B1-gS0oEtYc)? 19 | 2. Look at his [reference implementation](https://github.com/capitalone/cqrs-manager-for-distributed-reactive-services) or, perhaps, [this alternative](https://github.com/greywolve/calderwood). 20 | 4. Be aware that "Event Sourcing" often comes along for the ride 21 | with CQRS, but it doesn't have to. It adds complexity (Kafka?). 22 | Don't do it lightly. Maybe just use CQRS without ES? 23 | 5. If you do want Event Sourcing, then Kafka might be your friend, 24 | Greg Young might be your God and [Onyx](https://github.com/onyx-platform/onyx) 25 | may be useful. 26 | 27 | ## Further Related Links 28 | 29 | * Reactive PostgreSQL: 30 | https://yogthos.net/posts/2016-11-05-LuminusPostgresNotifications.html 31 | * Datalog All The Way Down: 32 | https://www.youtube.com/watch?v=aI0zVzzoK_E 33 | -------------------------------------------------------------------------------- /docs/FAQs/GlobalInterceptors.md: -------------------------------------------------------------------------------- 1 | 2 | 5 | # 6 | 7 | ## Question 8 | 9 | Does re-frame allow me to register global interceptors? Ones which are included 10 | for every event handler? 11 | 12 | ## Answer (v1.0.0 onwards) 13 | 14 | Yes, re-frame provides an API for registering global interceptors. 15 | 16 | The following code creates a global interceptor to keep a track of all events: 17 | 18 | ```clj 19 | ;; We'll be recording events into this atom 20 | ;; The most recent events will be at the front of the list. 21 | (def event-store (atom (list))) 22 | 23 | 24 | (defn keep-last-20 25 | [existing new-one] 26 | (take 20 (conj existing new-one))) 27 | 28 | 29 | ;; this interceptor will collect events and add them to the atom above 30 | (def event-collector 31 | (re-frame.core/->interceptor 32 | :id :event-collector 33 | :before (fn [context] 34 | (swap! event-store keep-last-20 (re-frame.core/get-coeffect context :event)) 35 | context))) 36 | 37 | ;; register this global interceptor early in program's boot process, 38 | ;; using re-frame's API 39 | (re-frame.core/reg-global-interceptor event-collector) 40 | ``` 41 | 42 | 43 | ## Answer (prior to v1.0.0) 44 | 45 | Prior to v1.0.0, re-frame provided no API to directly support this feature, 46 | but there are ways of making it happen. 47 | 48 | Let's assume you have an interceptor called `omni-ceptor` which you want 49 | automatically added to all your event handlers. 50 | 51 | You'd write a replacement for both `reg-event-db` and `reg-event-fx`, and get 52 | these replacements to automatically add `omni-ceptor` to the interceptor 53 | chain at registration time. 54 | 55 | Here's how to write one of these auto-injecting replacements: 56 | ```clj 57 | (defn my-reg-event-db ;; a replacement for reg-event-db 58 | 59 | ;; 2-arity with no interceptors 60 | ([id handler] 61 | (my-reg-event-db id nil handler)) 62 | 63 | ;; 3-arity with interceptors 64 | ([id interceptors handler] 65 | (re-frame.core/reg-event-db ;; which uses reg-event-db 66 | id 67 | [omni-ceptor interceptors] ;; <-- inject `omni-ceptor` 68 | handler))) 69 | ``` 70 | 71 | NB: did you know that interceptor chains are flattened and nils are removed? 72 | 73 | With this in place, you would always use `my-reg-event-db` 74 | instead of the standard `reg-event-db`: 75 | ```clj 76 | (my-reg-event-db 77 | :event-id 78 | (fn [db v] 79 | ...)) 80 | ``` 81 | 82 | And, hey presto, you'd have your `omni-ceptor` "globally" injected. 83 | -------------------------------------------------------------------------------- /docs/FAQs/Inspecting-app-db.md: -------------------------------------------------------------------------------- 1 | 2 | 5 | # 6 | 7 | ## Question 8 | 9 | How can I inspect the contents of `app-db`? Perhaps from figwheel. 10 | 11 | ## Short Answer 12 | 13 | If at a REPL, inspect: `re-frame.db/app-db`. 14 | 15 | If at the js console, that's `window.re_frame.db.app_db.state`. 16 | 17 | If you want a visual browser of app-db, along with inspecting subpaths of app-db, and diffing changes, use [re-frame-10x](https://github.com/day8/re-frame-10x). 18 | 19 | You are [using cljs-devtools](https://github.com/binaryage/cljs-devtools), right? 20 | If not, stop everything ([unless you are using re-natal](https://github.com/drapanjanas/re-natal/issues/137)) and immediately make that happen. 21 | 22 | ## Better Answer 23 | 24 | Are you sure you need to? 25 | 26 | First, you seldom want to inspect all of `app-db`. 27 | And, second, inspecting via a REPL might be clumsy. 28 | 29 | Instead, you probably want to inspect a part of `app-db`. __And__ you probably want 30 | to inspect it directly in the GUI itself, not off in a REPL. 31 | 32 | Here is a useful technique from @escherize. Add something like this to 33 | the hiccup of your view ... 34 | ```clj 35 | [:pre (with-out-str (pprint @interesting))] 36 | ``` 37 | This assumes that `@interesting` is the value (ratom or subscription) 38 | you want to observe (note the @ in front). 39 | 40 | `pprint` output is nice to read, but not compact. For a more compact view, do this: 41 | ```clj 42 | [:pre (pr-str @some-atom)] ;; NB: using pr-str instead of pprint 43 | ``` 44 | 45 | If you choose to use `pprint` then you'll need to `require` it within the `ns` of your `view.cljs`: 46 | ```clj 47 | [cljs.pprint :refer [pprint]] 48 | ``` 49 | 50 | Finally, combining the short and long answers, you could even do this: 51 | ```clj 52 | [:pre (with-out-str (pprint @re-frame.db/app-db))] ;; see everything! 53 | ``` 54 | or 55 | ```clj 56 | [:pre (with-out-str (pprint (:part @re-frame.db/app-db)))] ;; see a part of it! 57 | ``` 58 | 59 | You definitely have [clj-devtools](https://github.com/binaryage/cljs-devtools) installed now, right? 60 | 61 | ## Other Inspection Tools 62 | 63 | Another very strong tool is [re-Frisk](https://github.com/flexsurfer/re-frisk) which 64 | provides a nice solution for navigating and inspecting your re-frame data structures. 65 | 66 | @yogthos' [json-html library](https://github.com/yogthos/json-html) provides 67 | a slick presentation, at the expense of more screen real estate, and the 68 | need to include specific CSS. 69 | 70 | 71 | 72 | -------------------------------------------------------------------------------- /docs/FAQs/LoadOnMount.md: -------------------------------------------------------------------------------- 1 | 2 | 5 | # 6 | 7 | ## Question 8 | 9 | How do I load the data for a view, when the user navigates to that view? 10 | 11 | ## For Javascript The Developer 12 | 13 | Are you from the Javascript/React world? If so, this first section is for you. 14 | 15 | In re-frame, Components are functions. They compute a materialized view of values which are reactively delivered, and they don't have state. 16 | 17 | On the other hand, React has a more OO sense of Components. They are classes with state and behaviour. And even React's more modern, so-called function components come with Hooks which are ordered, and often imperative and effectful. 18 | 19 | So, with respect to Components, re-frame and React are technically different. But it is on a philosophical point that they differ the most: 20 | 21 | - In re-frame, **Components are not causal**, they are reactive. 22 | - Whereas React Components are often deeply causal, via Collocated queries, ComponentDidMount, Hooks and Suspense, etc. In React, Components initiate things - like HTTP requests. 23 | - In re-frame, ***it is events which are causal*** (never components). 24 | 25 | ### Why this difference? 26 | 27 | > Humans have a cognitive bias: "what is focal is presumed causal". 28 | 29 | Political leaders know this. They like presenting good news themselves because they like to 30 | be "seen" as causal of good stuff, but they'll get a press secretary to deliver bad news. 31 | Movie directors know how to use this when framing their protagonists within the story. 32 | 33 | Unfortunately, the React team have lost themselves in this bias. They keep trying to make the 34 | most focal part of the system (components) also be the causal part. Please stop doing that! It is a mistake. Events are what's causal - they embody the user's intent. 35 | 36 | Just to be clear, I love React. What an utterly brilliant idea and great execution. 37 | I'm deeply grateful because, wow!, did it change things. 38 | It is just that I preferred React when it was only trying to be the V part of MVC. Everything since has been downhill. 39 | 40 | Perhaps read the further explanation in [PurelyFunctional.tv's writeup](https://purelyfunctional.tv/article/react-vs-re-frame/) under the heading "Reacters load data on mount". 41 | 42 | ## Do This Instead 43 | 44 | With re-frame, imperative, effectful stuff only ever happens during the handling of an event. 45 | 46 | When the user clicks on a tab to change what is shown 47 | to them in the UI, an event is dispatched, and it is 48 | the associated event handler which will compute the 49 | effects of the user's request. That might include: 50 | 51 | 1. change application state so the panel is shown 52 | 2. further change application state so that a "twirly busy" thing is shown 53 | 3. issue a database query or open a websocket 54 | 55 | Also, remember that events should model "user intent", like 56 | "review overdue items". Be sure to never model events like 57 | "load overdue items from database" because that's just a 58 | low level operation performed in the service of fulfilling 59 | the user's intent. 60 | 61 | There's a useful effect handler available for HTTP work: 62 |
4 |
5 | > All models are wrong, but some are useful
6 |
7 | The re-frame tutorials initially focus on the domino
8 | narrative. The goal is to efficiently explain the mechanics of re-frame,
9 | and to get you reading and writing code ASAP.
10 |
11 | But **there are other perspectives** on re-frame
12 | which will deepen your understanding.
13 |
14 | This section of the tutorial is a tour of these ideas.
15 |
16 | > If a factory is torn down but the rationality which produced it is
17 | left standing, then that rationality will simply produce another
18 | factory. If a revolution destroys a government, but the systematic
19 | patterns of thought that produced that government are left intact,
20 | then those patterns will repeat themselves. 
8 |
9 |
--------------------------------------------------------------------------------
/docs/cljdoc.edn:
--------------------------------------------------------------------------------
1 | {:cljdoc.doc/tree [["README" {:file "README.md"}]]
2 | :cljdoc.api/namespaces []}
3 |
--------------------------------------------------------------------------------
/docs/deps.edn:
--------------------------------------------------------------------------------
1 | {:paths ["src"]
2 |
3 | :deps {org.clojure/clojure {:mvn/version "1.10.1"}
4 | org.clojure/clojurescript {:mvn/version "1.10.773"}}}
5 |
--------------------------------------------------------------------------------
/docs/event-handling-infographic.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | 
4 |
5 |
6 | 
11 |
12 |
--------------------------------------------------------------------------------
/docs/images/404-img.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/404-img.png
--------------------------------------------------------------------------------
/docs/images/Alien3_0.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/Alien3_0.jpg
--------------------------------------------------------------------------------
/docs/images/Readme/6dominoes.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/Readme/6dominoes.png
--------------------------------------------------------------------------------
/docs/images/Readme/Dominoes-small.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/Readme/Dominoes-small.jpg
--------------------------------------------------------------------------------
/docs/images/Readme/Dominoes.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/Readme/Dominoes.jpg
--------------------------------------------------------------------------------
/docs/images/Readme/todolist.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/Readme/todolist.png
--------------------------------------------------------------------------------
/docs/images/delete.me.event-handlers.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/delete.me.event-handlers.png
--------------------------------------------------------------------------------
/docs/images/epoch.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/epoch.png
--------------------------------------------------------------------------------
/docs/images/event-dispatch.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/event-dispatch.png
--------------------------------------------------------------------------------
/docs/images/example_app.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/example_app.png
--------------------------------------------------------------------------------
/docs/images/favicon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/favicon.png
--------------------------------------------------------------------------------
/docs/images/handling-one-event.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/handling-one-event.png
--------------------------------------------------------------------------------
/docs/images/interceptors.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/interceptors.png
--------------------------------------------------------------------------------
/docs/images/logo/Genesis.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/Genesis.png
--------------------------------------------------------------------------------
/docs/images/logo/Guggenheim.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/Guggenheim.jpg
--------------------------------------------------------------------------------
/docs/images/logo/README.md:
--------------------------------------------------------------------------------
1 |
2 | 
3 |
4 | See the `ai` folder to illustrator files.
5 |
6 |
--------------------------------------------------------------------------------
/docs/images/logo/ai/Re-frame colour.ai:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/ai/Re-frame colour.ai
--------------------------------------------------------------------------------
/docs/images/logo/ai/Re-frame white.ai:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/ai/Re-frame white.ai
--------------------------------------------------------------------------------
/docs/images/logo/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/favicon.ico
--------------------------------------------------------------------------------
/docs/images/logo/old/f_303w.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/old/f_303w.png
--------------------------------------------------------------------------------
/docs/images/logo/old/frame_1024w.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/old/frame_1024w.png
--------------------------------------------------------------------------------
/docs/images/logo/old/re-frame-logo.sketch:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/old/re-frame-logo.sketch
--------------------------------------------------------------------------------
/docs/images/logo/old/re-frame_128w.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/old/re-frame_128w.png
--------------------------------------------------------------------------------
/docs/images/logo/old/re-frame_256w.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/old/re-frame_256w.png
--------------------------------------------------------------------------------
/docs/images/logo/old/re-frame_512w.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/old/re-frame_512w.png
--------------------------------------------------------------------------------
/docs/images/logo/re-frame-colour.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/re-frame-colour.png
--------------------------------------------------------------------------------
/docs/images/logo/re-frame-white.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/logo/re-frame-white.png
--------------------------------------------------------------------------------
/docs/images/mental-model-omnibus.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/mental-model-omnibus.jpg
--------------------------------------------------------------------------------
/docs/images/not-a-domino-lineup.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/not-a-domino-lineup.jpg
--------------------------------------------------------------------------------
/docs/images/not-a-domino.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/not-a-domino.jpg
--------------------------------------------------------------------------------
/docs/images/scale-changes-everything.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/scale-changes-everything.jpg
--------------------------------------------------------------------------------
/docs/images/subscriptions.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/subscriptions.png
--------------------------------------------------------------------------------
/docs/images/the-water-cycle.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/the-water-cycle.png
--------------------------------------------------------------------------------
/docs/images/yinyang.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/day8/re-frame/7b6fa64a6b3aecd2fcdbbfd80a89d59f92de57e1/docs/images/yinyang.png
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | template: overrides/home.html
3 | title: Derived data, flowing
4 | ---
5 |
--------------------------------------------------------------------------------
/docs/interconnections.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | Ask a Systems Theorist, and they'll tell you that a system has **parts** and **interconnections**.
4 |
5 | Human brains tend to focus first on the **parts**, and then, later, maybe on
6 | **interconnections**. But we know better, right? We
7 | know interconnections are often critical to a system.
8 | "Focus on the lines between the boxes" we lecture anyone kind enough to listen (in my case, glassy-eyed family members).
9 |
10 | In the case of re-frame, dominoes are the **parts**, so, tick, yes, we have
11 | looked at them first. Our brains are happy. But what about the **interconnections**?
12 |
13 | If the **parts** are functions, as is the case with re-frame,
14 | what does it even mean to talk about **interconnections between functions?**
15 | To answer that question, I'll rephrase it as:
16 | how are the domino functions **composed**?
17 |
18 | At the language level,
19 | Uncle Alonzo and Uncle John tell us how a function like `count` composes:
20 | ```clj
21 | (str (count (filter odd? [1 2 3 4 5])))
22 | ```
23 | We know when `count` is called, and with what
24 | argument, and how the value it computes becomes the arg for a further function.
25 | We know how data "flows" into and out of the functions.
26 |
27 | Sometimes, we'd rewrite this code as:
28 | ```clj
29 | (->> [1 2 3 4 5]
30 | (filter odd?)
31 | count
32 | str)
33 | ```
34 | With this arrangement, we talk of "threading" data
35 | through functions. **It seems to help our comprehension to conceive function
36 | composition in terms of data flow**.
37 |
38 | re-frame delivers architecture
39 | by supplying the interconnections - it threads the data - it composes the dominoes - it is the lines between the boxes.
40 |
41 | But it doesn't have a universal method for this "composition". The technique it uses varies from one domino
42 | neighbour-pair to the next. Initially, it uses a queue/router, then a pipeline of interceptors
43 | and, finally, a Signal Graph.
44 |
45 | Remember back in the Introduction? Our analogy for re-frame was the water cycle - water flowing around the loop,
46 | compelled by different kinds of forces at different times (gravity, convection, etc), going through phase changes.
47 |
48 | With this focus on interconnections, we have been looking on the "forces" part of the loop. The transport.
49 |
--------------------------------------------------------------------------------
/docs/re-frame.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | 
73 |
74 | **Scale changes everything.** Frameworks
75 | are just pesky overhead at small scale - measure them instead by how they help
76 | you tame the complexity of bigger apps, and in this regard re-frame has
77 | worked out well. Some have been effusive in their praise.
78 |
79 | And, yes, re-frame is fast, straight out of the box. And, yes, it has
80 | a good testing story (unit and behavioural). And, yes, it works with
81 | tools like figwheel or shadow-cljs to create
82 | a powerful hot-loading development story. And, yes, it has
83 | fun specialist tooling, and a community,
84 | and useful 3rd party libraries.
85 |
86 |
87 |
88 |
96 | #
97 |
--------------------------------------------------------------------------------
/docs/reagent.md:
--------------------------------------------------------------------------------
1 |
2 | Clojurescript is ergonomic, stable, functional language
3 |
4 | Look at the front page of https://www.learnreframe.com/
5 |
6 |
7 | 
8 | Someone is to blame for this.
11 |Rest assured we have started the necessary witch hunt.
12 |Build web apps, in ClojureScript, leveraging React.
28 |Has a data-oriented, functional design.
29 |Advanced enough to have outlasted three generations of Javascript technical churn.
30 |A focus on developer productivity. Fewer lines of code. Hot code reloading. A simple dynamic model. Managed effects, including state. Pure functions. Variously declarative.
31 |The more sophisticated your app, the better.
32 |
11 |
14 |