Skip to content

Improvements to the tutorial. Thanks @akauppi for the feedback. #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 21, 2014
Merged

Improvements to the tutorial. Thanks @akauppi for the feedback. #49

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions doc/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ To setup Scala.js in a new sbt project, we need to do two things:
1. Add the Scala.js sbt plugin
2. Apply the Scala.js specific settings to the project

Adding the Scala.js sbt plugin is a one-liner in `project/build.sbt`:
Adding the Scala.js sbt plugin is a one-liner in `project/plugins.sbt` (all file names we write in this tutorial are relative to the project root):

addSbtPlugin("org.scala-lang.modules.scalajs" % "scalajs-sbt-plugin" % "0.5.0")

We also setup basic project settings and Scala.js settings in the sbt build file (`build.sbt`):
We also setup basic project settings and Scala.js settings in the sbt build file (`build.sbt`, in the project root directory):

scalaJSSettings

Expand All @@ -41,6 +41,10 @@ That is all we need to configure the build.

If at this point you prefer to use Eclipse or IDEA as your IDE, you may use [sbteclipse](https://github.com/typesafehub/sbteclipse/wiki/Using-sbteclipse) or [idea-eclipse](https://github.com/mpeltonen/sbt-idea) project files for the IDE. Note that for compiling and running your application, you will still need to use sbt from the command line.

#### Alternative versions

You may instead use 2.10.2, 2.10.3, 2.10.4 or 2.11.0 for `scalaVersion` if you so wish. Similarly, any 0.13.x version of sbt should work without itch, for example 0.13.5.

### HelloWorld application

For starters, we add a very simple `TutorialApp` in the `tutorial.webapp` package. Create the file `src/main/scala/tutorial/webapp/TutorialApp.scala`:
Expand All @@ -66,6 +70,8 @@ As you expect, this will simply print "HelloWorld" when run. To run this, simply
Hello world!
[success] (...)

**Troubleshooting**: Should you experience errors with the `PermGen` size of the JVM at this point, you can increase it. Refer, for example, to [this StackOverflow question](http://stackoverflow.com/questions/8331135/transient-outofmemoryerror-when-compiling-scala-classes).

Congratulations! You have successfully compiled and run your first Scala.js application. The code is actually run by a JavaScript interpreter. If you do not believe this (it happens to us occasionally), you can use sbt's `last`:

> last
Expand All @@ -92,11 +98,11 @@ To generate a single JavaScript file using sbt, just use the `fastOptJS` task:
[info] Fast optimizing (...)/scala-js-tutorial/target/scala-2.11/scala-js-tutorial-fastopt.js
[success] (...)

This will perform some dead-code elimination and generate the `scala-js-tutorial-fastopt.js` file containing reachable JavaScript code.
This will perform some fast optimizations and generate the `target/scala-2.11/scala-js-tutorial-fastopt.js` file containing the JavaScript code.

### Create the HTML Page

The only thing which is specific to Scala.js, is how we can call the Scala code from JavaScript. First have a look at our HTML page (`scalajs-tutorial-fastopt.html` in the project root), we will go in the details right after.
To load and launch the created JavaScript, you will need an HTML file. Create the file `scalajs-tutorial-fastopt.html` (or whatever name you prefer, for example `index-fastopt.html`) in the project root with the following content. We will go in the details right after.

{% highlight html %}
<!DOCTYPE html>
Expand Down Expand Up @@ -130,7 +136,7 @@ As the last step has shown, running JavaScript inside a HTML page is not particu

### Adding the DOM Library

To use the JavaScript DOM library in Scala.js, it is best to use the Scala.js DOM library which provides types for the DOM. To add it to your sbt project, add the following line to your `build.sbt`:
To use the DOM, it is best to use the statically typed Scala.js DOM library. To add it to your sbt project, add the following line to your `build.sbt`:

libraryDependencies += "org.scala-lang.modules.scalajs" %%% "scalajs-dom" % "0.6"

Expand Down Expand Up @@ -263,11 +269,11 @@ jQuery("body").append("<p>[message]</p>")

Where `[message]` is the string originally passed to `appendPar`.

### Adding JavaScript libraries
If you try to reload your webpage now, it will not work (typically a `TypeError` would be reported in the console). The problem is that we haven't included the jQuery library itself, which is a plain JavaScript library.

You can now try and reload your webpage. You will observe that - although it seems we have done everything right - you don't see a "Hello World" message. Some browsers might give you a `TypeError`. The problem is that we haven't included the jQuery library itself, which is a plain JavaScript library.
### Adding JavaScript libraries

An option is to include `jquery.js` from an external source, such as [jsDelivr](http://www.jsdelivr.com/)
An option is to include `jquery.js` from an external source, such as [jsDelivr](http://www.jsdelivr.com/).

{% highlight html %}
<script type="text/javascript" src="http://cdn.jsdelivr.net/jquery/2.1.1/jquery.js"></script>
Expand Down Expand Up @@ -375,7 +381,7 @@ According to the [explanation in uTest's readme](http://github.com/lihaoyi/utest

testLoader := scala.scalajs.sbtplugin.testing.JSClasspathLoader((ScalaJSKeys.execClasspath in Compile).value)

And the following to our `project/build.sbt`:
And the following to our `project/plugins.sbt`:

addSbtPlugin("com.lihaoyi" % "utest-js-plugin" % "0.1.6")

Expand Down