JarCasting
scalajs-hyperapp
A Scala.js facade for Hyperapp, a JavaScript micro-framework for building web applications.
Getting Started
First, enable the scalajs-bundler plugin by following these instructions. Then, add the following dependency to your build.sbt:
libraryDependencies += "cf.srxl" %%% "scalajs-hyperapp" % "1.0.0"
Basic App
Below is the same counter application found in the Hyperapp readme, written with Scala.js.
import org.scalajs.dom.document
import cf.srxl.hyperapp.Actions
import cf.srxl.hyperapp.DSL._
object CounterApp {
def main(args: Array[String]): Unit = {
val state: State = Map(
"count" -> 0
)
val actions = Actions(
"down" ==> ((value: Int) => state => state.int("count").map(c => Map("count" -> (c - value)))),
"up" ==> ((value: Int) => state => state.int("count").map(c => Map("count" -> (c + value))))
)
val view: View = (state, actions) =>
<("div", ^(),
<("h1", ^(), state.int("count").get),
<("button", ^("onclick" -> (() => actions.action("down").get(1))), "-"),
<("button", ^("onclick" -> (() => actions.action("up").get(1))), "+")
)
app(state, actions, view, document.body)
}
}
Reference
Imports
cf.srxl.hyperapp.DSL._ contains many useful functions and implicits to help build Hyperapp apps. You'll almost certainly want to import this. Everything else can be imported as necessary.
State
A state object is a simple Map[String, js.Any] (or the State type alias from the hyperapp package object).
val state: State = Map(
"key" -> "value"
)
To access values from a state object, you can use the methods defined in DSL.StateOps to easily get the types you want.
Nested State
When using nested state, make sure to import scala.scalajs.js.JSConverters._ and call toJSDictionary on any Maps in the state. Alternatively, you can use the ::> operator from DSL to have the conversion done for you.
val state: State = Map(
"nested" ::> (
"key" -> "value"
)
)
Actions
Action objects are created with the Actions class. There are 4 different entry types you can have in a state object:
- Simple actions (
-->) - Stateful actions (
==>) - Asynchronous actions (
=/>) - Action scopes (
:>)
As an example, this object in JavaScript:
const actions = {
scope: {
action1: value => ({ value1: value })
},
action2: value => state => ({ value2: state.value2 + value }),
action3: value => (state, actions) => { doSomething(); actions.action2(value) }
}
would look like this in Scala (the Int types on the functions are as an example):
val actions = Actions(
"scope" :> (
"action1" --> ((value: Int) => Map("value1" -> value))
),
"action2" ==> ((value: Int) => state => state.int("value2").map(v => Map("value2" -> (v + value)))),
"action3" =/> ((value: Int) => (state, actions) => { doSomething(); actions.action("action2").get(value) })
)
Received Actions
Actions received from functions such as the view function or an async action are not Actions, rather they are WiredActions. You can access actions from a WiredAction using actions, and scopes with scope. Both methods return Options, so you can use them in for-comprehensions like so:
for {
level1 <- actions.scope("level1")
level2 <- level1.scope("level2")
action <- level2.action("action")
} yield action("value")
Just like in regular Hyperapp, the app method returns the WiredActions, so you can use it to call actions from wherever you want.
View
A view function takes a State and an Actions, and returns a ViewNode. The View type alias describes this function. Instead of manually creating ViewNodes, you can use the < and ^ functions from DSL to easily create nodes.
<("tagName", ^("attribute" -> "value"), "children")
An example of a view function:
val view: View = (state, actions) =>
<("div", ^(),
<("h1", ^(), "Hello, World!"),
<("button", ^("onclick" -> (() => doSomething())), "Click Me!")
)
Components
The < function can also accept a component as it's first parameter. There are 4 different types of components:
Component(props => ViewNode)ComponentWithChildren((props, children) => ViewNode)LazyComponent(props => (state, actions) => ViewNode)LazyComponentWithChildren((props, children) => (state, actions) => ViewNode)
The shape of the props object is the same as a state object, so you can use all the methods in DSL.StateOps on a props object in the same way you would on a state object.
Contributing
If you have a feature you want added, feel free to open an issue, or a PR if you're feeling kind enough! Make sure that both the unit tests in /src/test/scala and the integration tests in /integration-tests are passing before you open a PR. Feel free to add more tests if you feel they're necessary, too.
Credits
- Jorge Bucaran (jorgebucaran) for creating Hyperapp
- The gwen-interpreter team for creating Gwen and the Gwen-Web engine used in integration testing
- The Scala.js gitter and Hyperapp Slack for helping me out with some issues (feel free to pop by and say hi! :))
License
scalajs-hyperapp is licensed under the BSD 3-Clause License. Hyperapp is licensed under the MIT License.