diff options
| -rw-r--r-- | book/index.tw | 63 | ||||
| -rw-r--r-- | book/intro.tw | 170 | ||||
| -rwxr-xr-x | book/src/main/resources/js/ui.js | 2 | ||||
| -rw-r--r-- | book/src/main/scala/book/Book.scala | 70 | ||||
| -rw-r--r-- | book/src/main/scala/book/Main.scala | 2 | ||||
| -rw-r--r-- | book/src/main/scala/book/Utils.scala | 41 | ||||
| -rw-r--r-- | intro.md | 32 |
7 files changed, 193 insertions, 187 deletions
diff --git a/book/index.tw b/book/index.tw index d5db4a7..db27d24 100644 --- a/book/index.tw +++ b/book/index.tw @@ -1,49 +1,22 @@ -@raw("<!doctype html>") -@html - @head - @meta(charset:="utf-8") - @meta(name:="viewport", content:="width=device-width, initial-scale=1.0") - @tags2.title("Hands-on Scala.js") - @Utils.includes - @script() - - @div(id:="layout") - @a(href:="#menu", id:="menuLink", cls:="menu-link") - @span - - @div(id:="menu") - @div(cls:="pure-menu pure-menu-open") - @a(cls:="pure-menu-heading", href:="#") - Contents - @ul(cls:="menu-item-list") - @Book.contentBar - - @div(id:="main") - @div(cls:="header") - @h1(id:=Utils.munge("Hands-on Scala.js")) - Hands-on Scala.js - @h2 - Writing client-side web applications in Scala - - @div(cls:="content") - @div(cls:="pure-g") - @div(cls:="pure-u-1 pure-u-md-13-24") - @hl.ref("examples/src/main/scala/Example.scala", "/*example*/", false) - - @div(cls:="pure-u-1 pure-u-md-11-24") - @canvas(id:="example-canvas", display:="block") - @script(src:="example-fastopt.js") - @script("Example().main('example-canvas')") - - @p - @a("Scala.js", href:="http://www.scala-js.org/") is a compiler that compiles Scala source code to equivalent Javascript code. That lets you write Scala code that you can run in a web browser, or other environments (Chrome plugins, Node.js, etc.) where Javascript is supported. - - @p - This book contains something for all levels of experience with Scala.js: beginners can get started with the Introduction and Hands-on tutorial, people who have used it before can skip ahead to the later parts of the tutorial, and even experienced users will find the In-depth Documention useful. - - @Book.intro - @Book.gettingStarted +@sect("Hands-on Scala.js") + @div(cls:="pure-g") + @div(cls:="pure-u-1 pure-u-md-13-24") + @hl.ref("examples/src/main/scala/Example.scala", "/*example*/", false) + + @div(cls:="pure-u-1 pure-u-md-11-24") + @canvas(id:="example-canvas", display:="block") + @script(src:="example-fastopt.js") + @script("Example().main('example-canvas')") + + @p + @a("Scala.js", href:="http://www.scala-js.org/") is a compiler that compiles Scala source code to equivalent Javascript code. That lets you write Scala code that you can run in a web browser, or other environments (Chrome plugins, Node.js, etc.) where Javascript is supported. + + @p + This book contains something for all levels of experience with Scala.js: beginners can get started with the Introduction and Hands-on tutorial, people who have used it before can skip ahead to the later parts of the tutorial, and even experienced users will find the In-depth Documention useful. + + @Book.intro + @Book.gettingStarted diff --git a/book/intro.tw b/book/intro.tw index 2f600d6..ac40291 100644 --- a/book/intro.tw +++ b/book/intro.tw @@ -1,114 +1,112 @@ -@sect{Intro to Scala.js} +@p + Traditionally, Scala has been a language which runs on the JVM. This eliminates it from consideration in many cases, e.g. when you need to build interactive web apps, you need to fall back to Javascript to run your client-side code, at a great loss in terms of toolability and maintainability. Scala.js lets you to develop web applications with the safety and toolability that comes with a statically typed language: + +@ul + @li + Typo-safety due to its compiler which catches many silly errors before the code is run + @li + In-editor support for autocomplete, error-highlighting, refactors, and intelligent navigation + @li + Very small compiled executables, in the 100-400kb range + @li + Source-maps for ease of debugging + +@p + The value proposition is that due to the superior language and tooling, writing a web application in Scala.js will result in a codebase that is more flexible and robust than an equivalent application written in Javascript. + +@sect{Who this book is for} + @p + This book is targeted at people who have some experience in both Scala and Javascript, as well as web development in general. You do not need to be an expert, but I will skim over basic concepts in to cut to the Scala.js specific points, though I will leave links whenever I introduce a new concept so you can read up if necssary. @p - Traditionally, Scala has been a language which runs on the JVM. This eliminates it from consideration in many cases, e.g. when you need to build interactive web apps, you need to fall back to Javascript to run your client-side code, at a great loss in terms of toolability and maintainability. Scala.js lets you to develop web applications with the safety and toolability that comes with a statically typed language: - - @ul - @li - Typo-safety due to its compiler which catches many silly errors before the code is run - @li - In-editor support for autocomplete, error-highlighting, refactors, and intelligent navigation - @li - Very small compiled executables, in the 100-400kb range - @li - Source-maps for ease of debugging + Furthermore, this book aims to only give an overview of the main steps you need to perform (and ideas you need to understand) to get started using Scala.js. It isn't a comprehensive guide, so if you want to know something this book doesn't cover, feel free to ask on the @a("mailing list", href:="https://groups.google.com/forum/#!forum/scala-js"). +@sect{Why Scala.js} @p - The value proposition is that due to the superior language and tooling, writing a web application in Scala.js will result in a codebase that is more flexible and robust than an equivalent application written in Javascript. + Javascript is the language supported by web browsers, and is the only language available if you wish to write interactive web applications. As more and more activity moves online, the importance of web apps will only increase over time. - @sect{Who this book is for} + @sect{Javascript-the-language} + @p + However, Javascript is not an easy language to work in. Apart from being untyped (which some people don't mind) Javascript is also extremely verbose, has a lot of surprising behavior, and has a culture that make even the simplest of patterns (e.g. instantiating an object) a debate between a dozen different and equally-bad options. @p - This book is targeted at people who have some experience in both Scala and Javascript, as well as web development in general. You do not need to be an expert, but I will skim over basic concepts in to cut to the Scala.js specific points, though I will leave links whenever I introduce a new concept so you can read up if necssary. + To work in Javascript, you need the discipline to limit yourself to the sane subset of the language, avoiding all the pitfalls along the way: + @img(src:="images/javascript-the-good-parts-the-definitive-guide.jpg") + + @sect{Javascript-the-platform} @p - Furthermore, this book aims to only give an overview of the main steps you need to perform (and ideas you need to understand) to get started using Scala.js. It isn't a comprehensive guide, so if you want to know something this book doesn't cover, feel free to ask on the @a("mailing list", href:="https://groups.google.com/forum/#!forum/scala-js"). + However, even as Javascript-the-language sucks, Javascript-the-platform has some very nice properties that make it a good target for application developers: + + @ul + @li + Zero-install distribution: just go to a URL and have the application downloaded and ready to use. + @li + Hyperlinks: being able to link to a particular page or item within a web app is a feature other platforms lack, and makes it much easier to cross-reference between different systems + @li + Sandboxed security: before the advent of mobile apps, web apps were the most secure runtime available, offering none of the risk or worry that comes with installing desktop software - @sect{Why Scala.js} @p - Javascript is the language supported by web browsers, and is the only language available if you wish to write interactive web applications. As more and more activity moves online, the importance of web apps will only increase over time. + These features are all very nice to have, and together have made the web platform the success it is today. - @sect{Javascript-the-language} - @p - However, Javascript is not an easy language to work in. Apart from being untyped (which some people don't mind) Javascript is also extremely verbose, has a lot of surprising behavior, and has a culture that make even the simplest of patterns (e.g. instantiating an object) a debate between a dozen different and equally-bad options. - @p - To work in Javascript, you need the discipline to limit yourself to the sane subset of the language, avoiding all the pitfalls along the way: + @hr - @img(src:="images/javascript-the-good-parts-the-definitive-guide.jpg") + @p + This is where Scala.js comes in. As developers we want Javascript-the-platform, with its ease-of-distribution, hyperlinks and security characteristics. We do not want Javascript-the-language, with its propensity for bugs, verbosity, and fragility. With Scala.js, you can cross compile your Scala code to a Javascript executable that can run on all major web browsers, thus saving you from the endless stream of gotcha's like the one below: - @sect{Javascript-the-platform} - @p - However, even as Javascript-the-language sucks, Javascript-the-platform has some very nice properties that make it a good target for application developers: + @hl.javascript + javascript> ["10", "10", "10", "10"].map(parseInt) + [10, NaN, 2, 3] // WTF - @ul - @li - Zero-install distribution: just go to a URL and have the application downloaded and ready to use. - @li - Hyperlinks: being able to link to a particular page or item within a web app is a feature other platforms lack, and makes it much easier to cross-reference between different systems - @li - Sandboxed security: before the advent of mobile apps, web apps were the most secure runtime available, offering none of the risk or worry that comes with installing desktop software + @hl.scala + scala> List("10", "10", "10", "10").map(parseInt) + List(10, 10, 10, 10) // Yay! - @p - These features are all very nice to have, and together have made the web platform the success it is today. + @p + Scala.js allows you to take advantage of the Javascript platform while still enjoying all the benefits of a concise, safe, modern language. The benefits of Scala are well documented, and I will not make a case here for Scala vs. some other language. Suffice to say, I believe it's a considerable improvement over programming in Javascript, and with Scala.js we can bring this improvement in development speed and happiness from the backend systems (where Scala has traditionally been used) to the front-end web application. - @hr +@sect{The Agenda} - @p - This is where Scala.js comes in. As developers we want Javascript-the-platform, with its ease-of-distribution, hyperlinks and security characteristics. We do not want Javascript-the-language, with its propensity for bugs, verbosity, and fragility. With Scala.js, you can cross compile your Scala code to a Javascript executable that can run on all major web browsers, thus saving you from the endless stream of gotcha's like the one below: + @p + This book will be roughly divided into three sections. These sections can be read in any order. Although the later chapters will make references to earlier chapters, there'll be hyperlinks so you can quickly go back and catch up on what you missed skipping over , - @hl.javascript - javascript> ["10", "10", "10", "10"].map(parseInt) - [10, NaN, 2, 3] // WTF + @sect{Hands On} + @p + A whirlwind tour of the various things that Scala.js can be used for. We will cover: + + @ul + @li + Your first Scala.js application: setting up your development environment, cloning the example repository, debugging and finally publishing your first toy application + @li + An interactive web app using Scala.js: how you interact with the HTML DOM, how you utilize Ajax calls and other browser APIs that are common in Javascript-heavy applications + @li + A Scala.js library: how to write a module that can be depended on by applications both your own and by others, and be used both with Scala.js and Scala-on-the-JVM + @li + Client-Server integration: We will build a simple web application with a Scala server and Scala.js client. In the process, we'll explore how to share code between client and server, how to get compiler-checked/boilerplate-free Ajax calls between client and server, and many other long-standing holy-grails of web development + + @p + After going through this chapter and following along with the exercises, you should have a good sense of how Scala.js works and how it feels building things in Scala.js. You would not be an expert, but you'll know where to get started if you decide to try out Scala.js for your next project. - @hl.scala - scala> List("10", "10", "10", "10").map(parseInt) - List(10, 10, 10, 10) // Yay! + @sect{Scala.js in Depth} + @p + This section of the book will cover lots of content that does not fit in the earlier Hands-On portion of the book. Things that aren't immediately necessary to get something up and running, things that only advanced users would care about, things that you probably don't need to know but you'd like to know out of intellectual curiosity. @p - Scala.js allows you to take advantage of the Javascript platform while still enjoying all the benefits of a concise, safe, modern language. The benefits of Scala are well documented, and I will not make a case here for Scala vs. some other language. Suffice to say, I believe it's a considerable improvement over programming in Javascript, and with Scala.js we can bring this improvement in development speed and happiness from the backend systems (where Scala has traditionally been used) to the front-end web application. + In general, this section of the book will go much deeper into Scala.js, much more than is necessary to get your first applications built. We will talk about the small number of semantic differences between Scala.js and Scala, details of the foreign-function-interface with Javascript, the various optimization levels and what they do. Nothing pressing or urgently needed, but all very interesting, and worth reading if you want to really understand Scala.js in depth. - @sect{The Agenda} + @sect{Why} + @p + Why should you care about Scala.js in the first place? Why not just write Javascript? As a new, barely-a-year-old project, what does it provide that other more mature compile-to-javascript langauges don't? @p - This book will be roughly divided into three sections. These sections can be read in any order. Although the later chapters will make references to earlier chapters, there'll be hyperlinks so you can quickly go back and catch up on what you missed skipping over , - - @sect{Hands On} - @p - A whirlwind tour of the various things that Scala.js can be used for. We will cover: - - @ul - @li - Your first Scala.js application: setting up your development environment, cloning the example repository, debugging and finally publishing your first toy application - @li - An interactive web app using Scala.js: how you interact with the HTML DOM, how you utilize Ajax calls and other browser APIs that are common in Javascript-heavy applications - @li - A Scala.js library: how to write a module that can be depended on by applications both your own and by others, and be used both with Scala.js and Scala-on-the-JVM - @li - Client-Server integration: We will build a simple web application with a Scala server and Scala.js client. In the process, we'll explore how to share code between client and server, how to get compiler-checked/boilerplate-free Ajax calls between client and server, and many other long-standing holy-grails of web development - - @p - After going through this chapter and following along with the exercises, you should have a good sense of how Scala.js works and how it feels building things in Scala.js. You would not be an expert, but you'll know where to get started if you decide to try out Scala.js for your next project. - - @sect{Scala.js in Depth} - @p - This section of the book will cover lots of content that does not fit in the earlier Hands-On portion of the book. Things that aren't immediately necessary to get something up and running, things that only advanced users would care about, things that you probably don't need to know but you'd like to know out of intellectual curiosity. - - @p - In general, this section of the book will go much deeper into Scala.js, much more than is necessary to get your first applications built. We will talk about the small number of semantic differences between Scala.js and Scala, details of the foreign-function-interface with Javascript, the various optimization levels and what they do. Nothing pressing or urgently needed, but all very interesting, and worth reading if you want to really understand Scala.js in depth. - - @sect{Why} - @p - Why should you care about Scala.js in the first place? Why not just write Javascript? As a new, barely-a-year-old project, what does it provide that other more mature compile-to-javascript langauges don't? - - @p - In this section of the book, we will examine the reasons which got me first interested in Scala.js. We'll talk at length about the deficiencies of Javascript, the ubiquity of the browser as an application platform, and the technical characteristics that make this the case. - - @p - Lastly, we will explore the solution space. Scala.js isn't the only game in town, and there are hundreds of over attempts at covering the same ground the Scala.js now attempts to cover. We'll compare and contrast the different approaches to see what Scala.js can bring to the table that other approaches cannot. - - @hr - + In this section of the book, we will examine the reasons which got me first interested in Scala.js. We'll talk at length about the deficiencies of Javascript, the ubiquity of the browser as an application platform, and the technical characteristics that make this the case. + @p - As mentioned earlier, these chapters can be read in any order. In keeping with the spirit of the book, we'll jump right into the Hands On to give you the experience, and save the talking and philosophizing for later. Let's go! + Lastly, we will explore the solution space. Scala.js isn't the only game in town, and there are hundreds of over attempts at covering the same ground the Scala.js now attempts to cover. We'll compare and contrast the different approaches to see what Scala.js can bring to the table that other approaches cannot. + + @hr + + @p + As mentioned earlier, these chapters can be read in any order. In keeping with the spirit of the book, we'll jump right into the Hands On to give you the experience, and save the talking and philosophizing for later. Let's go! diff --git a/book/src/main/resources/js/ui.js b/book/src/main/resources/js/ui.js index e98327a..5f144bb 100755 --- a/book/src/main/resources/js/ui.js +++ b/book/src/main/resources/js/ui.js @@ -76,7 +76,7 @@ document.addEventListener("DOMContentLoaded", function(){ // Get id of current scroll item for(var i = scrollItems.length - 1; i >= 0; i--){ - if (scrollHeaders[i].offsetTop < fromTop + 15 /*fudge factor*/){ + if (scrollHeaders[i].offsetTop < fromTop + 100 /*fudge factor*/){ if (lastId != i) { if (lastId != -1) { scrollItems[lastId].parentElement.className = scrollItems[lastId].parentElement.className.replace( diff --git a/book/src/main/scala/book/Book.scala b/book/src/main/scala/book/Book.scala index 6e4122f..4e2d015 100644 --- a/book/src/main/scala/book/Book.scala +++ b/book/src/main/scala/book/Book.scala @@ -12,27 +12,56 @@ import scalatags.Text.all._ object Book { import Utils.sect - val intro = twf("book/intro.tw") - val gettingStarted = twf("book/getting-started.tw") + lazy val intro = sect("Intro to Scala.js")(twf("book/intro.tw")) + lazy val gettingStarted = sect("Getting Started")(twf("book/getting-started.tw")) + val txt = twf("book/index.tw") val contentBar = { - def rec(current: Node, depth: Int): Seq[Frag] = Seq( - li( - a( - current.name, - href:="#"+Utils.munge(current.name), - paddingLeft := s"${depth * 10 + 10}px", - cls := "menu-item" + (if (depth == 1) " menu-item-divided " else "") + def rec(current: Node, depth: Int): Seq[Frag] = { + println("\t"*depth + current.name) + Seq( + li( + a( + current.name, + href:="#"+Utils.munge(current.name), + paddingLeft := s"${depth * 10 + 10}px", + cls := "menu-item" + (if (depth == 1) " menu-item-divided " else "") + ) ) - ) - ) ++ current.children.flatMap(rec(_, depth + 1)) + ) ++ current.children.flatMap(rec(_, depth + 1)) + } - // @li(cls:="menu-item-divided pure-menu-selected") + println("TABLE OF CONTENTS") rec(Utils.structure, 0) } - - - val txt = twf("book/index.tw").render - + val site = Seq( + raw("<!doctype html>"), + html( + head( + meta(charset:="utf-8"), + meta(name:="viewport", content:="width=device-width, initial-scale=1.0"), + tags2.title("Hands-on Scala.js"), + Utils.includes + ), + + div(id:="layout")( + a(href:="#menu", id:="menuLink", cls:="menu-link")( + span + ), + + div(id:="menu")( + div(cls:="pure-menu pure-menu-open")( + a(cls:="pure-menu-heading", href:="#")( + "Contents" + ), + ul(cls:="menu-item-list")( + contentBar + ) + ) + ) + ), + div(id:="main", txt) + ) + ).render object hli{ def javascript(code: String*) = hl.highlight(code, "javascript", inline=true) def scala(code: String*) = hl.highlight(code, "scala", inline=true) @@ -47,8 +76,6 @@ object Book { if (inline){ code(cls:=lang + " highlight-me", lines(0), padding:=0, display:="inline") }else{ - println("LINES " + lines.toList) - println(snippet) val minIndent = lines.map(_.takeWhile(_ == ' ').length) .filter(_ > 0) .min @@ -114,15 +141,11 @@ object Book { firstCharIndex == -1 || firstCharIndex >= whitespace + (if (indented) 1 else 0) } - things.foreach(println) val stuff = if (!indented) { - println("NOT INDENTED " + things) things - } - else { + } else { val last = lines(firstLine + things.length + 1) -// println("LAST: " + last) if (last.trim.toSet subsetOf "}])".toSet) { lines(firstLine) +: things :+ last } else { @@ -131,7 +154,6 @@ object Book { } stuff.map(_.drop(whitespace)).mkString("\n") } - println(blob) pre(code(cls:=lang + " highlight-me", blob)) } diff --git a/book/src/main/scala/book/Main.scala b/book/src/main/scala/book/Main.scala index 89fb5e1..19b256a 100644 --- a/book/src/main/scala/book/Main.scala +++ b/book/src/main/scala/book/Main.scala @@ -32,7 +32,7 @@ object Main { // .call() - write(Book.txt, "output/index.html") + write(Book.site, "output/index.html") for(res <- Utils.autoResources ++ Utils.manualResources) { copy(getClass.getResourceAsStream("/" + res), "output/" + res) diff --git a/book/src/main/scala/book/Utils.scala b/book/src/main/scala/book/Utils.scala index df56c84..fbef8e8 100644 --- a/book/src/main/scala/book/Utils.scala +++ b/book/src/main/scala/book/Utils.scala @@ -38,27 +38,46 @@ object Utils{ raw("") } println(includes) - var indent = 1 - val headers = Seq(h1, h1, h2, h3, h4, h5, h6) - val structure = Node("Hands-on Scala.js", mutable.Buffer.empty) - var current = structure + var indent = 0 + + + val headers = Seq[(String => scalatags.Text.Tag, Option[Frag => Frag])]( + (h => div(cls:="header")( + h1(h), + h2("Writing client-side web applications in Scala") + ), Some(f => div(cls:="content", f))), + (h => div(cls:="header")( + h1(id:=Utils.munge(h), h), + br + ), None), + (h1(_), None), + (h2(_), None), + (h3(_), None), + (h4(_), None), + (h5(_), None), + (h6(_), None) + ) + + var structure: Node = null case class sect(name: String){ indent += 1 val newNode = Node(name, mutable.Buffer.empty) - current.children.append(newNode) - val prev = current - current = newNode + val (headerWrap, contentWrap) = headers(indent-1) + if (structure!= null) structure.children.append(newNode) + val prev = structure + structure = newNode def apply(args: Frag*) = { - val res = Seq( - headers(indent-1)(cls:="content-subhead", id:=munge(name), name) +: args:_* + val wrappedContents = contentWrap.getOrElse((x: Frag) => x)(args) + val res = Seq[Frag]( + headerWrap(name)(cls:="content-subhead", id:=munge(name)), + wrappedContents ) indent -= 1 - current = prev + if (prev != null) structure = prev res } } def munge(name: String) = { name.replace(" ", "") } - }
\ No newline at end of file @@ -8,8 +8,15 @@ Hands-On Scala.js Why Where - Tutorial - A HTML5 Canvas Application + Hands On + Getting Started + Opening the Project + The Application Code + The Project Code + Publishing + + Making an HTML5 Canvas Game + Accessing DOM APIs Using js.Dynamic Using scala-js-dom for type-safety @@ -18,7 +25,7 @@ Hands-On Scala.js Publishing Looking through the generated code - Interactive Web Pages + Interactive Web Apps Managing HTML using the DOM Managing HTML using Scalatags Wiring up DOM events and interactions @@ -45,6 +52,8 @@ Hands-On Scala.js Deployment Reference + The Scala.js File Encoding + Javascript Interop Calling Javascript from Scala.js Writing your own FFI facades @@ -55,22 +64,7 @@ Hands-On Scala.js Differences from Scala/JVM - Compilation Pipeline + Internals Optimization Phases - -Intro to Intro to Scala.js - - Scala.js is a compiler that compiles Scala source code to equivalent Javascript code. That lets you write Scala code that you can run in a web browser, or other environments (Chrome plugins, Node.js, etc.) where Javascript is supported. - - This book is targeted at people who have some experience in both Scala and Javascript. You do not need to be an expert in both, but I will skim over basic concepts in both languages to cut to the Scala.js specific points. - - Scala.js on its own allows you to develop web applications with the safety and toolability that comes with a statically typed language. - - - Typo-safety due to its compiler which catches many silly errors before the code is run - - In-editor support for autocomplete, error-highlighting, refactors, and intelligent navigation - - Very small compiled executables, in the 170-400kb range - - Source-maps for ease of debugging - - In general, the development experience is on
\ No newline at end of file |