ovto 0.2.0

data/book/api/state.md

@@ -0,0 +1,97 @@
+# Ovto::State
+
+`Ovto::State` is like a hash, but members are accessible with name rather than `[]`.
+
+## Example
+
+```rb
+class State < Ovto::State
+  item :foo
+  item :bar
+end
+
+state = State.new(foo: 1, bar: 2)
+state.foo  #=> 1
+state.bar  #=> 2
+```
+
+## Default value
+
+
+```rb
+class State < Ovto::State
+  item :foo, default: 1
+  item :bar, default: 2
+end
+
+state = State.new
+state.foo  #=> 1
+state.bar  #=> 2
+```
+
+## Immutable
+
+State objects are immutable. i.e. you cannot update value of a key. Instead, use `State#merge`.
+
+```rb
+state = State.new(foo: 1, bar: 2)
+new_state = state.merge(bar: 3)
+new_state.foo  #=> 1
+new_state.bar  #=> 3
+```
+
+## Nesting state
+
+For practical apps, you can nest State like this.
+
+```rb
+class Book < Ovto::State
+  item :title
+  item :author
+end
+
+class State < Ovto::State
+  item :books, []
+end
+
+book = Book.new('Hello world', 'taro')
+state = State.new(books: [book])
+```
+
+## Defining instance methods of state
+
+You can define instance methods of state.
+
+```rb
+class Book < Ovto::State
+  item :title
+  item :author
+
+  def to_text
+    "#{self.title} (#{self.author})"
+  end
+end
+
+book = Book.new('Hello world', 'taro')
+book.to_text  #=> "Hello world (taro)"
+```
+
+## Defining class methods of state
+
+Ovto does not have a class like `StateList`. Just use Array to represent a list of state.
+
+You can define class methods to manipulate a list of state.
+
+```rb
+class Book < Ovto::State
+  item :title
+  item :author
+
+  def self.of_author(books, author)
+    books.select{|x| x.author == author}
+  end
+end
+
+# Example
+taro_books = Book.of_author(books, "taro")
+```

data/book/guides/debugging.md

@@ -0,0 +1,23 @@
+# Debugging Ovto app
+
+## console.log
+
+In an Ovto app, you can print any object to developer console by `console.log`
+like in JavaScript. 
+
+```rb
+console.log(state: State.new)
+```
+
+This is mostly equal to `p state: State.new` but `console.log` supports
+JavaScript objects too.
+
+(Note: this is not an official feature of Opal. You can do this setup by this:)
+
+```rb
+  require 'console'; def console; $console; end
+```
+
+## ovto-debug
+
+If the page has a tag with `id='ovto-debug'`, exception is shown in the tag.

data/book/guides/development.md

@@ -0,0 +1,11 @@
+# Development notes
+
+## How to run unit test
+
+1. git clone
+2. bundle install
+3. bundle exec rake
+
+## How to rebuild docs
+
+`bundle exec doc:build`

data/book/guides/tutorial.md

@@ -0,0 +1,288 @@
+# Getting Started
+
+This is a tutorial of making an Ovto app. We create a static app (.html + .js) here,
+but you can embed Ovto apps into a Rails or Sinatra app (See `./example/*`).
+
+This is the final Ruby code.
+
+```
+require 'ovto'
+
+class MyApp < Ovto::App
+  class State < Ovto::State
+    item :celsius, default: 0
+
+    def fahrenheit
+      (celsius * 9 / 5.0) + 32
+    end
+  end
+
+  class Actions < Ovto::Actions
+    def set_celsius(state:, value:)
+      return {celsius: value}
+    end
+
+    def set_fahrenheit(state:, value:)
+      new_celsius = (value - 32) * 5 / 9.0
+      return {celsius: new_celsius}
+    end
+  end
+
+  class View < Ovto::Component
+    def render(state:)
+      o 'div' do
+        o 'span', 'Celcius:'
+        o 'input', {
+          type: 'text',
+          onchange: ->(e){ actions.set_celsius(value: e.target.value.to_i) },
+          value: state.celsius
+        }
+        o 'span', 'Fahrenheit:'
+        o 'input', {
+          type: 'text',
+          onchange: ->(e){ actions.set_fahrenheit(value: e.target.value.to_i) },
+          value: state.fahrenheit
+        }
+      end
+    end
+  end
+end
+
+MyApp.run(id: 'ovto-view')
+```
+
+Let's take a look step-by-step.
+
+## Prerequisites
+
+- Ruby
+- Bundler (`gem install bundler`)
+
+## Setup
+
+Make a Gemfile:
+
+```
+source "https://rubygems.org"
+gem "ovto", github: 'yhara/ovto'  # Use git master because ovto gem is not released yet
+gem 'rake'
+```
+
+Run `bundle install`.
+
+## HTML
+
+Make an index.html:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script type='text/javascript' src='app.js'></script>
+  </head>
+  <body>
+    <div id='ovto-view'></div>
+    <div id='ovto-debug'></div>
+  </body>
+</html>
+```
+
+## Write code
+
+app.rb:
+
+```rb
+require 'ovto'
+
+class MyApp < Ovto::App
+  class State < Ovto::State
+  end
+
+  class Actions < Ovto::Actions
+  end
+
+  class View < Ovto::Component
+    def render(state:)   # Don't miss the `:`. This is not a typo but
+      o 'div' do         # a "mandatory keyword argument".
+        o 'h1', "HELLO"  # All of the Ovto methods take keyword arguments.
+      end
+    end
+  end
+end
+
+MyApp.run(id: 'ovto-view')
+```
+
+- The name `MyApp` is arbitrary.
+- The id `ovto-view` corresponds to the `div` tag in `index.html`.
+
+## Compile
+
+Generate app.js from app.rb.
+
+```
+$ bundle exec opal -c -g ovto app.rb > app.js
+```
+
+(Compile will fail if there is a syntax error in your `app.rb`.)
+
+Now you can run your app by opening `index.html` in your browser.
+
+## Trouble shooting
+
+If you see HELLO, the setup is done. Otherwise, check the developer console
+and you should see some error messages there.
+
+For example if you misspelled `class State` to `class Stat`, you will see:
+
+```
+app.js:5022 Uncaught $NameError {name: "State", message: "uninitialized constant MyApp::State", stack: "State: uninitialized constant MyApp::State"}
+```
+
+because an Ovto app must have a `State` class in its namespace.
+
+## (Tips: auto-compile)
+
+If you get tired to run `bundle exec opal` manually, try `ifchanged` gem:
+
+1. Add `gem "ifchanged"` to Gemfile
+1. `bundle install`
+1. `bundle exec ifchanged ./app.rb --do 'bundle exec opal -c -g ovto app.rb > app.js'`
+
+Now you just edit and save `app.rb` and it runs `opal -c` for you.
+
+## Add some state
+
+In this tutorial, we make an app that convers Celsius and Fahrenheit degrees to
+each other. First, add an item to `MyApp::State`.
+
+```rb
+  class State < Ovto::State
+    item :celsius, default: 0
+  end
+```
+
+Now an item `celsius` is added to the global app state. Its value is `0` when
+the app starts. You can read this value by `state.celsius`. Let's display the
+value with `MyApp::View`.
+
+```rb
+  class View < Ovto::Component
+    def render(state:)
+      o 'div' do
+        o 'span', 'Celcius:'
+        o 'input', type: 'text', value: state.celsius
+      end
+    end
+  end
+```
+
+Now you should see `Celsius: [0      ]` in the browser.
+
+## Add a method to State
+
+Next, we want to know what degree is it in Fahrenheit. Let's add a method to
+convert.
+
+```rb
+  class State < Ovto::State
+    item :celsius, default: 0
+
+    def fahrenheit
+      (celsius * 9 / 5.0) + 32
+    end
+  end
+```
+
+Now you can know the value by `state.fahrenheit`. Update the `View` to show the value too.
+
+```
+  class View < Ovto::Component
+    def render(state:)
+      o 'div' do
+        o 'span', 'Celcius:'
+        o 'input', type: 'text', value: state.celsius
+        o 'span', 'Fahrenheit:'
+        o 'input', type: 'text', value: state.fahrenheit
+      end
+    end
+  end
+```
+
+## Add an action
+
+Now we know 0 degrees Celsius is 32 degrees Fahrenheit. But how about 10 degrees or
+100 degrees Celsius? Let's update the app to we can specify a Celsius value.
+
+You may think that you can change the value with `state.celsius = 100`, but this is
+prohibited. In Ovto, you can only modify app state with Actions.
+
+Our first action looks like this. An action is a method defined in `MyApp::Actions`.
+It takes an old state (and its own parameters) and returns a Hash that describes
+the updates to the state. This return value is `merge`d into the global app state.
+
+```rb
+  class Actions < Ovto::Actions
+    def set_celsius(state:, value:)
+      return {celsius: value}
+    end
+  end
+```
+
+This action can be called by `actions.set_celsius` from the View. Replace the
+first input tag with this:
+
+```rb
+        o 'input', {
+          type: 'text',
+          onchange: ->(e){ actions.set_celsius(value: e.target.value.to_i) },
+          value: state.celsius
+        }
+```
+
+`onchange:` is a special attribute that takes an event handler as its value.
+The argument `e` is an instance of `Opal::Native` and wraps the event object of
+JavaScript. In this case you can get the input string by `e.target.value`.
+
+Now reload your browser and input `100` to the left input box. Next, press Tab key
+(or click somewhere in the page) to commit the value. Then you should see `212`
+in the right input box. 100 degrees Celsius is 212 degrees Fahrenheit!
+
+## What has happend
+
+In case you are curious, here is what happens when you give 100 to the input box.
+
+1. JavaScript's `onchange` event is executed.
+1. Ovto calls the event handler.
+1. It calls `actions.set_celsius`. `actions` is an instance of `Ovto::WiredActions`.
+  It is a proxy to the `MyApp::Actions`. It has the same methods as those in
+  `MyApp::Actions` but does some more:
+  - It passes `state` to the user-defined action.
+  - It merges the result to the global app state.
+  - It schedules re-rendering the view to represent the new state.
+
+## Reverse conversion
+
+It is easy to update the app to support Fahrenheit-to-Celsius conversion.
+The second input should be updated to:
+
+```rb
+        o 'input', {
+          type: 'text',
+          onchange: ->(e){ actions.set_fahrenheit(value: e.target.value.to_i) },
+          value: state.fahrenheit
+        }
+```
+
+Then add an action `set_fahrenheit` to `MyApp::Actions`. This action convers the
+Fahrenheit degree into Celsius and set it to the global state.
+
+```rb
+    def set_fahrenheit(state:, value:)
+      new_celsius = (value - 32) * 5 / 9.0
+      return {celsius: new_celsius}
+    end
+```
+
+Now your app should react to the change of the Fahrenheit value too. 

data/docs/api/Ovto/Actions.html

@@ -0,0 +1,135 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Class: Ovto::Actions
+  
+    &mdash; Documentation by YARD 0.9.12
+  
+</title>
+
+  <link rel="stylesheet" href="../css/style.css" type="text/css" charset="utf-8" />
+
+  <link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  pathId = "Ovto::Actions";
+  relpath = '../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../_index.html">Index (A)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../Ovto.html" title="Ovto (module)">Ovto</a></span></span>
+     &raquo; 
+    <span class="title">Actions</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Class: Ovto::Actions
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName">Object</span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next">Ovto::Actions</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/ovto/actions.rb</dd>
+  </dl>
+  
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>Base class for ovto actions.</p>
+
+<p>Currently this class is empty; exists for consistency and  future
+extension.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div>
+
+
+
+
+
+
+
+
+</div>
+
+      <div id="footer">
+  Generated on Fri Jun  1 21:07:20 2018 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.12 (ruby-2.4.2).
+</div>
+
+    </div>
+  </body>
+</html>