New interface for external events (#41)

* Simplify example folders; add extra example; add clarification to documentation

* Custom events instead of signals

* Finish draft and fix tests

* Updated examples

* Split window and document events so names dont clash

* add window focus

* More window events

* First half of documentation

* Finish documentation

* Add examples

* Finish example

* Rebased

Author: easafe

README.md

@@ -26,16 +26,16 @@ module Counter.Main where
 import Prelude
 
 import Effect (Effect)
-import Flame (Html, QuerySelector(..))
--- Update strategy for side effects free functions; see docs for other strategies
+import Flame (Html, QuerySelector(..), Subscription)
+-- Side effects free updating; see docs for other examples
 import Flame.Application.NoEffects as FAN
 import Flame.Html.Element as HE
 import Flame.Html.Attribute as HA
 
 -- | The model represents the state of the app
 type Model = Int
 
--- | This datatype is used to signal events to `update`
+-- | Data type used to represent events
 data Message = Increment | Decrement
 
 -- | Initial state of the app
@@ -56,12 +56,17 @@ view model = HE.main "main" [
       HE.button [HA.onClick Increment] "+"
 ]
 
+-- | Events that come from outside the `view`
+subscribe :: Array (Subscription Message)
+subscribe = []
+
 -- | Mount the application on the given selector
 main :: Effect Unit
 main = FAN.mount_ (QuerySelector "body") {
       init,
+      view,
       update,
-      view
+      subscribe
 }
 ```
 

bower.json

@@ -16,7 +16,6 @@
     "purescript-web-html": "^2.0.0",
     "purescript-nullable": "^4.1.1",
     "purescript-aff": "^5.1.0",
-    "purescript-signal": "^10.1.0",
     "purescript-foreign-object": "^2.0.1",
     "purescript-argonaut-generic": "^6.0.0",
     "purescript-argonaut-codecs": "^7.0.0"

docs/_config.yml

@@ -17,8 +17,6 @@
 # Build settings
 markdown: kramdown
 highlighter: rouge
-plugins:
-  - jekyll-feed
 
 # Exclude from processing.
 # The following items will not be processed, by default. Create a custom list

docs/concepts.md

@@ -7,35 +7,42 @@ permalink: /concepts
 ## Main concepts
 
 A Flame application consists of the following record
+
 ```haskell
 type Application model message = {
       init :: model,
       view :: model -> Html message,
-      update :: model -> message -> model
+      update :: model -> message -> model,
+      subscribe :: Array (Subscription message)
 }
 ```
 The type variable `model` refers to the state of the application. `message`, on the other hand, describes the kinds of events the application can handle.
 
 ### Application state
 
 In the counter example we set our model as a simple type alias
+
 ```haskell
 type Model = Int
 ```
+
 that is, the state of our application is a single integer. In a real world application, the model will probably be something more interesting -- Flame makes no assumption about how it is structured.
 
 With our model type declared, we can define the initial state of the application
+
 ```haskell
 init :: Model
 init = 0
 ```
+
 The first time the application is rendered, Flame calls the view function with `init`.
 
 ### Application markup
 
-The `view` function maps the current state to markup. Whenever the model is updated, flame patches the DOM by calling `view` with the new state.
+The `view` function maps the current state to markup. Whenever the model is updated, Flame patches the DOM by calling `view` with the new state.
 
 In the counter example, the view is defined as
+
 ```haskell
 view :: Model -> Html Message
 view model = HE.main "main" [
@@ -44,17 +51,21 @@ view model = HE.main "main" [
       HE.button [HA.onClick Increment] "+"
 ]
 ```
+
 The `message`s raised on events are used to signal how the application state should be updated.
 
 See [Defining views](views) for an in depth look at views.
 
 ### State updating
 
 The `update` function handles events, returning an updated model. In a Flame application, we reify native events as a custom data type. In the counter example, we are interested in the following events:
+
 ```haskell
 data Message = Increment | Decrement
 ```
+
 and thus our update function looks like
+
 ```haskell
 update :: Model -> Message -> Model
 update model = case _ of
@@ -64,31 +75,34 @@ update model = case _ of
 
 See [Handling events](events) for an in depth look at update strategies.
 
-### External event handling
+### Subscriptions
+
+Finally, we can specify events that come from outside of the `view` as an array to `subscribe`. Such events include `window`, `document` -- and even messages arbitrarily raised by user code. These messages will then be handled in the usual way by the `update` function.
 
-Finally, mounting a Flame application record yields a [`Channel`](https://pursuit.purescript.org/packages/purescript-signal/10.1.0/docs/Signal.Channel), which can be fed messages from events outside of our view. This includes `window` or `document` events, such as resize or load, and custom events, all of which are then handled as usual by the application `update` function.
+In the counter example no external events are handled, so the subscription list is empty
 
-In the counter example, no external events are handled, so we use the version of `mount` that discards the channel
 ```haskell
-main :: Effect Unit
-main = FAN.mount_ "main" {
-      ...
+subscribe :: Array (Subscription Message)
+subscribe = []
 }
 ```
 
-See [Handling external events](events#handling-external-events) for an in depth look at external events.
+See [Handling external events](events#handling-external-events) for an in depth look at subscriptions.
 
 ### Rendering
 
 Having all pieces put together, we can either render the application to the DOM, as in the case of the counter example
+
 ```haskell
 main :: Effect Unit
 main = FAN.mount_ (QuerySelector "body") {
       init,
+      view,
       update,
-      view
+      subscribe
 }
 ```
+
 or as a `String` with `Flame.Renderer.String.render`, which can be used server-side.
 
 See [Rendering the app](rendering) for an in depth look at rendering.