React Native ドキュメントの日本語訳

よりみやすい形でこちらで翻訳を継続しています。

https://nakanisi-yusuke.gitbooks.io/react-native-document-translate-japanese/content/

React Native

Learn once, write anywhere: Build mobile apps with React

一度学べば、どんなところでもそれを書くことが出来る:モバイル・アプリケーションを React で構築する

ネイティブ・モバイル・アプリを JavaScript と React で構築する

Build native mobile apps using JavaScript and React

React Native lets you build mobile apps using only JavaScript. It uses the same design as React, letting you compose a rich mobile UI from declarative components.

React Native を用いることで、JavaScript だけでモバイル・アプリケーションを構築することができます。React Native は React と同じ構造を使用しており、宣言的に定義した Component を用いて、上質なモバイル UI を構成することができます。

React Native アプリは、本当の モバイル・アプリケーションです

A React Native app is a real mobile app

With React Native, you don’t build a “mobile web app”, an “HTML5 app”, or a “hybrid app”. You build a real mobile app that’s indistinguishable from an app built using Objective-C or Java. React Native uses the same fundamental UI building blocks as regular iOS and Android apps. You just put those building blocks together using JavaScript and React.

React Native で作成するのは「モバイル・ウェブ・アプリ」でも「HTML5 アプリ」でも「ハイブリッド・アプリ」でもありません。作成するのは、Objective-C や Java を用いて作成したアプリケーションと、未分けがつかない、本当のモバイル・アプリです。React Native は、通常の iOS や Android のアプリケーションと同じ基本的な UI ブロックを用います。これらの UI ブロックを JavaScript と React の中に組み込みます。

再コンパイルに時間を浪費するのはやめにしましょう

Don’t waste time recompiling

React Native lets you build your app faster. Instead of recompiling, you can reload your app instantly. With Hot Reloading, you can even run new code while retaining your application state. Give it a try – it’s a magical experience.

React Native を使えば、以前より早くアプリを構築することができます。React Native では、再コンパイルをするのではなく、アプリケーションを即リロードさせることができます。Hot Reloading によって、変更を加えた新しいコードを、アプリケーションの状態を保持したまま、実行することができます。試してみてください。魔法のような体験です。

必要な時にネイティブ・コードを使用することもできます

Use native code when you need to

React Native combines smoothly with components written in Objective-C, Java, or Swift. It’s simple to drop down to native code if you need to optimize a few aspects of your application. It’s also easy to build part of your app in React Native, and part of your app using native code directly – that’s how the Facebook app works.

React Native はスムーズに、Objective-C や Java や Swift で書かれたコンポーネントを取り込むことができます。アプリのいくつかの側面を最適化するために、ネイティブ・コードを使用する方法は非常に簡潔です。またアプリの一部に React Native を用い、一部にネイティブ・コードを直に使うことも簡単です。Facebook アプリケーションもそのようにして動作しています。

React Native を始めましょう

Get Started with React Native

Who’s using React Native?

Thousands of apps are using React Native, from established Fortune 500 companies to hot new startups. If you’re curious to see what can be accomplished with React Native, check out these apps!

何千ものアプリケーションが React Native を使用しています。その範囲は広く、既に評価が安定した Fortune 500 カンパニーから、今まさに動いている新規スタートアップでも使用されています。

Getting Started

This page will help you install and build your first React Native app. If you already have React Native installed, you can skip ahead to the Tutorial.

このページは初めて React Native をインストールして、アプリケーションを作る人のための情報を提供します。すでにインストールしているひとは飛ばして、次のチュートリアルに進んでください。(このチュートリアル)

Quick Start

Create React Native App is the easiest way to start building a new React Native application. It allows you to start a project without installing or configuring any tools to build native code – no Xcode or Android Studio installation required (see Caveats).

Create React App は、新規のリアクト・ネイティブ・アプリケーションを作るうえで一番簡単な方法です。native コードをビルドするために、他のツールのインストールや設定がまったく必要ありません。Xcode も Android Studio もインストールする必要がありません。

Assuming that you have Node installed, you can use npm to install thecreate-react-native-appcommand line utility:

ただし、Node がインストールされており、npm をつかってコマンドラインから create-react-app をインストールできる必要があります。

では次のコマンドでインストールしていきましょう。

$ npm install -g create-react-native-app

Then run the following commands to create a new React Native project called “AwesomeProject”:

以下のコマンドで、”Awesome Project”という名称の新規の React Native プロジェクトを作成しましょう。

$ create-react-native-app AwesomeProject
$ cd AwesomeProject
$ npm start

This will start a development server for you, and print a QR code in your terminal.

これで開発用サーバーが立ち上がり、QR コードがターミナルに表示されます。

Running your React Native application

Install theExpo client app on your iOS or Android phone and connect to the same wireless network as your computer. Using the Expo app, scan the QR code from your terminal to open your project.

クライアントアプリケーションの Expo をご自身の iOS もしくは Android にインストールして、使用しているコンピューターと同じワイヤレスネットワークに接続してください。Expo アプリを使って ターミナルに表示された QR コードをスキャンをしましょう。するとプロジェクトが端末上で展開されます。

Modifying your app

Now that you have successfully run the app, let’s modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

さてこれでアプリケーションを走らせることに成功しましたので、次は変更をくわえてきいきましょう。App.js をテキストエディターで開いて編集していきます。変更を加えると、自動的にアプリケーションがリロードされます。

That’s it!

Congratulations! You’ve successfully run and modified your first React Native app.

おめでとうございます。最初の React Native アプリを走らせて、さらに変更を加えることに成功しましたね。

Now what?

次にどうすればいいか。

  • Create React Native App also has a user guideyou can reference if you have questions specific to the tool.

  • User guideがあるので、Create React Native Appに関して疑問があれば参照してください。

  • If you can’t get this to work, see the Troubleshooting section in the README for Create React Native App.

  • うまくこのチュートリアルが動かなかった場合には、Troubleshooting を読んでください。

If you’re curious to learn more about React Native, continue on to the Tutorial.

React Native について興味がうまれてもっと学びたいという場合には Tutorial を読み続けてください。

Running your app on a simulator or virtual device

作成したアプリケーションを、シミュレータもしくは仮想デバイス上で動かす

Create React Native App makes it really easy to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for building projects with native code to learn how to install Xcode and set up your Android development environment.

Create React Native App は、開発環境の設定をする必要がないので非常に簡単に、実際の物理デバイス上でアプリケーションを走らせることができます。ですが、アプリケーションを iOS シミュレータや Android の仮想デバイス上で動かしたい場合には、Xcode のインストールと Android 開発環境のセットアップに関する説明を読んでください。

Once you’ve set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

セットアップが完了しさえすれば、Android Virtual Device の場合には npm run androidと実行すればアプリケーションをその上で動かすことができます。iOS シミュレータの場合にはnpm run iosと実行してください。(ただし iOS シミュレータは macOS でしか提供されていません)

iOS シミュレータもしくは Android Virtual Device でアプリケーションを動かすための準備

Installing dependencies

You will need Node, Watchman, the React Native command line interface, and Xcode.

Node, Watchman, React Native command line interface, Xcode が必要です。

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

開発に使うのは、どんなエディターでもかまいませんが、まず Xcode をインストールして、React Native app をビルドするのに必要なツールを用意する必要があります。

Node, Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

Node と Watchman のインストールには Homebrew をしようすることを推奨します。Homebrew をインストールした後に、以下のコマンドをターミナルで実行してください。

$ brew install node
$ brew install watchman

If you have already installed Node on your system, make sure it is version 4 or newer.

すでに Node をインストールしている場合には、そのバージョンが 4 以上であるようにしてください。

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Watchman は Facebook が開発したツールで、filesystem の変更を監視します。より良いパフォーマンスのために、このツールをインストールすることを強く推奨いたします。

The React Native CLI

Node comes with npm, which lets you install the React Native command line interface.

Node に付随している npm を使用して、React Native command line interface をインストールしましょう。

Run the following command in a Terminal:

以下のコマンドをターミナルで実行します。

$ npm install -g react-native-cli

If you get an error like Cannot find module 'npmlog', try installing npm directly: curl -0 -L https://npmjs.org/install.sh | sudo sh.

次のようなエラーが出る場合には Cannot find module 'npmlog'、npm をダイレクトにインストールしてください: curl -0 -L https://npmjs.org/install.sh | sudo sh.

Xcode

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

Xcode をインストールする一番簡単な方法は Mac App Store を使うことです。Xcode をインストールすると、同時に iOS Simulator と iOS app をビルドするために必要なツール一式もインストールしてくれます。

If you have already installed Xcode on your system, make sure it is version 8 or higher.

Xcode をすでにインストールしている場合には、バージョンが8以上であるようにしてください。

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose “Preferences…” from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tool もインストールする必要があります。Xcode を開いて、”Preferences…” を Xcode のメニューから洗濯してください。Location パネルに移動し、Command Line Tools のドロップダウンから、一番最新のものを選択してインストールします。

Caveats

Because you don’t build any native code when using Create React Native App to create a project, it’s not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you’ll eventually need to include your own native code, Create React Native App is still a good way to get started. In that case you’ll just need to “eject” eventually to create your own native builds. If you do eject, the “Building Projects with Native Code” instructions will be required to continue working on your project.

Create React Native App configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you’re integrating React Native into an existing project, you’ll want to skip Create React Native App and go directly to setting up the native build environment. Select “Building Projects with Native Code” above for instructions on configuring a native build environment for React Native.

Learn the Basics

React Native is like React, but it uses native components instead of web components as building blocks. So to understand the basic structure of a React Native app, you need to understand some of the basic React concepts, like JSX, components, state, and props. If you already know React, you still need to learn some React-Native-specific stuff, like the native components. This tutorial is aimed at all audiences, whether you have React experience or not.
 
React Native は React と似ています。ただし、アプリケーションを構成するために、Web Component ではなく Native Component を用いる点は異なっています。ですので React Native App の基本的な概念を学ぶためには、React の基礎的な概念を理解する必要があります。例えば JSX, component, state, prop といった概念などです。React をすでに知っているのであれば、さらに進んで native component のような React Native に特有の概念を学んでいく必要があります。本チュートリアルは、React の経験がある人もない人も、全ての方向けに作成されています。
 
Let’s do this thing.
 
では進めていきましょう。
 

Hello World

 
In accordance with the ancient traditions of our people, we must first build an app that does nothing except say “Hello world”. Here it is:
 
太古からの我々の伝統に乗っ取り、「Hello, world」と言う以外に何もしないアプリケーションを構築しましょう。
 
If you are feeling curious, you can play around with sample code directly in the web simulators. You can also paste it into your App.js file to create a real app on your local machine.
 
興味があれば、サンプルコードを Web シミュレータ上で直接実行してみてください。もしくは上記のコードを App.js ファイルにペースとして、ローカルマシーン上の実際のアプリケーションの上で実行してみましょう。
 

What’s going on here?

 
何がおきているか
 
Some of the things in here might not look like JavaScript to you. Don’t panic. This is the future.
 
ここで起きていることは、JavaScript のようには見えないかもしれません。動転しないでください。これは次世代の JavaScript なんです。
 
First of all, ES2015 (also known as ES6) is a set of improvements to JavaScript that is now part of the official standard, but not yet supported by all browsers, so often it isn’t used yet in web development. React Native ships with ES2015 support, so you can use this stuff without worrying about compatibility. import, from, class, extends, and the () => syntax in the example above are all ES2015 features. If you aren’t familiar with ES2015, you can probably pick it up just by reading through sample code like this tutorial has. If you want, this page has a good overview of ES2015 features.
 
訳注:ES2015 についての解説。ES2015について慣れていない人は、this pageを参照。
 
The other unusual thing in this code example is <Text> Hello world!</Text>. This is JSX – a syntax for embedding XML within JavaScript. Many frameworks use a special templating language which lets you embed code inside markup language. In React, this is reversed. JSX lets you write your markup language inside code. It looks like HTML on the web, except instead of web things like <div> or <span>, you use React components. In this case, <Text> is a built-in component that just displays some text.
 
訳注:<Text> は見慣れない構文であるが、これはJSX の記法。React Compont の呼び出し。詳しくは React そのもののマニュアルを参照。
 

Components

 
So this code is defining HelloWorldApp, a new Component. When you’re building a React Native app, you’ll be making new components a lot. Anything you see on the screen is some sort of component. A component can be pretty simple – the only thing that’s required is a render function which returns some JSX to render.
 
ということで上記のコードは、HelloWorldApp という新しいコンポーネントを定義しています。React Native app を構築していくにあたって、新しいコンポーネントをたくさん作っていくことになります。スクリーンに写っているものはどれでも全て、このようなコンポーネントでできています。コンポーネントは非常にシンプルです。必要なのは、レンダリングされる JSX を return する render function を持っていることだけです。
 

This app doesn’t do very much

 
このアプリはほとんど何もしていませんね。
 
Good point. To make components do more interesting things, you need to learn about Props.
 
おっしゃる通りです。もっと面白いことをするために、次に Props を学びましょう。
 

Props

 
Most components can be customized when they are created, with different parameters. These creation parameters are called props.
 
ほとんどのコンポーネントは、作成される際に、異なるパラメーターを元に、カスタマイズすることができます。この際に用いるパラメーターが、props です。
 
For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.
 
例えば、React Native コンポーネントの基礎的なものの一つして Image がありますが、この Image を作成する際に、source という名前の prop を用いることで Image コンポーネントが何を表示するかを制御することができます。
 
Notice that {pic} is surrounded by braces, to embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.
 
{pic} というふうに、{} で囲まれている点に着目してください。これによって pic と言う変数を JSX の中に埋め込んでいます。JSX 内に {} によって、どんな JavaScript expression も埋め込むことができます。
 
Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place. Just refer to this.props in your render function. Here’s an example:
 
自分作成したコンポーネントにも props を用いることができます。これによって、同じコンポーネントを様々な場所で、少しだけ異なる内容を持たせて使用することが可能になります。Render function の中で、this.props を参照するだけです。
 
Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, just like the built-in components. The power to do this is what makes React so cool – if you find yourself wishing that you had a different set of UI primitives to work with, you just invent new ones.
 
name という prop を用いることで、Greeting コンポーネントをカスタマイズすることができるので、同じコンポーネントをそれぞれ異なる挨拶に対して使いまわすことができます。また、この例では Greeting コンポーネントを JSX の中で用いていますが、あたかも built-in コンポーネントかのように用いています。こうすることには大きな利点があり、それによって React をとてもクールなものにしています。つまり、UI primitive(訳注:おそらく Native Cmponent のままの素朴な UI のこと) とは少し違ったものを使いたいと思った場合には、自分でそれを作ってしまえばいいのです。
 
The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.
 
ここではもう一つ新しいものが使われています。 View component です。View は、そのほかのコンポーネントのコンテイナーとして便利なもので、スタイルやレイアウトをコントロールする際に便利です。
 
With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.
 
props と 基礎的な TextImageView コンポンーネントによって、広範囲にわたる静的な画面を作り出すことができます。時間によって変化するアプリケーションを作りたい場合には、State を学ぶ必要があります。
 

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.
 
コンピポーネントをコントロールするために用いることができるデータには、二種類あります。一つは prop で もう一つは state です。props は親要素から渡され、コンポーネントのライフタイムを通して固定されます。変化するデータに関しては、state を使う方が良いでしょう。
 
In general, you should initialize state in the constructor, and then call setState when you want to change it.
 
一般的に言って、コンストラクタにおいて state を初期化し、それを変える場合には setState を用います。
 
For example, let’s say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The “whether the text is currently on or off” changes over time, so that should be kept in state.
 
例えば、テキストを時間経過にあわせて点滅させたいとします。テキスト自体は Blink コンポーネントが生成された際にコンポーネント自体に与えられ保持します。その際には prop 経由でテキストの内容を与えられます。
 
In a real application, you probably won’t be setting state with a timer. You might set state when you have new data arrive from the server, or from user input. You can also use a state container like Redux to control your data flow. In that case you would use Redux to modify your state rather than calling setState directly.
 
実際のアプリケーションの場合には、state をタイマーを使ってセットするようなことはないでしょう。どちらかといえば、サーバーから新しいデータを取得した際や、ユーザーがインプットした際に、状態を変更するはずです。また Redux のような state container を用いて、data flow をコントロールすることもできます。その場合には Redux を使って状態を変更することになるので、setState をそのまま呼び出すことはありません。
 
When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.
 
setState が呼び出されると、BlinkApp は自分自身のコンポーネントを re-render します。Timer の中で setState を呼び出すことで、コンポーネントは Timer が駆動するたびに、コンポーネントを re-render します。
 
State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you might be annoyed that most of our examples so far use boring default black text. To make things more beautiful, you will have to learn about Style.
 
React Native における State は React における State と全く同じように動作しますので、state の扱いをより知りたい場合には React Component API を参照ください。さて、この時点では我々の例示が今のところは退屈な黒いだけのテキストであることに、苛立ちを感じていることでしょう。より装飾的にするために、次は Style を学んでいきます。
 

Style

With React Native, you don’t use a special language or syntax for defining styles. You just style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g backgroundColor rather than background-color.
 
React Native 使う場合、スタイルを定義するための、特別な言語やシンタックスは必要ありません。単に JavaScript を使ってアプリケーションをスタイリングしていきます。全てのコアとなるコンポーネントは、style という名前の prop を受け付けます。スタイルの名前とあたいはほとんど web で一般的に使われる CSS と同じですが、例外は名前がキャメルケースを使って書かれているものです。例えば backgroundColor とすべきで、background-color としてはいけません。
 
The style prop can be a plain old JavaScript object. That’s the simplest and what we usually use for example code. You can also pass an array of styles – the last style in the array has precedence, so you can use this to inherit styles.
 
style prop は普通の伝統的な JavaScript のオブジェクトを渡します。これが一番シンプルな形式で、サンプルコードでは一般的にこのタイプが使われます。また style の配列を渡すこともできます。配列の最後のスタイルが適応されますので、これをつかってスタイルを継承させることができます。(訳注:おそらく、配列の前から後ろへと上書きされていくということがいわれていると思われる。)
 
As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here’s an example:
 
コンポーネントが複雑になるにつれて、StyleSheet.create を用いて複数のスタイルを一箇所にまとめた方が、より綺麗に整頓できるはずです。次のように。
 
One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles “cascade” the way they do in CSS.
 
よくある手法として、コンポーネントには一つだけの style prop を受け取らせて、それを用いてサブコンポーネントをもスタイリングさせる手法です。これを用いて style を “cascade” することができます。これは CSS でも行われる手法ですね。(訳注:よくわからない。実例が欲しいところ。)
 
There are a lot more ways to customize text style. Check out the Text component reference for a complete list.
 
text のスタイリングをする方法はたくさんあります。Text component のリファレンスを参照してください。
 
Now you can make your text beautiful. The next step in becoming a style master is to learn how to control component size.
 
さあ Text を美しく装飾することができました。次なる style マスターへの一歩は、コンポーネントのサイズをコントロールすることです。
 

Height and Width

A component’s height and width determine its size on the screen.
 
コンポーネントの高さと幅の定義によって、スクリーン上に表示されるサイズを規定します。
 

Fixed Dimensions

 
固定サイズの場合
 
The simplest way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.
 
コンポーネントの縦横幅を決める一番簡単な方法は、style で幅と高さを与えることです。React Native に置ける全ての縦横幅は、untiless で、density-independent pixel を表しています。(訳注:1px がどのような規格基準での 1px なのかを表していると思われる)
 
Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.
 
このような方法で縦横幅を設定する方法は、いつでも同じサイズでレンダリングされるべきコンポーネントのために一般的に使われます。スクリーンのサイズがどうであれ一定幅でレンダリングする場合です。
 

Flex Dimensions

 
状況に合わせて伸縮する縦横幅
 
Use flex in a component’s style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst each other component with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.
 
コンポーネントの Style の中で flex を用いることで、使用可能なスペースに合わせて伸び縮みさせることができます。flex: 1 を用いると、コンポーネントに対して使えるスペース全部を埋めるように支持することになります。ただしその際に同じ親コンポーネントを持つ隣接するコンポーネントとその領域をわけあうことになります。flex の値が大きくなるほど、兄弟要素の間で、占める割合が増すことになります。
 
_A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.
_
 
コンポーネントは使用可能なスペース全てを埋めるわけですが、それは親要素の縦横幅が 0 以上の場合に限られます。もし親要素に高さや幅を固定もしくは flex で指定されてない場合、親要素の縦横幅が 0 になってしまうので、その子要素に flex が指定されていたとしても、見えなくなってしまいます。
 
After you can control a component’s size, the next step is to learn how to lay it out on the screen.
 
コンポーネントのサイズをコントロールできるようになったので、次はスクリーン上にどのようにレイアウトするのかを学習します。

Redux 公式ドキュメントのリポジトリ→ GitHub fork → GitBook の連携

以前から勝手に OSS ドキュメントの翻訳をしてはこのブログに公開していましたが、読みにくいというクレームをよく頂いておりました。しかし、そうは言われても、公式ページと同じ公開方式 (例えば GitHub Pages や GitBook 形式がよく使われています) で翻訳した結果を公開するのは、少し自分には難しい…と思っておりました。

が、ついに綺麗なフォーマットで公開できそうです。

Redux の公式ドキュメントは GitBook 形式なのですが、GitBook にするためのソースは全て GitHub で公開されています。これを以下の手順で処理して、翻訳していきます。

  1. まずは自分の GitHub アカウントを持つ。
  2. Redux ドキュメントの GitHub リポジトリから自分の GitHub へ Fork する。
  3. GitBook のアカウントと、自分の GitHub アカウントを連携させる。
  4. 自分の GitHub アカウント内の Fork した Redux ドキュメントのリポジトリを、GitBook 上で読み込む。
  5. GitBook のブラウザ・エディタで翻訳する。
  6. GitBook で Publish すると、GitBook 上のリポジトリにも、連携している自分の GitHub リポジトリにも自動的に反映される。

こうすると次のような利点があります。

  1. GitBook と GitHub が sync するので、どちらか一方を編集した際に、もう一方も変更される。
  2. GitBook のウェブ上のエディターを用いることで、GitBook で公開されるフォーマットとほぼ同じ形のまま、編集・翻訳できる。
  3. GitBook で Publish すると、その結果が GitHub にコミットされるので、GitHub で OSS に貢献している雰囲気が非常に出る。(活動ログに濃い緑色のマップが作成できる)

Continue reading “Redux 公式ドキュメントのリポジトリ→ GitHub fork → GitBook の連携”

React v16.0 メジャーバージョンアップ

例によって勝手に翻訳

https://reactjs.org/blog/2017/09/26/react-v16.0.html

個人的な react 16 関連情報リスト

React v16.0

We’re excited to announce the release of React v16.0! Among the changes are some long-standing feature requests, including fragmentserror boundariesportals, support for custom DOM attributes, improved server-side rendering, and reduced file size.

React v16.oのリリースをお知らせできることに、胸が高鳴っています。今回の変更の中には、皆さんから長く要望いただいていた機能もあります。fragmentserror boundariesportals, custom DOM attributes のサポート, 改善された server-side rendering, そして reduced file size などです。

New render return types: fragments and strings

render メソッド内における return の新しい形式:fragment と string

You can now return an array of elements from a component’s render method. Like with other arrays, you’ll need to add a key to each element to avoid the key warning:

コンポーネントの render メソッド内で、要素の配列を return することが出来るようになりました。他の配列と同様に、各要素に key を与える必要があります。これにより key warning を避けることができます。

// list item を余計な要素で囲む必要はありません。

// key を与えることを忘れずに。

render() {
  // No need to wrap list items in an extra element!
  return [
    // Don't forget the keys :)
    <li key="A">First item</li>,
    <li key="B">Second item</li>,
    <li key="C">Third item</li>,
  ];
}

In the future, we’ll likely add a special fragment syntax to JSX that doesn’t require keys.

将来的には、JSXのための特別な fragment シンタックスを提供する予定です。このシンタックスにおいては、key は必要なくなります。

We’ve added support for returning strings, too:

また文字列の return にも対応しました。

//「 見てよお母さん。span で囲まなくてもいいんだ。

render() {
  return 'Look ma, no spans!';
}

See the full list of supported return types.

Better error handling

エラー・ハンドリングの改善

Previously, runtime errors during rendering could put React in a broken state, producing cryptic error messages and requiring a page refresh to recover. To address this problem, React 16 uses a more resilient error-handling strategy. By default, if an error is thrown inside a component’s render or lifecycle methods, the whole component tree is unmounted from the root. This prevents the display of corrupted data. However, it’s probably not the ideal user experience.

以前は、レンダリング時にランタイム・エラーが生じた場合、React は壊れた状態になってしまい、意味不明なエラー・メッセージを表示していました。そしてその状態を直すためにはページを再更新する必要がありました。 このような問題に対処するため、React 16 はより柔軟性のあるエラーハンドリング戦略を用いることにしました。初期設定では、エラーがコンポーネントの render メソッドやライフサイクル・メソッドの中で生じた場合、コンポーネント・ツリー全体が、ルートコンポーネントからアンマウントされるようになっています。これによって、壊れたデータが表示されることを防いでいます。しかし、おそらくこれは、理想的なユーザー体験とは言い難いものです。

Instead of unmounting the whole app every time there’s an error, you can use error boundaries. Error boundaries are special components that capture errors inside their subtree and display a fallback UI in its place. Think of error boundaries like try-catch statements, but for React components.

エラーが生じる度にアプリケーション全体をアンマウントするのではなく、代わりに「Error Boundaries」を用いることができます。「Error boundaries」は、特別なコンポーネントで、自身の下層にあるツリーで生じたエラーを捉えて、フォールバック UI を代わりに表示します。「Error boundaries」は、トライ/キャッチ文と同じようなものだと考えてもいいでしょう。ただし React コンポーネントのためのトライ/キャッチ文です。

For more details, check out our previous post on error handling in React 16.

詳細は previous post on error handling in React 16 を確認ください。

Portals

Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.

「portal」機能は、子要素を、親コンポーネントのDOMヒエラルキーの外側に存在するDOM node に対して、レンダリングする機能です。

render() {
  // React does *not* create a new div. It renders the children into `domNode`.
  // `domNode` is any valid DOM node, regardless of its location in the DOM.
  return ReactDOM.createPortal(
    this.props.children,
    domNode,
  );
}

See a full example in the documentation for portals.

(訳注: react は通常、自分の子要素の位置にコンポーネントをレンダリングするが、portal を用いると、その縛りから放たれて、どの DOM に対してもコンポーネントをレンダリングをできるようだ。具体的なユースケースとして、overflow: hidden されている親要素の中のコンポーネントから、モーダルウィンドウを生成したい場合があげられている。通常であれば、overflow: hidden されている要素の子要素として DOM がレンダリングされる以上、親要素の外にはみ出るような視覚表現を作り出すことができない。このような条件において、親要素の外側に DOM をレンダリングする必要が発生し、その場合に portal 機能が有用となる。)

Better server-side rendering

サーバーサイドレンダリングの改善

React 16 includes a completely rewritten server renderer. It’s really fast. It supports streaming, so you can start sending bytes to the client faster. And thanks to a new packaging strategy that compiles away process.env checks (Believe it or not, reading process.env in Node is really slow!), you no longer need to bundle React to get good server-rendering performance.

React 16 は、完全に新たに書き直された server render を用いています。これによって非常に早くなりました。この新しい server render は、ストリーミングをサポートしており、非常に早くクライアントへの情報送信を開始することができるようになりました。また  new packaging strategy のお陰で(これはprocess.env のチェックをコンパイルから取り除いています。信じられないかもしれませんが、Node の process.env は本当に遅いのです!)、サーバーレンダリングのパフォーマンスをよくするためにReact をバンドルする、ということが必要なくなりました。

Core team member Sasha Aickin wrote a great article describing React 16’s SSR improvements. According to Sasha’s synthetic benchmarks, server rendering in React 16 is roughly three times faster than React 15. “When comparing against React 15 with process.env compiled out, there’s about a 2.4x improvement in Node 4, about a 3x performance improvement in Node 6, and a full 3.8x improvement in the new Node 8.4 release. And if you compare against React 15 without compilation, React 16 has a full order of magnitude gain in SSR in the latest version of Node!” (As Sasha points out, please be aware that these numbers are based on synthetic benchmarks and may not reflect real-world performance.)

React 開発のコアメンバーである「Sasha Aickin」がRact 16 の SSR が大きく進歩したということについて記事を書いています。「great article describing React 16’s SSR improvements」 Sahsa のシンセティック・ベンチマークによればReact 16 のサーバーレンダリングは、ざっくりって React 15 の3倍は早いことがわかりました。「process.env をコンパイルした React15 と比較すると、node 4 では2.4倍の改善がされ、node 6 では3倍の、そして最新のnode 8.4 では3.8倍の改善がされました。そしてコンパイルなしの react 15 と比較するとすれば、最新バージョンの Node では、なんと一桁違う改善がされています!」(Sashaが指摘していることですが、この数字はシンセティック・ベンチマークによるもので、実際のパフオーマンスを、必ずしも反映するものではない点に注意してください。)

In addition, React 16 is better at hydrating server-rendered HTML once it reaches the client. It no longer requires the initial render to exactly match the result from the server. Instead, it will attempt to reuse as much of the existing DOM as possible. No more checksums! In general, we don’t recommend that you render different content on the client versus the server, but it can be useful in some cases (e.g. timestamps).

加えて、React 16 は hydrating server-rendered HTML を改善しています。(ただし一旦クライアントにリーチした場合のみですが) 最早、サーバーからの結果と完全にマッチさせるために最初のレンダリングをする、という必要がなくなりました。その代わりに、既に存在するDOMを最大限、再活用するようになりました。もうチェックサムは必要ありません!一般的に言って、クライアント側とサーバー側で異なるコンテンツをレンダリングすることは、おすすめしません。とはいえ有効なケースもあります。(例えばtimestampなど)

See the documentation for ReactDOMServer for more details.

Support for custom DOM attributes

カスタム DOM 属性のサポート

Instead of ignoring unrecognized HTML and SVG attributes, React will now pass them through to the DOM. This has the added benefit of allowing us to get rid of most of React’s attribute whitelist, resulting in reduced file sizes.

HTML と SVG の React が認識できない属性に関して、今まで React は無視をしてきましたが、React 16 ではそのまま DOM に渡すようになりました。これによって以前のReactのホワイト・リストを使わなくて良くなるので、結果としてファイルサイズが小さくなります。

Reduced file size

小さくなったファイルサイズ

Despite all these additions, React 16 is actually smaller compared to 15.6.1!

様々な機能追加にもかかわらず、React 16 は 15.6.1 よりもファイルサイズが小さくなりました!

  • react is 5.3 kb (2.2 kb gzipped), down from 20.7 kb (6.9 kb gzipped).
  • react-dom is 103.7 kb (32.6 kb gzipped), down from 141 kb (42.9 kb gzipped).
  • react + react-dom is 109 kb (34.8 kb gzipped), down from 161.7 kb (49.8 kb gzipped).

That amounts to a combined 32% size decrease compared to the previous version (30% post-gzip).

The size difference is partly attributable to a change in packaging. React now uses Rollup to create flat bundles for each of its different target formats, resulting in both size and runtime performance wins. The flat bundle format also means that React’s impact on bundle size is roughly consistent regardless of how you ship your app, whether it’s with Webpack, Browserify, the pre-built UMD bundles, or any other system.

サイスが小さくなった理由の一部は、packaging 方法の変更にあります。React は Rollup を用い、異なった対象のフォーマットへのフラットバンドルを作っています。結果としてサイズの点でもランタイム・パフォーマンスの点でも向上しました。フラットバンドルフォーマットであるということは同時に次のことも意味します。つまり、Webpack, Browserify, the pre-built UMD bundles, や他のどのシステムを用いてアプリケーションを最終的にバンドルするとしても、Reactのバンドルサイズは小さいままです。

MIT licensed

In case you missed it, React 16 is available under the MIT license. We’ve also published React 15.6.2 under MIT, for those who are unable to upgrade immediately.

React 16 は MIT ライセンスで運用されます。15.6.2 も同じく MIT ライセンスでした。

New core architecture

新しいコア・アーキテクチャ

React 16 is the first version of React built on top of a new core architecture, codenamed “Fiber.” You can read all about this project over on Facebook’s engineering blog. (Spoiler: we rewrote React!)

React 16 は新しいコアアーキテクチャである”Fiber”のもと構築された、最初のReact です。このプロジェクトの全貌については Facebook’s engineering blog の記事で知ることができます。

Fiber is responsible for most of the new features in React 16, like error boundaries and fragments. Over the next few releases, you can expect more new features as we begin to unlock the full potential of React.

“Fiber” こそが、React 16 の新機能の多くの立役者です。error boundaries や fragment といった新機能は Fiber によって成り立っています。次に続くいくつかのリリースでも、さらに多くの新機能を追加する予定です。React のポテンシャルを最大限引き出していきます。

Perhaps the most exciting area we’re working on is async rendering—a strategy for cooperatively scheduling rendering work by periodically yielding execution to the browser. The upshot is that, with async rendering, apps are more responsive because React avoids blocking the main thread.

おそらく一番エキサイティングな部分は「async rendering」でしょう。

This demo provides an early peek at the types of problems async rendering can solve:

 Follow
Andrew Clark @acdlite

Ever wonder what “async rendering” means? Here’s a demo of how to coordinate an async React tree with non-React work https://gist.github.com/acdlite/f31becd03e2f5feb9b4b22267a58bc1f 

Twitter Ads info and privacy

Tip: Pay attention to the spinning black square.

We think async rendering is a big deal, and represents the future of React. To make migration to v16.0 as smooth as possible, we’re not enabling any async features yet, but we’re excited to start rolling them out in the coming months. Stay tuned!

Installation

React v16.0.0 is available on the npm registry.

React v16.0.0 は npm レジストリ上で手に入れることができます。

To install React 16 with Yarn, run:

Yarn を用いて React 16 をインストールするには、次のコマンドを実行してください。

yarn add react@^16.0.0 react-dom@^16.0.0

To install React 16 with npm, run:

npm を用いて React 16 をインストールするには、次のコマンドを実行してください。 

npm install --save react@^16.0.0 react-dom@^16.0.0

We also provide UMD builds of React via a CDN:

また、React の UMD ビルドを CDN を通じて提供しています。

<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>

Refer to the documentation for detailed installation instructions.

Upgrading

Although React 16 includes significant internal changes, in terms of upgrading, you can think of this like any other major React release. We’ve been serving React 16 to Facebook and Messenger.com users since earlier this year, and we released several beta and release candidate versions to flush out additional issues. With minor exceptions, if your app runs in 15.6 without any warnings, it should work in 16.

React 16 は莫大な内部変更が加えられましたが、アップグレードという観点からいえば、他の React メジャーバージョンアップのリリースと変わりません。我々は既に今年の初めには React 16 を Facebook や Messenger.com のサービスに使用しており、幾つかのベータ版と候補バージョンを出して、機能を追加してきました。いくつかの細かな例外を除けば、あなたのアプリケーションが 15.6 上で warning なしに動いているのであれば、基本的に 16 上でも動作します。

New deprecations

Hydrating a server-rendered container now has an explicit API. If you’re reviving server-rendered HTML, use ReactDOM.hydrate instead of ReactDOM.render. Keep using ReactDOM.render if you’re just doing client-side rendering.

「Hydrating a server-rendered container」に関しては、新たに明示的な API を持つことになりました。「reviving server-rendered HTML」しているのであれば、ReactDOM.render ではなく ReactDOM.hydrate を使用してください。単にクライアントサイドレンダリングをしている場合には、いつもどおりReactDOM.render を使用してください。

React Addons

As previously announced, we’ve discontinued support for React Addons. We expect the latest version of each addon (except react-addons-perf; see below) to work for the foreseeable future, but we won’t publish additional updates.

既に発表した通り、React Addons のサポートを打ち切りました。それぞれのaddon の最終バージョンは、しばらく問題なく動くはずですが、しかし新たな更新をする予定はありません。

Refer to the previous announcement for suggestions on how to migrate.

react-addons-perf no longer works at all in React 16. It’s likely that we’ll release a new version of this tool in the future. In the meantime, you can use your browser’s performance tools to profile React components.

react-addons-perfは React 16 では動きません。おそらく新しいこういったツールを将来発表するはずです。しばらくのあいだは、ブラウザのパフォーマンスツールを使ってReact コンポーネントの捜査を行ってください。 (use your browser’s performance tools to profile React components.)

Breaking changes

破壊的変更

React 16 includes a number of small breaking changes. These only affect uncommon use cases and we don’t expect them to break most apps.

React 16 はかなりの数の破壊的変更が加えられました。これらが影響をあたえるのはかなり特殊なケースで運用されているアプリケーションに限られており、ほとんどのアプリケーションにおいて、動かなくなることはないと予想しています。

  • React 15 had limited, undocumented support for error boundaries using unstable_handleError. This method has been renamed to componentDidCatch. You can use a codemod to automatically migrate to the new API.
  • ReactDOM.render and ReactDOM.unstable_renderIntoContainer now return null if called from inside a lifecycle method. To work around this, you can use portals or refs.
  • setState:
    • Calling setState with null no longer triggers an update. This allows you to decide in an updater function if you want to re-render.
    • Calling setState directly in render always causes an update. This was not previously the case. Regardless, you should not be calling setState from render.
    • setState callbacks (second argument) now fire immediately after componentDidMount / componentDidUpdate instead of after all components have rendered.
  • When replacing <A /> with <B />B.componentWillMount now always happens beforeA.componentWillUnmount. Previously, A.componentWillUnmount could fire first in some cases.
  • Previously, changing the ref to a component would always detach the ref before that component’s render is called. Now, we change the ref later, when applying the changes to the DOM.
  • It is not safe to re-render into a container that was modified by something other than React. This worked previously in some cases but was never supported. We now emit a warning in this case. Instead you should clean up your component trees using ReactDOM.unmountComponentAtNode. See this example.
  • componentDidUpdate lifecycle no longer receives prevContext param. (See #8631)
  • Shallow renderer no longer calls componentDidUpdate because DOM refs are not available. This also makes it consistent with componentDidMount (which does not get called in previous versions either).
  • Shallow renderer does not implement unstable_batchedUpdates anymore.
  • ReactDOM.unstable_batchedUpdates now only takes one extra argument after the callback.

Packaging

  • There is no react/lib/* and react-dom/lib/* anymore. Even in CommonJS environments, React and ReactDOM are precompiled to single files (“flat bundles”). If you previously relied on undocumented React internals, and they don’t work anymore, let us know about your specific case in a new issue, and we’ll try to figure out a migration strategy for you.
  • There is no react-with-addons.js build anymore. All compatible addons are published separately on npm, and have single-file browser versions if you need them.
  • The deprecations introduced in 15.x have been removed from the core package. React.createClass is now available as create-react-classReact.PropTypes as prop-typesReact.DOM as react-dom-factoriesreact-addons-test-utils as react-dom/test-utils, and shallow renderer as react-test-renderer/shallow. See 15.5.0 and 15.6.0 blog posts for instructions on migrating code and automated codemods.
  • The names and paths to the single-file browser builds have changed to emphasize the difference between development and production builds. For example:
    • react/dist/react.js → react/umd/react.development.js
    • react/dist/react.min.js → react/umd/react.production.min.js
    • react-dom/dist/react-dom.js → react-dom/umd/react-dom.development.js
    • react-dom/dist/react-dom.min.js → react-dom/umd/react-dom.production.min.js

JavaScript Environment Requirements

React 16 depends on the collection types Map and Set. If you support older browsers and devices which may not yet provide these natively (e.g. IE < 11), consider including a global polyfill in your bundled application, such as core-js or babel-polyfill.

React 16 は Map や Set に依存しています。そのためこれらをサポートしてない古いブラウザにおいては(例えばIE11未満)、グローバルな polyfill をバンドルアプリケーションに含めることを検討してください。例えば core-js や babel-polyfill などを用いてください。

A polyfilled environment for React 16 using core-js to support older browsers might look like:

次のソースは、古いブラウザでも react 16 が動くようにするために、core-js を用いて React 16 のための polyfill が適用された環境の例です。

import 'core-js/es6/map';
import 'core-js/es6/set';

import React from 'react';
import ReactDOM from 'react-dom';

ReactDOM.render(
  <h1>Hello, world!</h1>,
  document.getElementById('root')
);

React also depends on requestAnimationFrame (even in test environments). A simple shim for test environments would be:

React は  requestAnimationFrame にも依存しています。(テスト環境においても依存してます) テスト環境用のシンプルな shim は以下のようになります。

global.requestAnimationFrame = function(callback) {
  setTimeout(callback, 0);
};

Acknowledgments

As always, this release would not have been possible without our open source contributors. Thanks to everyone who filed bugs, opened PRs, responded to issues, wrote documentation, and more!

Special thanks to our core contributors, especially for their heroic efforts over the past few weeks during the prerelease cycle: Brandon Dail, Jason Quense, Nathan Hunzaker, and Sasha Aickin.

Edit this page

CSS Transition と Keyframe Animation 違いと優位性

いつもはVelocity.jsをつかってアニメーションを書いているのですが、マウスホバー時のアニメーションをリッチにしたり、ReactでDOMを再レンダリングした時に目を引くためのアニメーションをさせる、そんなときにはCSSベースでアニメーションを書いたほうが、メンテナンスが簡単そう等々、利点があるなと最近感じました。

そこでTransitionとKeyframeを使ったアニメーションに関して、いくつか役にたった記事を集めて、英語のものは勝手に翻訳します。

ざっくりデモ https://codepen.io/nakanishi/pen/gxQzoZ

CSS Transitions VS Keyframe Animations

There are currently two ways to animate things with CSS:

現在、アニメーションをCSSで実装する方法は2つあります。TransitionとKeyframe Animationです。
  • Transitions
  • Keyframe Animations

Each technique has similarities and differences. Here’s how they work.

それぞれの技術は同じ点もありますし、異なる点もあります。これらの技術がどのように機能しているのか、みていきましょう。

Transitions

Transitions work by morphing a property from one value to another when the transition is triggered.

Transitionは、Propertyをある値から別の値へと変化させることで、動作します。これはトランジションがトリガーされた際におきます。

Here is a simple example (hover your mouse over the box to trigger the transition):

次の簡単な例をごらんください。

JS Bin

There are several ways to trigger a transition. The most common way is with the :hover pseudo-class (which you saw in the example above), but others include:

トランジションをトリガーする方法はいくつかあります。一番一般的な方法は、:hover疑似クラスを用いる方法ですが、他にも方法があります。

  • :active
  • :focus
  • :checked
  • :disabled
  • page load
  • media queries
  • device orientation
  • class changes (Triggered via javascript)

(By the way, there’s a great article by Louis Lazaris demonstrating some examples of these techniques) これらのテクニックを使ったサンプルが上記の記事で紹介されています。

In all cases, a user performs some action, which sets our transition in motion. You can adjust many properties of the transition, like the delay or timing, but all transitions must have a beginning and an end.

どのケースにおいても、ユーザーがなんらかのアクションを起こし、それがトランジションにモーションを与えます。トランジションの多くのpropertyを調整することが出来ます。例えば、delayやタイミングを調整することができます。しかし、Transitonの場合には、必ず開始と終了が存在します。

Keyframe Animations

Keyframe animations are similar to transitions, in that they can be used to morph properties from one value to another, but they differ in how they are defined. You define them by identifying the keyframes that make up your animation and giving that set of keyframes a name. Then, you can invoke those keyframes anywhere you want, using CSS selectors. Let’s look at an example:

Keyframe animation は次の点ではTransitionと同じです。つまり、propertyをある値から別の値へと変化させるという点においては同じです。しかし、定義の仕方が異なります。Animationを構成するKeyframeを定義し、そのKeyframe全体に名前を与えます。その後、そのkeyframeを必要な箇所で呼び出します。その際にはCSSセレクタを用います。例を見てみましょう。

JS Bin

As you can see, we’ve defined our “pulse” keyframes, and applied it to several elements.

上記の例では、pulseという名前のkeyframeを定義し、それをいくつかの要素に対して適応しています。

Which is Better?

Both have their strengths and weaknesses. Here are a few of the main benefits I’ve found for each option:

どちらの機能にも強みと弱点があります。それぞれの選択に対する主要な利点を紹介します。

Benefits of Transition:

  • Slightly better browser support (compare transitions to animations)
  • 多少ブラウザーサポートの点で優れている(訳注:ただし2017年現在ではどちらもほとんどサポートされているので、この点はあまり考慮する必要がないかも。)
  • Familiar syntax
  • 親しみやすいシンタックス
  • Simplicity
  • 明快さ
  • Easy to manipulate in Firebug/Devtools
  • FirebugやDevtoolで扱いやすい

Benefits of Keyframes:

  • More granular timing control
  • タイミングをより詳細にコントロールすることができる
  • Easy to mix and match properties (one keyframe definition can animate color and opacity, and size, etc.)
  • 複数のプロパティを組み合わせたり、そのタイミングを合わせるのが簡単。(一つのキーフレームに、色の変更や、透明度の変更や、サイズの変更、というように複数のアニメーションを指定できる。)
  • More animation options (infinite, alternate, etc.)
  • infiniteやalternateなど、より多くのアニメーションに関するオプションがある
  • Keeps code DRY
  • コードをDRYにすることができる。

Personally, I feel like animations with keyframes are more powerful, but it really comes down to your specific application (for example, I chose to use transitions in AnchorJS and keyframe animations for my Flying Toasters).

個人的にはkeyframeを使ったアニメーションのほうが強力かなと思いますが、しかし、それぞれの状況にあわせて選択することになるでしょう。例えばAnchorJSにおいてはtranstionを使いますし、私のフライングトースターのアニメーションにはkeyframeを選択しました。

Finally, one property that is often confused with these animation techniques is transform. While transform is new and can do some neat things (like rotate, scale, translate, etc), it doesn’t animate anything. It’s a typical css property like font color or opacity.

最後に、これらのアニメーションに関する技術と、混同されているpropertyがあります。それはtransformです。transformは、新しく素晴らしい効果をもたらしてくれるものですが(rotateやscaleやtranslateなど)、アニメーションをさせるものではありません。これはCSSのプロパティであって、font-colorやopacityといったものと同じです。

CSS3 Transitions Without Using :hover

Up to this point, the most common use for CSS3 Transitions has been in conjunction with the well-known CSS :hover pseudo-class.

今までのところ、CSS3 Transitionの一番よくある使い方は、これまたよく知られた :hover 擬似クラスと組み合わせて用いる方法でした。

Here’s a typical transition that changes link color on mouseover using pure CSS:

次の例は、transitionを使った典型的なもので、リンクカラーを、マウスホバー時に変更するものです。これは全て純粋なCSSによっておこなわれています。

a, a:link, a:visited {
  color: lightblue;
  -webkit-transition: color .4s linear;
  -moz-transition: color .4s linear;
  -o-transition: color .4s linear;
  -ms-transition: color .4s linear;
  transition: color .4s linear;
}

a:hover {
  color: white;
}

This will animate the color property when you hover over a link on the page. Pretty simple, and you’ve probably seen or used something similar. But transitions are not just limited to use with :hover.

このコードはcolorプロパティを、aリンクがホバーされた際に変化させます。とてもシンプルなものであり、また多分過去にあなたも見たことがあるか、実際に書いたことがあるのではないかと思います。しかし、トランジションを使えるのは:hoverだけではないのです。

You can animate CSS properties via transitions using some other CSS techniques, a number of which I’ve outlined below. I’ve also included a demo for each example.

CSSプロパティをtransitionを用いてアニメーションさせるテクニックは色々あり、その概要を書き出しました。それぞれの項目には、デモも付けました。

Transitions Using :active

The :active pseudo-class matches any element that’s in the process of being activated. The primary way that an element is “activated” is by means of a mouse click, or mouse down.

:active擬似クラスは、全てのactiveな状態にある要素とマッチします。主な、要素をactiveにする方法は、クリックする、もしくはマウスを押し込んだ状態にすることです。

Here’s some CSS and an accompanying demo that demonstrates using :active along with CSS3 transitions to mimic a mousedown event:

次のCSSは、:activeを使ったデモです。CSS3 Transitionを使って、mousedownイベントを検知した時に発動するようになっています。

.box {
  width: 300px;
  height: 300px;
  background: #222;
  -webkit-transition: width 2s ease, height 2s ease;
  -moz-transition: width 2s ease, height 2s ease;
  -o-transition: width 2s ease, height 2s ease;
  -ms-transition: width 2s ease, height 2s ease;
  transition: width 2s ease, height 2s ease;
}

.box:active {
  width: 500px;
  height: 500px;
}

With this code, the box’s width and height properties are animated to become larger as you hold the mouse down on the element. Once you release, the box animates back to its original dimensions.

このコードは、四角の横幅と高さのpropertyがアニメーションされており、要素の上でマウスダウンしている間、それが大きくなります。マウスを離すと、元のサイズに戻ります。

Here’s a demo:

Transitions Using :focus

You can use the :focus pseudo-class to do something similar. This time we’ll use a form, and we’ll animate the width of any form element that receives focus:

:focus 擬似クラスを使って、同様のことができます。今回はform要素を使いましよう。form要素にフォーカスが当たった場合に、幅をアニメーションさせてみました。

input, textarea {
  width: 280px;
  -webkit-transition: width 1s ease;
  -moz-transition: width 1s ease;
  -o-transition: width 1s ease;
  -ms-transition: width 1s ease;
  transition: width 1s ease;
}

input:focus, textarea:focus {
  width: 340px;
}

And here’s a live demo:

Transitions Using :checked

You can animate checkboxes and radio buttons when they become “checked” — although you’re limited with what you can do with those, since you can’t really change their native styling.

checkboxとradio buttonを”check”されたときに、アニメーションさせることもできます。ただしボタンに対してできることは限られています。何故ならnativeのスタイリングを変更することはできないからです。

We’ll just do a simple width change, which will appear to indent any selected checkbox:

シンプルな変更を加えてみることにしました。これによって選択されたチェックボックスは、インデントされたようになります。

input[type="checkbox"]:checked {
  height: 20px;
  -webkit-transition: width 1s ease;
  -moz-transition: width 1s ease;
  -o-transition: width 1s ease;
  -ms-transition: width 1s ease;
  transition: width 1s ease;
}

input[type="checkbox"]:checked {
  width: 30px;
}

And here’s a simple demo:

Transitions Using :disabled

Keeping with the theme of web forms, this time we’ll combine CSS3 transitions with some jQuery to animate the background color of form elements when they become disabled via the disabled attribute:

引き続きformを扱っていきます。今回は、CSS3 TransitionとjQueryを組み合わせて、formの背景色をアニメーションさせます。disabledアトリビュートによってdisableになった際にこれが発動するようにしました。

input[type="text"], textarea {
  background: #e2e2e2;
  -webkit-transition: background 1s ease;
  -moz-transition: background 1s ease;
  -o-transition: background 1s ease;
  -ms-transition: background 1s ease;
  transition: background 1s ease;
}

input:disabled, textarea:disabled {
  background: #666666;
}

And the quick-and-dirty jQuery that adds/removes the disabledattribute is:

そして非常に雑ではありますが、disabledアトリビュートをつけたり外したりするjQueryのコードは以下のようになります。

$(function() {
  $('input[type="radio"]').click(function() {
    if ($(':checked').val() === "other") {
      $('input[type="text"]').removeAttr("disabled");
    } else {
      $('input[type="text"]').attr("disabled", "disabled");
    }
  });
});

So when the last radio button is selected (the one with a value of “other”), the text box has its disabled attribute removed. If another option is selected, the disabled attribute is re-applied.

つまり、ラジオボタンの最後のものを選択すると(このボタンはotherというvalueを持っています)、テキストボックスはdisableといいうアトリビュートが鳥のどかれます。それ以外のラジオボタンが選択されると、disabledアトリビュートが再度適用されます。

The :disabled pseudo-class is dependent on that attribute being present, so the animation will occur whenever that attribute is added or removed.

:disabled 疑似要素は、現在のその属性がどのような状態であるかということに依存しますので、そのためアニメーションはそのアトリビュートが追加されたり削除されるときに、発動します。

Here’s the demo:

Transitions Using Media Queries

This last one may be the least practical, because let’s face it, the only people that ever resize their window to see what happens are web developers.

最後にとりあげるこのテーマはあまり実践的ではないかもしれません。というのも、ウィンドウサイズを変更して、何が起きるかをまじまじと観察するような人間は、ウェブディベロッパーくらいだからです。

Nonetheless, this is just another way to use CSS3 transitions. The new Modernizr design does this.

とにかく、このサンプルでは先程とは違った方法のCSS3 Transitonが使われています。新しいModernizrのデザインでもこれが使われています。

Here’s the code:

.box {
  width: 440px;
  height: 440px;
  background: #222;
  margin: 0 auto;
  -webkit-transition: width 2s ease, height 2s ease;
  -moz-transition: width 2s ease, height 2s ease;
  -o-transition: width 2s ease, height 2s ease;
  -ms-transition: width 2s ease, height 2s ease;
  transition: width 2s ease, height 2s ease;
}

@media only screen and (max-width : 960px) {
  .box {
    width: 300px;
    height: 300px;
  }
}

This example animates two different properties simultaneously, separating the two by a comma. The media query tells the box to shrink if the screen size goes below 961px.

上記の例では2つの異なるプロパティを同時にアニメーションさせています。それぞれの値はコンマで仕切られていますね。メディアクエリーはboxに、スクリーンサイズが961以下になった場合に、縮まるように定義されています。

Resize your window in the demo page to see it work:

Some Notes About the Code

If you’re wondering about the code, I’ve included the standard property last, even though it’s not supported by any browser that I know of.

どんなブラウザでも対応できるように、prefixとそれから標準的なプロパティを最後に追加しています。

Also, I’ve included the -ms- prefix, even though IE9 and IE10 do not yet support transitions. But evidently they are coming in IE10, so it’s worth including an extra line.

同じくprefixに関して。今はIE11が標準的に対応しなくてはいけないブラウザなので、ここは関係ない。

And the code examples that you can see in this post aren’t exactly the same as those used in the demo pages. I’ve made the code as brief as possible for the purpose of focusing only on the parts being discussed in this article.

デモコードは少し変えている。

Are There Other Ways?

This is pretty much all I could come up with for alternate ways to use CSS3 transitions. If you can think of another, let me know.

CSS3: Animations vs. Transitions

In CSS, you have two techniques for visualizing change that are competing for your attention: Animations & Transitions. In this article, let’s examine the similarities and differences between them so that you can know when to use which.

CSSにおいて、ユーザーの注意を引くための、視覚的な変化をもたらすための技術には、大きく分けて2つあります。一つはAnimationで、もう一つはTransitonです。この記事では、その2つの技術の同じ部分と異なる部分を精査していき、どちらを選択するばよいのか、その指針を示すことにします。

To make the most of this article, it would be helpful for you to be familiar with using both animations and transitions. If you haven’t had a chance to get your hands dirty with them, the Creating a Simple CSS Animation and Looking at CSS3 Transitions tutorials will help you get started.

この記事を最大限活用するためには、あなたが既にある程度AnimationとTransitionの技術に馴染みがあるほうがいいでしょう。実際に手を動かしてこれらの技術を使ったコードを書いたことがないのであれば、まずは上記2つのチュートリアルから始めるといいかもしれません。

Similarities

From a distance, both animations and transitions are very similar. They both allow you to:

大枠でいえば、animationとtransitionはどちらも非常に似ています。どちらも次のことができます。

  • Specify which CSS properties to listen for changes on
  • Set timing (easing) functions to alter the rate of going from a one property value to another
  • timing(イース)ファンクションを設定することで、プロパティの値の変化の進み具合を定義することが出来る。
  • Specify a duration to control how long the animation or transition will take
  • durationを設定することで、animatioやtransitionがどれくらいの時間をかけて変化するかを指定できる。
  • Programmatically listen to animation and transition-specific events that you can then do with as you wish
  • Visualize CSS property changes.

Beyond this point, though, you will see that animations and transitions diverge a bit and let their uniqueness shine through. Let’s look at those unique qualities in greater detail.

上記以外のことがらに関しては、animationとtransitionには少し違いがあり、その違いがお互いの良さを生じさせています。ではそれぞれの特質をより詳細にみていきましょう。

Differences

Animations and transitions show their differences when it comes to how you trigger them to play, whether they loop easily, how complicated of a transition you can define, how formal you must be in being able to use them, and how well they play with JavaScript. Let’s explore those topics in greater detail.

AnimationとTransitionの違いがはっきりと現れるのは、次のような点です。どのように開始のためのトリガーをするか。どれくらいループをさせることが簡単か。どれくらい複雑に変化を指定できるか。使用するためにどれくらい形式的な理解が必要か。そしてJavaScriptと組み合わせた時にどれくらい上手く動くか。ではこれらのトピックについて考えてみましょう。

Triggering

One of the major differences between animations and transitions can be seen in how you trigger them to start playing.

大きな違いの一つは、トリガーの方法です。どのように再生をスタートさせるか、という部分が異なります。

A transition only plays as a reaction to a CSS property that has changed. A common scenario is one where you use the :hover pseudo class to change the value of a CSS property:

Transitionは、CSSプロパティの変更に対してのみ反応し、再生をおこないます。よくあるのは、:hover擬似クラスを用いてCSSプロパティの値を変更する方法です。

To use the example visualized here, if a transition is defined, you would be able to see the circle growing from its normal size to its hover size. Another way of triggering a transition is to use JavaScript to programmatically add or remove CSS classes to simulate a CSS property change. Rounding out our ways of making a property change, you can use JavaScript to set an inline style that changes a property your transition is listening for.

上記の例を使って説明をします。transitionを定義しているので、通常のサイズからホバーしたサイズへと、円が大きくなっていくことが確認できます。ホバー以外の方法としては、JSを使ったプログラミングによってCSSクラスを追加したりすることでCSSプロパティを変更する方法もあります。つまりJSを使ってインラインスタイルに、プロパティを変更するような変更を加えます。しかもtransitionが待ち構えているプロパティを変更します。(訳注:「transiton: width 2s」となっている要素に対して、widthを例えばjQueryを使って$(‘.target’).width(400)と指定すればアニメーションする。)

Animations, on the other hand, don’t require any explicit triggering. Once you define the animation, it will start playing automatically. Yep, that’s how animations roll!

Transitionに対して、Animationの場合は、トリガーを明示的に宣言する必要はありません。一度アニメーションを定義してしまえば、自動的に再生されます。

Looping

This is pretty simple. Animations can be easily made to loop by setting the animation-iteration-count property. You can specify a fixed number of times you want your animation to repeat:

この話題に関して結論は非常にシンプルです。Animationはanimation-iteration-countプロパティを使うことで、簡単にループを設定することができます。アニメーションを繰り返す回数を具体的な数字で指定することができます。

animation-iteration-count: 5;

If you just want your animation to loop forever, you can do that as well:

無限にループさせた場合は、次のようにすることで実現できます。

animation-iteration-count: infinite;

Transitions, on the other hand, don’t have a property that specifies how many times they can run. When triggered, a transition runs only once. You can make a transition loop by fiddling with the transitionEnd event, but that isn’t particularly straightforward – especially when compared with animations.

それに対してTransitionの場合には、繰り返し何回も再生するように指定するpropertyはありません。トリガーされると、トランジションは一度だけ実行されます。transitionをループさせることは、transitonEndイベントを扱うことで実現できますが、しかしそれはあまり正攻法ではありません。とくにAnimationと比べた場合にはかなり複雑な方法です。

Defining Intermediate Points / Keyframes

中間点の定義 / Keyframeの場合

With an animation, you have the ability to define keyframes which give you more control over your CSS property values beyond just the start and the end:

Animationの場合、keyframeの定義によって、CSSプロパティの値をよりコントロールすることができ、開始と終了以上の定義ができます。

You can set as many keyframes as you want, and when your animation plays, each keyframe will be hit with the specified property changes reflected. This allows you to create the kinds of involved animations that help HTML5 compete with more established animation technologies like Flash more effectively.

keyframeは望む数だけ、何個も設定できます。アニメーションがスタートすると、それぞれのkeyframeの位置で指定されたpropertyの変更が反映されます。これによってHTML5で、他の洗練されたFLashのようなアニメーション用のテクノロジーに、匹敵する効果を作り出すことができます。

With a transition, you don’t have much control over anything beyond the end result:

Transitionでは、最初と最後の指定以上の、複雑なコントロールはできません。

A transition simply goes from an initial state to the final state. You cannot specify any points in-between like you can with an animation, so a transition might not be a good choice if you are trying to create the next Teen Girl Squad sensation or a complex animation.

Transitionは単純に、初期状態から、最終的な状態へと、推移させることしかできません。keyframe animationのように、中間点を指定することはできないのです。なのでtransitonでは、Teen Girl Squadのような刺激的で複雑なアニメーションを作るのには向いていません。

Specifying Properties Up-Front

The next thing I will describe is how formal animations and transitions are when it comes to defining a transition between CSS property values.

次の話題は、どれくらい規則だった定義が、アニメーションにおいて必要か、という観点です。

On the formal side, you have transitions. Every CSS property you want recognized by your transition must be explicitly represented.

もし規則だった書き方をしたいのであれば、Transitionに軍配が上がるでしょう。Transitionに反応して欲しい全てのCSSプロパティを、明示的に書く必要があります。

For example, let’s say you have something like the following:

例えば、以下のようなコードを書いたとしましょう。

#mainContent { 
        background-color: #CC0000; 
        transition:background-color .5s ease-in; 
} 
#mainContent:hover { 
        cursor: pointer; 
        background-color: #000000; 
        width:500px;
}

Upon hover, I specify a different value for both background-color as well as width. My transition specifies only background-color though. This means your browser is only listening for changes on the background-color property.

hoverした場合には、通常時とは異なる2つのプロパティの値を指定しています。バックグランドカラーと幅です。ただし、Transitionではバックグランドカラーだけを指定しています。つまり、バックグラウンドカラーの変更だけを、監視することになります。

If I wanted my transition to affect both the background-color and width properties, I will need to explicitly add another transition entry for width:

もしバックグラウンドカラーとwidthの2つのプロパティをトランジションしたい場合には、明示的にwidthもtransitionに加える必要があります。

#mainContent { 
        background-color: #CC0000;
        transition:background-color .5s ease-in, width .5s ease-in 
} 
#mainContent:hover { 
        cursor: pointer; 
        background-color: #000000; 
        width: 500px;
}

What About transition: all?

全てのプロパティをトランジションする場合にはどうすればよいか

You do not have to specify every property that you care about when using a transition. You could simplify your life by using the all value instead: transition: all .5s ease-in. I do not recommend this because you will take a performance hit. Your browser is now listening for a whole lotta properties as opposed to just a few that you know you will be modifiying. Unless you have a strong need to do this, I would recommend specifying each CSS property you wish to transition individually.

Transitionを使う際に、全てのプロパティを明示的に指定する必要はありません。allという値を代わりに使えば、シンプルに全てのプロパティををトランジションさせることができます。「transition: all easein」といった具合です。とはいえ、これはあまりおすすめしません。何故ならパフォーマンスが下がるからです。こうした場合、ブラウザは沢山存在する全てのプロパティを監視するからです。それなのにあなたが変更するプロパティは少ししかありません。こうすべき強い必要性がない限りは、transitionさせたいプロパティをそれぞれ指定することをおすすめします。

With animations, you have the ability to specify properties at a whim in each keyframe without having to do anything that resembles declaring them:

Animationにおいては、以下のようにすればいいです。

keyframes imageSlide { 
        0% { 
                left: -150px;
        } 

        20% { 
                left: 50px; 
                height: 200px;
        } 

        80% { 
                left: 200px; 
                height:300px;
        } 

        100% { 
                left: 600px; 
                background-color:#FFFFFF;
        } 
}

In this example, the height and background-color of whatever element I am animating will smoothly transition when the appropriate keyframe is reached – even if the property was never listed before!

このように、適切なアニメーションが各keyframeで発動します。そために、前もって変更するプロパティのリストを作っておく必要はありません!

Interaction with JavaScript

In many cases, a transition or animation you declare in CSS will be good enough. You specify in CSS your starting value, the ending value, and any intermediate values that you want your properties to take. Your animation or transition will read these values and take care of business from there. This scenario works best when what you are wanting to do is predefined. There will be times when you want to alter the value of a property that you are animating based on some external input – a mouse click, the result of some calculation, etc.

多くの場合において、CSSで実装するtransitionやanimationといった機能は、それだけで十分な役割を果たしてくれます。CSSで開始時の値を定義して、終わりの値も定義して、そして中間点を定義して、といった具合に。AnimationやTransitionはそれらの値をしっかり読み取って、それぞれの地点で自分の仕事を遂行します。どうしたいかが事前に決まっている場合には、これで役割をしっかりとこなすことができます。しかし、値を、外部の入力値に基づいて、アニメーションを変更したい場合もあるでしょう。例えばマウスクリックや、ある種の計算の結果を使用する場合です。

For such interactions, property values entirely predefined in CSS is a bit limiting. You can decide in such cases to rely on JavaScript, but going all-in on JavaScript alone may be too extreme as well. What you want is a hybrid approach where your animation or transition is declared primarily in CSS but certain aspects of which are manipulated using JavaScript.

このようにインタラクションが必要な場合には、CSSに予め記述された値だけでは、できることが限定されてしまいます。そういった場合には、JSを使用することを検討すると思いますが、かといって全てJSだけで実装するのはやりすぎだというようなケースがあります。そういう場合には、CSSアニメーションとJSのハイブリッドというアプローチも選択肢に入るはずです。animationやtransitionで予め大部分をCSSにかいておいて、しかしある部分はJSで操作する、といった方法です。

When it comes to combining JavaScript with either an animation or transition, there is no contest – you almost always want to use a transition. Using an animation with JavaScript is possible…in much the same way it is possible to win at the cinnamon challenge. It isn’t impossible to make it work, but chances are, you don’t want to do it. The reason for this difference has to do with how transitions and animations work.

JSと組み合わせるという観点から言うと、はっきりいって勝負は見えています。ほとんどのケースでは、transitionを使うことになるでしょう。Animationを使う方法も無理ではないのですが、そうしようと思う機会はかなり少ないはずです。その理由は、transitionとanimationの挙動に違いがあるからなのです。

Animations are very specific in what they do. The @keyframes rule clearly lays out the path your animation will take as it is running. Attempting to change your animation in JavaScript requires a very complicated series of steps that involves actually modifying the @keyframes style rule itself. If you’ve ever had to manipulate CSS that lives inside a style rule, you know that it is pretty unintuitive.

Animationの場合は、何をするのかということをかなり具体的に定義します。@keyframeによってアニメーションがどのような状態を変遷していくのかを、明確に定義します。JSによってアニメーションを変更しようとすると、かなり複雑な作業が必要になります。@keyframesを書き換えないといけないからです。インラインで記述されたCSSをマニュピレイトしたことがある人ならわかると思いますが、これはかなり直感的ではありません。

Contrasting the predefined path of an animation is the transition. Transitions are not as well defined as they may seem. Your transition will kick in when a property it is listening for changes. This property change can be set entirely via only CSS:

Transitionの場合は、そこまで定義をしていません。トランジションは、待ち受けていたプロパティの変更があった場合に、開始されます。下記のコードではプロパティの変更はCSSの中でなされていますね。

#myElement {
        background-color: #FFF;
        transition: background-color .2s ease-in;
}
#myElement:hover {
        background-color: #000;
}

This change can also be accomplished via JavaScript where you modify a CSS property the transition is listening for by setting an inline style:

CSSプロパティの変更はJSからも可能です。インラインに書かれたトランジションが待ち受けるプロパティを、JSから変更しましょう。

var myElement = document.querySelector("#myElement");
myElement.style.backgroundColor = "333";

The transition doesn’t care how the properties it is listening for changes. As long as the property changes somehow, the transition will get to work. This means, for interactive scenarios that don’t involve a predefined starting and ending point, you can do a lot of interesting things by deferring all transition-related heavy lifting by using the transition declaration. The actual values of the properties you are wanting to transition can be specified using JavaScript.

transitionは、変更を監視しているプロパティがどんな方法で変更されるかは、まったく気にしていません。とにかくプロパティが変更されれば、Transitionが発動します。つまり、予め始まりと終わりが決まっていないインタラクティブなアニメーションを実装する場合に、transtionの対象になっているプロパティを変更することで、様々な面白い効果を得られる、ということです。望むプロパティの値をJSを使って指定することができます。

To help visualize what I just wrote, let’s look at a simple example:

Click anywhere in the gray box to have the circle move to the point of the click. Keep clicking around to see the circle keep moving.

灰色のboxの中でクリックすると、円がその場所に移動します。クリックして、円が移動するのを確認してください。

How this works is pretty simple. The actual movement is handled by the transition. Knowing where to transition to is handled by the JavaScript which sets the top and left property values on the element. Because the transition is listening for changes to the top and left properties, any change results in your transition kicking in. The end result is exactly what you wanted. Best of all, you didn’t have to write any JavaScript for handling the actual movement itself. As a bonus, because the transition is declared in CSS, your browser optimizes it heavily so that it runs really smoothly.

仕組みは非常に簡単です。実際の動きは、transitionによって実装されています。どこへ移動すべきなのか、ということはJSを使って制御されています。JSによってtranstionが監視している、leftプロパティとtopプロパティを変更しています。変更が発生すると、transitionが起動します。その結果希望する結果を実現しています。一番いいのはJSを全く書かないで実装する方法ではありますが。副次的な利点としてtranstionはCSSで宣言されているので、ブラウザーはパフォーマンスを最大化してくれ、結果として非常にスムーズに動きます。

This friendship between transitions and JavaScript is so full of win, it hurts just writing about.

transitionとjsの組み合わせは、非常に有効です。

Conclusion

There you have it – a candid look at what makes transitions and animations similar yet so very different. My general approach for determining when to use which goes like this:

TransitionとAnimationが基本的には似ていて、それでいて異なる部分もかなりある、ということをみてきました。どちらを使うべきなのか、ということに関しての私の選択基準は、以下の様なものです。

  • If what I want requires the flexibility provided by having multiple keyframes and easy looping, then I go with an animation.
  • keyframeと簡単に実装できるループによる柔軟性が欲しいときは、animationを選択します。
  • If I am looking for a simple from/to animation, I go with a transition.
  • シンプルに、開始と終了を設定するアニメーションを実装した場合にはtransitionを選択します。
  • If I want to manipulate the property values that I wish to animate using JavaScript, I go with a transition.
  • JSでプロパティの値を操作したい場合には、Transitionを選択します。

Now, with enough effort and JavaScript tomfoolery, you can neutralize any deficiences I list in deciding whether to use a transition or an animation. My recommendations are based on the common cases where you take a transition or animation mostly at face value. Herculean efforts to change their default behavior is admirable but often unnecessary.

もちろんJSで色々とがんばれば、どちらの機能を選択するか、を検討する際にあげたそれぞれの欠点を埋め合わせることはできます。しかし、一般的なケースにおいては上記のような選択をするのが普通でしょう。必死の努力によってこれら二つの機能の基本的な振る舞いを変更することはできますし、それは賞賛に値するのかもしれませんが、意味はありません。

日本語訳: Presentational and Container Components

勝手に翻訳シリーズ

元の記事

https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0

Presentational and Container Components

Bismuth
There’s a simple pattern I find immensely useful when writing React applications. If you’ve been doing React for a while, you have probably already discovered it. This article explains it well, but I want to add a few more points.
とても有益でシンプルなパターンを、Reactを書いているときに見つけました。もちろんあなたもReactをある程度書いたことがあれば、多分同じようなことを既に発見されていることでしょう。Thisこの記事も同じことについて説明しています。ですが、さらにいくつか新しいことを紹介できるとおもいます。
You’ll find your components much easier to reuse and reason about if you divide them into two categories. I call them Container and Presentational components* but I also heard Fat and SkinnySmart and Dumb, Stateful and PureScreens and Components, etc. These all are not exactly the same, but the core idea is similar.

ご存知だと思いますが、コンポーネントをうまく再利用するためには、そしてうまく整理するためには、コンポーネントを2種類に切り分けると良いのです。その二つを私はContainer ComponentとPresentational Componentと名付けることにしました。ですが人によってはFatとSkinny、SmartとDumb、StatefulとPure、ScreensとComponentsと、様々な呼び方をしています。これらは全てが完全に同じものではありませんが、中心的な役割は同じです。

My presentational components:

私がPresentationalと名付けたコンポーネントの特徴は以下の通りです。

  • Are concerned with how things look.
  • どのような見た目になるか、ということと関連づいている
  • May contain both presentational and container components** inside, and usually have some DOM markup and styles of their own.
  • PresentatinalコンポーネントとContainerコンポーネントの両方を内部に持つことができ、たいていの場合は自分自身のためのDOMマークアップとスタイルを持つ。
  • Often allow containment via this.props.children.
  • たいていの場合は、コンテンツをthis.props.childrenを用いて保持している。(訳注:公式参照 コンポーネントの<Component>ここ<Component>ここの部分入れらたものがthis.props.childrenで参照できる部分。通常、これは自動的にレンダリング時に参照され、内部で保持され、表示される。)
  • Have no dependencies on the rest of the app, such as Flux actions or stores.
  • アプリケーションの他の部分に対して依存している部分が一切ない。例えばFluxのactionやstoreに依存している部分がない。
  • Don’t specify how the data is loaded or mutated.
  • dataがどのようにロードされるか、もしくは変更されるか、といったことは定義しない。
  • Receive data and callbacks exclusively via props.
  • dataやコールバックは外部からprops経由で受け取る。
  • Rarely have their own state (when they do, it’s UI state rather than data).
  • 独自の状態を保つことは基本的にはない。(あるとすれば、UIの状態を持つ場合であってDateではない。)
  • Are written as functional components unless they need state, lifecycle hooks, or performance optimizations.
  • Functional コンポーネントとしてかかれる。状態やライフサイクルフック、パフォーマンス調整が必要とされない限りは。
  • Examples: Page, Sidebar, Story, UserInfo, List.
  • 例としては、Page, Sidebar, Story, UserInfo, Listなどがあげられる。

My container components:

私がContainerと名付けたコンポーネントの特徴は以下の通りです。

  • Are concerned with how things work.
  • どのように機能するか、ということと結びついてる。
  • May contain both presentational and container components** inside but usually don’t have any DOM markup of their own except for some wrapping divs, and never have any styles.
  • PresentatinalコンポーネントとContainerコンポーネントの両方を内部に持つことができるが、たいていの場合は自分自身のためのDOMマークアップとスタイルを「持たない」。
  • Provide the data and behavior to presentational or other container components.
  • データと挙動を、Presentationalコンポーネントや、他のContainerコンポーネントに対して提供する。
  • Call Flux actions and provide these as callbacks to the presentational components.
  • Fluxのアクションをcallしたり、アクションをコールバックとしてPresentatinalコンポーネンへ提供する。
  • Are often stateful, as they tend to serve as data sources.
  • たいていの場合は状態を持ち、データの源としての役割を担う。
  • Are usually generated using higher order components such as connect()from React Redux, createContainer() from Relay, or Container.create() from Flux Utils, rather than written by hand.
  • higher order componentを用いることで生成される。例えばReact Reduxのconnect()やRelayのcreateContainer()やFlux UtilsのContainerCreate()である。
  • Examples: UserPage, FollowersSidebar, StoryContainer, FollowedUserList.

I put them in different folders to make this distinction clear.

私はこの二つのコンポーネントを、異なるフォルダーに配置することで、明確に区別することにしています。

(訳注:ということは、Reduxのconnect()を使う層は、基本的にContainer Component。connectはなぜ使うかといえば、state,reducer,actionとpresentationalコンポーネントを、Containerコンポーネント内で結びつけるため。presentationalコンポーネントとactionをロードして、connectでstate,dispatchと結びつける。するとpresentationalコンポーネントにstate,dispatchが渡されるので、presentationalコンポーネントがそれを使えるようになる。connectで結びつけて作った新しい高次階層コンポーネントをexportし、これを他のコンポーネントから呼び出して使う。)

Benefits of This Approach

このアプローチの利点

  • Better separation of concerns. You understand your app and your UI better by writing components this way.
  • 役割の分割をうまくできる。コンポーネントをこう書くことで、アプリケーションとUIがどうなっているのか、より理解しやすくなる。
  • Better reusability. You can use the same presentational component with completely different state sources, and turn those into separate container components that can be further reused.
  • 使い回しが効く。Presentationalコンポーネントを全く異なるStateを持つ状況において使用することができる。また異なるContainerコンポーネントの中で使用することができる。
  • Presentational components are essentially your app’s “palette”. You can put them on a single page and let the designer tweak all their variations without touching the app’s logic. You can run screenshot regression tests on that page.
  • Presentatinalコンポーネントは、本質的にはアプリケーションの「パレット」である。ページのどこにでも配置することができ、デザイナーがアプリのロジックに触ることなく変更することができる。
  • This forces you to extract “layout components” such as Sidebar, Page, ContextMenu and use this.props.children instead of duplicating the same markup and layout in several container components.
  • こうすることで「layout Component」を強制的に取り除くことになるので、同じマークアップやレイアウトを様々なContainerコンポーネントになんども複製する必要がなくなる。this.props.childrenを使えばいい。

Remember, components don’t have to emit DOM. They only need to provide composition boundaries between UI concerns.

コンポーネントは必ずしもDOMを出力する必要はない、という点に注意してください。第一の役割は、コンポジションにおける境界を定義することにあります。

Take advantage of that.

どの段階でContainerを導入すべきか

When to Introduce Containers?

I suggest you to start building your app with just presentational components first. Eventually you’ll realize that you are passing too many props down the intermediate components. When you notice that some components don’t use the props they receive but merely forward them down and you have to rewire all those intermediate components any time the children need more data, it’s a good time to introduce some container components. This way you can get the data and the behavior props to the leaf components without burdening the unrelated components in the middle of the tree.

まずはPresentationalコンポーネントだけでAppを書き始めることをお勧めします。そうしていくと、最終的には、あまりに多くのpropsを中間層のコンポーネントに渡している、と感じることにはなると思います。propsを受け取ってはいるものの、用いておらず、単にさらに下部のコンポーネントへと渡しているだけのコンポーネントがあるような状況が生まれた場合が、Containerコンポーネントを導入するのに最適な段階でしょう。そうすれば、データや挙動のためのpropsを各コンポーネントに与えるために、関係のないコンポーネントを中間層に挟む必要がなくなります。

This is an ongoing process of refactoring so don’t try to get it right the first time. As you experiment with this pattern, you will develop an intuitive sense for when it’s time to extract some containers, just like you know when it’s time to extract a function. My free Redux Egghead series might help you with that too!

これはリファクタリンの際に継続的におこなうことなので、最初から行う必要はありません。このパターンで書く際に経験していることだと思いますが、いつコンテイナーを導入するのかということを感じ取るセンスを育む必要があります。これはちょうど、どの段階でFunctionにまとめるべきなのかを判断するセンスと似ています。 free Redux Egghead series も参考になるはず!

他の違い

Other Dichotomies

It’s important that you understand that the distinction between the presentational components and the containers is not a technical one. Rather, it is a distinction in their purpose.

presentationalコンポーネントとcontainerコンポーネントの違いは、技術的なものというよりは、その目的による、という点を理解することが重要です。

By contrast, here are a few related (but different!) technical distinctions:

  • Stateful and Stateless. Some components use React setState() method and some don’t. While container components tend to be stateful and presentational components tend to be stateless, this is not a hard rule. Presentational components can be stateful, and containers can be stateless too.
  • Stateful and Stateless.  ReactのsetState()を使うコンポーネントもあれば、使わないコンポーネントもあります。ContainerコンポーネントはStateを持つ傾向にあり、Presentationalコンポーネントがstateを持たない傾向にありますが、とはいえこれは厳密なルールではありません。Presentationalコンポーネントがstateを持つこともありますし、ContainerコンポーネントがStateを持たないこともあります。
  • Classes and Functions. Since React 0.14, components can be declared both as classes and as functions. Functional components are simpler to define but they lack certain features currently available only to class components. Some of these restrictions may go away in the future but they exist today. Because functional components are easier to understand, I suggest you to use them unless you need state, lifecycle hooks, or performance optimizations, which are only available to the class components at this time.
  • Classes and Functions. React 0.14から、コンポーネントはクラスとしてもファンクションとしても宣言できるようになりました。ファンクショナルコンポーネントは宣言がよりシンプルですが、クラスコンポーネントにしかない機能を持っていません。そういった制限が将来撤廃されるかもしれませんが、今のところは存在します。ファンクショナルコンポーネントは把握するのが簡単ですので、ステイト/ライフサイクルフック/パフォーマンスの調整といったクラスコンポーネントだけにしかない機能が必要でない場合には、ファンクショナルコンポーネントを使うことを推奨します。
  • Pure and Impure. People say that a component is pure if it is guaranteed to return the same result given the same props and state. Pure components can be defined both as classes and functions, and can be both stateful and stateless. Another important aspect of pure components is that they don’t rely on deep mutations in props or state, so their rendering performance can be optimized by a shallow comparison in their shouldComponentUpdate() hook. Currently only classes can define shouldComponentUpdate() but that may change in the future.
  • Pure and Impure. コンポーネントのうち、同じpropsと状態を与えれば、同じ結果を返すものを、Pureコンポーネント、と言ったりします。ピュアコンポーネントは、クラスでもファンクションでもどちらでも定義することができます。またステイトを持つことも持たないこともできます。(残りの部分わからず)

Both presentational components and containers can fall into either of those buckets. In my experience, presentational components tend to be stateless pure functions, and containers tend to be stateful pure classes. However this is not a rule but an observation, and I’ve seen the exact opposite cases that made sense in specific circumstances.

PresentationalコンポーネントもContainerコンポーネントも、そうではないもう一方のコンポーネントになる可能性が常にあります。私の経験では、Presentatinalコンポーネントはstatelessなピュアファンクションであり、Containerコンポーネントはstateを持つピュアクラスであることが多いようです。とはいえこれはルールではなくて、あくまでもそういうことが多いというだけなので、過去には全くの反対のケースで、しかも合理的、という状況もありました。

Don’t take the presentational and container component separation as a dogma. Sometimes it doesn’t matter or it’s hard to draw the line. If you feel unsure about whether a specific component should be presentational or a container, it might be too early to decide. Don’t sweat it!

PresentationalコンポーネントとContainerコンポーネントの区別を、教義のように考えないようにしてください。時にはそんなことを考える必要がない時もありますし、区別をすることが難しい場合もあります。どちらにすべきか確信が持てない場合には、それを決断するにはまだ早いのかもしれません。そんなことは気にしないで!

Example

This gist by Michael Chan pretty much nails it.

Further Reading

Node-REDの基本的なノード:MQTT,JSON,Websocket,TCP等

Node-RED: Lecture 3 – Basic nodes and flows

In this lecture you will get to see a few of the more commonly used nodes and build on some of the things you learnt in previous lectures. You’ll start off with a series of examples based around the popular MQTT protocol that shows how to wire together a set of basic but very useful message processing nodes. Then you’ll briefly look at other ways to get messages into and out of your flows using protocols such as TCP, UDP and websockets.

このレクチャーでは、いくつか一般的に使われるノードの紹介と、既に以前のレクチャーで紹介したものの詳細については触れていなかったものを再度取り上げます。まずはよく知られたMQTTプロトコルに基づいたサンプルから始めていきます。これによって、基本的な、しかしとても便利なメッセージ処理をするノードを、どのようにつなげていいかがわかるはずです。次に、メッセージを取り込んだり出力するための他の方法として、TCPやUDPやwebsocketといったプロトコルの扱い方もとりあげます。

At the end of this lecture you will have a better understanding of some of the basic nodes used in Node-Red flows. You will also have seen how easy it is to build sophisticated processing flows that take real-world events, process them and generate responses that use popular Internet protocols to communicate the results outside of your flow.

このレクチャーが終わる頃には、Node-REDフローに用いられる基本的なノードの理解ができることでしょう。また洗練された処理のためのフローが、如何に簡単につくれるかということも理解できるはずです。現実世界のイベントを取得して、それを処理し、返答を生成して、インターネット上の一般的なプロトコルを用いて、フローの外の世界と通信します。

We use a cloud hosted version of Node-RED for these lectures called FRED. Sign up for a free account at FRED. Examples in the early lectures will work with other installations of Node-RED, later lectures use nodes you will need to install yourself if you don’t use FRED.

例によってFREDを使っていきます。

Examples

Example 3.1 Receiving JSON via an MQTT message

Example 3.2 Using the switch node to handle a JSON object

Example 3.3 Using a change node to change or manipulate a message payload

Example 3.4 Using the rbe (report by exception) node

Example 3.5 Scaling input with the range node

Example 3.6 Using an mqtt output node to test the flow

Example 3.7 Using Websockets with Node-RED

Example 3.8 Sending TCP requests.

例3.1 MQTTメッセージを介してJSONを受け取る

Example 3.1 Receiving JSON via an MQTT message

The following series of examples builds on the mqtt node, which provides a convenient way to take input from an MQTT broker. For those not familiar with MQTT, it is an example of a publish/subscribe system (usually shortened to pub/sub system) which lets sensors publish updates that all delivered to client subscribed to that sensor. MQTT uses a topic model allowing publishers (eg sensors) to create topics and publish data to the topics Equally, others can subscribe to a topic and will receive asynchronous notification of data posted to the topic.

これから続く一連のサンプルは、MQTTノードを構築していきます。MQTTノードはMQTTブローカーからの入力を簡単に取得する方法を提供します。MQTTについてあまり馴染みのない人のために説明をすると(訳注:次の日本語の記事がわかりやすかったので参照)、これはpublish /subscribeシステムを持ち、sensorたちに更新をpublishさせ、そのsensorをsubscribeしているクライアントに、その情報を届ける仕組みです。MQTTはトピックモデルによって運用され、パブリッシャー(sensor)にトピックをたて、トピックをpublishし、パブリッシャー以外はそのトピックをsubscribeして、そのトピックへポストされたデータを非同期に受け取ります。(訳注:ちょっと翻訳変ですけど、pulishとかtopicとかはもうそのまま用語を理解したほうが早いと思うので、そのままで)

Pub/Sub systems are a great way to connect loosely coupled distributed systems and they map well to typical IoT patterns where devices or things generate events that you want to share. The MQTT protocol, apart from being asynchronous, is also lightweight and doesn’t have as high an overhead as HTTP; which for resource-constrained devices is often an important advantage. MQTT was originally developed in the late 1990s and has been used in a variety of IoT settings. MQTT became an OASIS standard in 2014 and is a standard part of many IoT toolboxes. MQTT actually stands for Message Queueing Telemetry Transport.

Pub/Subシステムは、ゆるく連結した分散型のシステムをつなぐためにとてもいい方法です。またこのシステムは典型的なIoTで用いられるパターンにマッチしていて、デバイスやThingsがイベントを生成し、それを他のデバイスやThingsと共有するような場合に向いています。MQTTプロトコルは、非同期であることを除けば、軽量で、HTTPよりも負荷が低いです。これは、リソースが限られたデバイスにとっては、重要な利点です。MTQQは元々1990年代後半に開発され、それ以来様々なIoTにおいて使われてきました。MQTTはOASISとして2014年に標準化され、IoTで使用される規格としては標準的なものとなっています。MQTTはMessage Queueing Telemetry Transportの略記です。

To use the mqtt node, you need to have access to a broker. There are a number of free MQTT servers running, for example http://test.mosquitto.org/, or the one that will be used in this lecture, www.hivemq.com. Using the broker address and the topic, you can configure the mqtt input node to subscribe on that topic, causing it to generate a new message whenever new data is published on that topic. The message will contain information on the published data, including the data itself in msg.payload and the MQTT broker topic in msg.topic.

MQTTノードを使うためには、Brokerにアクセスする必要があります。フリーのMQTTサーバーがいくつもあり、たとえばhttp://test.mosquitto.org/や、このレクチャーで使うwww.hivemq.comなどがあります。Brokerアドレスと、topicを使うことで、MQTTインプットノードを、そのトピックをサブスクライブし、そのトピックでpublishがされた際に、新しいメッセージを生成させることにしましょう。そのmessageはpublishされたデータに関する情報を含み、データはmsg.playloadに、MQTTブローカーのtopicはmsg.topicに含まれています。

To get you started with the mqtt node, you’ll be using the free mqqt broker hivemq – which is available via (http://www.hivemq.com/showcase/public-mqtt-broker/). Of course you can use any MQTT broker, including your own, if you have installed one.

MQTTノードを使うために、MQTTブローカーであるhivemqを使います。もちろん他のどのMQTTブローカーを使うこともできます。例えば自分でインストールしたサーバーを使うこともできます。

First, drag and drop an mqtt input node and configure it for the broker. Don’t forget to configure the topic to something unique, in the case of this example we are using noderedlecture/sensor but you should use your own unique topic, i.e. <your name here>/sensor

まずはいつも通りMQTTインプットノードをドラッグ・アンド・ドロップでは位置して、設定画面からborkerのための情報を入力しましょう。大事なことは他の人とかぶらないtopic名を設定することです。例えばこの例ではnoderedlecture/sensorというトピックたて使用していますが、あなたはそれとは違う名前のトピックを建てるようにしてください。例えば 自分の名前/sensorとか、ですね。

(訳注:よくわからないが、とにかくトピックと、サーバーだけ同じにしておけば、受信できる模様。ポートとかクライアントIDは異なっていても受信できる。)

Figure 3.1 Configuring the mqtt node with broker address and topic

 

There are many ways you can send mqtt messages to hivemq. You can use their websockets client showcase (http://www.hivemq.com/demos/websocket-client/), the mqtt dashboard (http://www.mqtt-dashboard.com/dashboard) or your own library. You’ll be using their websocket client in this example, so navigate to that page and connect to the broker. You will publish a JSON encoded string to the topic you configured to see both the use of the mqtt node and the json node.

MQTTメッセージをhivemqに送る方法はたくさんあります。上の2つのリンクは、公式が提供しているものでこれを使うこともできますし、自分でライブラリをつくってもいいでしょう。このサンプルでは、上記のリンクのうち、最初のもの、WebSokcetクライアントをつかっていくことにします。

Figure 3.2 Sending an MQTT message (publishing) using the HiveMQ client page.

Since you are sending a JSON string, you will need to parse the message that the mqtt node generates when it receives the MQTT message. To do that, you’ll need to drag and drop a json node and connect it to the mqtt node’s output.

ここではJSON形式の文字列を送っているので、MQTTノードが受け取って、そして生成したメッセージをパースする必要があります。そのためにJSONノードを配置し、MQTTノードのアウトプットをこれに入力します。

Node-RED’s json node is a sort of convenience function, in that it parses the incoming message and tries to convert it to/from JSON. So if you send it a JSON string, it will convert it to a JavaScript object, and vice versa.

Node-REDのJSONノードは、JSONを変換してJSオブジェクトに変換してくれますし、またその反対もできます。

If you wire up the usual debug node to the json node and deploy, then use the HiveMQ dashboard to send the JSON string {“analyze”:false, “value”:10} as shown in Fig 3.2. You will see it printing in the debug tab (Fig 3.3).

結線して、debugノードをつかってみましょう。ディプロイした後にHiveMQダッシュボードを使ってJSON文字列を送りましょう。するとdebug窓で確認できます。

 

Figure 3.3 Receiving and parsing an MQTT message sent as a JSON string

If you look closely at the output, you can see that the msg.payload contains an object, which itself has two fields, analyze and value, each with their own values. As you saw in lecture 2, you can access these fields via msg.payload.analyze and msg.payload.value. Let’s take a look at a node that can do that.

Outputの内容をより詳細にみてみると、msg.payloadはオブジェクトをもっていることがわかります。そのオブジェクトは、2つのフィールドを持ち、1つはanalyzeでもう一つはvalueで、それぞれそのフィールドに対応する値を持っています。レクチャー2でみたように、これらのフィールドにmsg.payload.analyzeでアクセスすることができます。やってみましょう。

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson3/3-1_mqqtmessages.json

例3.2 スイッチノードを使って、JSONオブジェクトを扱う

Example 3.2 Using the switch node to handle a JSON object

One of the nice features of having a JSON object is that you can easily act on its properties. A useful node for this is the switch node. Its role is to ‘switch’ or route messages depending on the incoming message properties.  For example, you can check the msg.payload.analyze property and, depending on its value (true/false), decide to route a message to one of the switch node’s outputs.

JSONオブジェクトをもちいる利点の一つは、そのプロパティに簡単にアクセスできることです。そのために便利なのは、Switchノードです。このノードは、入力されたメッセージのプロパティの値によって、スイッチングし、その経路にメッセージを送ります。例えば、msg.payload.analyzeプロパティをチェックして、その値によって(tureかfalse)switchノードのいずれかのアウトプットにメッセージを送ります。

Drag a switch node and double-click on it. Configure it to evaluate the property “msg.payload.analyze”. If true, send the message to the first output; if false, send it to the second output as shown in in Fig 3.4.

switchノードをいつも通りドラッグ・アンド・ドロップして配置して、ダブルクリックして設定画面に入りましょう。そしてmsg.payload.analyzeプロパティを評価するように設定します。もしこの値がtrueであれば1st Outputに出力します。falseだった場合には、2nd Outputから出力します。

Figure 3.4 Configuring the switch node to route based on a message property

Now you can connect two debug nodes as shown in Fig 3.5 – when you set up multiple outputs for a node, they are numbered from the top, so output 1 is the top output and output 2 is at the bottom in  Fig. 3.5.

次の図では2つのdebugノードにswitchノードのアウトプットをつなぎました。switchノードに複数のアウトプットを設定した場合には、上から順番にアウトプットの番号がつけられます。ですからFig.3.5ではoutput1が一番上にあって、その下にあるのがoutput2です。

 

Figure 3.5 Connecting a switch node to two debug nodes

If you now go back to the HiveMQ input page and send the MQTT message {“analyze”:true, “value”:6}, you will see that the first (top) output is activated and the incoming messages is routed, or ‘switched’, to output 1. If you send the original message {“analyze”:false, “value”:10}, the switch node will activate output 2 and the original debug node will fire. Hovering the pointer over the debug message will show which debug node is printing out the message as shown in Fig. 3.6.

さきほど作成したHiveMQを受け取るフローを少し修正してSwitchノードを使ってみましょう。MQTTメッセージの内容が{“analyze”:true, “value”:6}の場合には、1st Outputが有効になり、ここに入力されたメッセージが出力されます。反対に、{“analyze”:false, “value”:10}を送った場合にはOutput2が有効になり、下のデバグノードがメッセージを受け取ります。デバグ窓でデバグメッセージにマウスを重ねると、どのデバグノードがメッセージを出力されたかを示してくれます。

Figure 3.6 Confirming the operation of the switch node

As you can see, this provides you with a built-in Node-RED node that allows you to quickly determine the contents of incoming messages and direct the message through to different parts of the flow depending on the input.

このノードを使えば、入力されたメッセージの値に基づいて、フローの異なる場所へメッセージを流していくことができます。

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson3/3-2_switchnode.json

例3.3 Chageノードを使って、メッセージを変更する。もしくは単にメッセージを扱う。

Example 3.3 Using a change node to change or manipulate a message payload

Another useful node is the change node, which will allow you to change a message payload or add new properties. You can use this node to affect the properties in a message, either by changing existing ones, deleting them or adding new properties.

どんどん便利なノードを紹介していきましょう。今回はChangeノードです。これをつかえばmessageのpayloadを変更したり、新しいプロパティを追加することができます。既にあるプロパティを変更したり、削除したり、加えたりすることができます。

In this example, you’ll continue with your MQTT theme and see how, now that you have successfully ‘switched’ the message flow based on the incoming MQTT message, you can add a new message property msg.payload.note.

次の例はさきほどから使用しているMQTTフローをそのまま使用、追加していきます。これは入力されたメッセージによってスイッチするものでしたが、さらにこれに新しいmessageプロパティであるmsg.payload.noteを追加することにしましょう。

First, let’s drag and drop a change node and connect it to the second output of the switch node (Fig 3.7). As you will remember, this is the output that fires when msg.payload.analyze is set to false.

Changeノードをドラッグ・アンド・ドロップして追加し、switchノードの2nd Outputに接続してください。このアウトプットには、msg.payload.analyzeがfalseのときにだけ、メッセージが届きますね。

Figure 3.7 Adding in a change node to set a new message property.

 

Now configure it to set the property msg.payload.note to “this is not being analyzed” as shown in Fig 3.8.

では設定していきましょう。msg.payload.noteプロパティを“this is not being analyzed”に設定します

 

Figure 3.8 Using a change node to add a new message property

 

When you receive a message that the switch node sends on the 2nd output, it will be modified to contain a “note” element with the string “this is not being analyzed”. If you deploy and test the flow by sending the MQTT message from HiveMQ, you’ll see the output as shown in Fig 3.9.

メッセージを受け取ってその内容がswitchノードのoutput2に出力されるものであれば、メッセージは変更されて、noteエレメントを持ち、内容が“this is not being analyzed”という文字列のものが追加されます。

 

Figure 3.9 The result of switching and then changing the message

 

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson3/3-3_changenode.json

例3.4 rbe (report by exception-例外報告?)を使う

Example 3.4 Using the rbe (report by exception) node

In this example, you’ll continue your message analysis theme and add nodes to the part of the flow that is used when you determine that the flow should be analyzed. You’ll be using the rbe (report by exception) node which only passes on data if it has changed. You can set it to examine a message payload and either block until a message changes (rbe mode) or when a messages changes by a specified amount (deadband mode). In rbe mode, it works on numbers and strings. In deadband mode, it works on numbers only and uses the configured deadband as a + or – ‘band’, so that the incoming value can fluctuate within a range before it fires.

次の例でも引き続き、さきほどのものを使っていきます。今回追加するのはRBEノードで、これを使うことで値が変更されたときだけ、メッセージを通すことができます。messageのpayloadを検査して、メッセージが変更されるまでブロックしたり(rbaモード)、メッセージの変更が特定の範囲の間にだけ機能するようにすることができます。(deadbandモード) rbaモードでは、数字に対しても文字列に対しても動作します。deadbandモードにおいては、数字にたいして動作し、その値の範囲設定は、最後に発火したときの値から、どれくらいの範囲なのかで指定することができます。

You’ll start by adding in another change node which you’ll connect to output 1 of the switch node. You’ll then connect an rbe node to the switch node as shown in Fig 3.10.

下の図のようにつないでください。

Let’s connect a change node, and an rbe node like this. To remind us that this output deals with the flag “analyze”, add a comment node and write “Analyze = true”. Comments are useful when writing complex flows.

コメントノードを使うと、複雑なものに対して説明がつけられるので便利です。

Figure 3.10 Adding an rbe node to check if our input data has changed by more than 20%

Edit the change node to set the msg.payload to msg.payload.value. This will set the output of this node to the value found in the msg.payload.value element of the input received (Fig 3.11).

changeノードを変更して、msg.payloadに対してmsg.payload.valueを与えるようにしましょう。こうすることで、このノードのoutputを、インプットから受け取ったmsg.payload.valueの値に変更することになります。

Figure 3.11 Using a change node to set payload

Since you want to determine if this value has changed by 20% or more, you’ll need to double-click on the rbe node and configure it to block unless the value changes by more than 20%.

値の変化が20%以上のときにだけ反応するように設定しましょう。20%以上の変更がない場合には、ブロックする、という設定にします。

Fig 3.12 Setting the rbe node to check msg.payload.value

To test the flow, deploy this flow and then return to the HiveMQ page and send a series of messages. Firstly, you’ll need to set the analyze value to true so that the switch node sends through a message on output 1. If you use the original message value of 6, this will fail to pass the rbe node. If you then send a second message of value 10, the rbe node will evaluate the difference between 6 and 10, see it is greater than 20%, and send on a message to the final debug node which will print on the debug pane as shown in Fig 3.13.

ではHiveMQのページにいってメッセージを送り、このフローをテストしてみましょう。まず最初に、送るメッセージのanalyzeプロパティの値をtrueにし、スイッチノードがOutput1にスイッチするようにしましょう。最初にvalue:6をおくると、rbeノードを通りません。次に、value:10を送ると、rbeノードは先程の6と今回の10の差を比較して、それが20%以上あれば、debugノードへと値を送ります。そしてその値がdebug窓に表示されます。

Fig 3.13 Confirming that 10 is more than 20% larger than 6 using an rbe node.

 

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson3/3-4_rbenode.json

例3.5 インプットを特定の範囲にスケーリングするnode

Example 3.5 Scaling input with the range node

When dealing with real world input from sensors and other devices, an ability to scale input data is often required. Node-RED provides the scale node to support this and allows you to scale (linearly) an input value. Let’s assume you want to scale your value (originally in the range 0-10) to a range (0-255) when you aren’t doing any analysis. This means we are dealing with the lower part of the flow fired when the switch node evaluates the Analyze property as false.

実世界の入力を、例えばセンサーといったデバイスから受け取って処理する場合には、インプットされたデータをスケーリングする機能はよく必要になります。Node-REDはscaleノードを提供し、これをサポートしています。仮に0〜10の値を0から255の値にしたいが、自分ではわざわざ分析をしたくはない、という状況があるとしましょう。今回は、analyzeプロパティがfalseの時に発火する、フローの下側の部分を扱います。

To do this, select the change node you configured above (set msg.payload) and copy it with ctrl+c, then ctrl+v. Attach a range node as shown in Fig 3.14.

次のように変更してください。コピペコマンドも普通に使えます。

 

 

Figure 3.14 Scaling input values using the range node.

Double-click on it, and configure it to map the input from 0-10 to 0-255 as shown in Fig 3.15.

Rangeノードをダブルクリックして編集していきましょう。inputを0-10の範囲を0-255に対応するようにアウトプットします。

The scale node has three options set by the action field. The default will scale according to the mapping given but will happily scale values outside the given ranges, using the same mapping. Scale and limit to target range means that the result will never be outside the range specified within the result range. A third option, Scale and wrap within the target range means that the result will essentially be a “modulo-style” wrap-around within the result range.

スケールノードには3つのオプションがあります。デフォルトでは、与えられたマッピング範囲によってスケーリングをするのですが、その際に、与えられた範囲外の値も同じように処理をします。Scale and limit to target rangeは同じようにスケーリングをするのですが、その出力結果は、result rangeからは決して外れません。3つめのScale and wrap within the target rangeは、数学の「割り算の余り」スタイルで、result レンジの中で折り返します。

Then return to the HiveMQ test page and post {“analyze”:false, “value”:10} as a new MQTT message to the same topic.

ではHiveMQのテストページにいって、 {“analyze”:false, “value”:10}と新しいメッセージを、さきほどと同じトピックにポストしましょう。

Figure 3.15 Setting the scaling ranges for input and output of the scale node

If you return to your Node-RED window, you will see that the debug node associated with the lower part of the flow has fired, showing that the msg.payload.value property that you set as 10 when you published it to MQTT, has been scaled up 255 as shown in Fig 3.16.

ではNode-REDウィンドウに戻って、フローの下側と関連付けられたdebugノードが発火し、msg.payload.valueプロパティが示されていますね。MQTTで10の値をパブリッシュしたわけですが、これがスケーリングされて255という値になっています。

Figure 3.16 Final scaled output when analysis is turned off

 

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson3/3-5_rangenode.json

MQTTアウトプットノードを使って、フローをテストする

Example 3.6 Using an mqtt output node to test the flow

As an alternative to using the HiveMQ test page to publish on the MQTT topic, we can configure an mqtt output node. This is the mirror of the mqtt input node and allows you to configure an MQTT service and the topic you are publishing on. You can then send the node messages with the exact same JSON string we’ve been sending via the HiveMQ test page.

HiveMQのテストページを使ってMQTTトピックを発行する以外に、MQTTアウトプットノードを使う方法もあります。これはMQTTインプットノードとついになるもので、MQTTサービスを使う設定をし、そこで発行するトピックの設定もします。これによって今までHiveMQテストページで送信してきたようなJSON文字列のメッセージを送信することができます。

To try that, drag and drop three inject nodes and an mqtt output node as shown in Fig 3.17, and configure and wire up as shown

やってみましょう。

Figure 3.17 using an mqtt node to publish on the noderedlecture/sensor topic

You can now test the flow you created to analyze the MQTT message directly from the workspace by clicking on the three inject nodes in sequence. The first will exercise the part of the flow handling the case when analysis is turned off; the 2nd two messages will cause the path with the rbe node to be exercised.

インジェクトノードの左側のボタンをおしてMQTTメッセージを送信し、テストしてみましょう。

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson3/3-6_mqqtout.json

訳注:細かい設定方法が書いてなかったので、自分が設定したものを画像でのせます。

まずはinjectノードで文字列をフローに挿入します。Json形式で記録。

次にMQTT アウトノードの設定です。サーバーを先程受信していたものと同じにしました。トピックも。

MQTTインプットは、アウトプットと同じにします。当然トピックも同じにします。

例3.7 ウェブソケットをNode-REDで使う

上手く行かなかったので、パス。

Example 3.7 Using Websockets with Node-RED

Websockets are another useful communication capability that is built into Node-RED via the the websocket node. Websockets provide a duplex TCP connection and were designed to allow web browsers and servers to maintain a ‘backchannel’ that could be used to augment traditional HTTP interactions, allowing servers to update web pages without the client making a new pull request.

Websocketも便利なコミュニケーションのために使える機能で、Node-REDではwebsocketノードを使って実装できます。Websocketは双方向通信可能なTCP接続で、ウェブブラウザとサーバが?

The websocket node comes in two flavours, input and output, allowing you to listen for incoming data (input) or to send (output) on a websocket. The output version is designed to check to see if the output payload originated at a websocket in a node, in which case it responds to the original sender. Otherwise it will broadcast the payload to all connected websockets.

Websocketノードは、inputとoutputの二種類があり、ウェブソケットの入力をまったり、送信したりすることができます。Outputのほうは、?

In addition, both input and output websocket nodes can be configured as either server or client – in server mode they ‘listen on’ a URL, and in client mode they connect to a specified IP address.

To see how the websocket nodes work, you’ll use a public websockets echo server which runs on the public site: (https://www.websocket.org/echo.html).

Drag an inject, websocket in, websocket out and a debug node onto the workspace and connect them as shown in figure 3.18.

Figure 3.18 using websockets to communicate with a Node-RED flow

Configure the inject node to send a string payload of “Hello There” (Fig 3.19)

Figure 3.19 Configuring an inject node to send on a websocket

Configure the websocket nodes to connect to wss://echo.websocket.org as shown in Fig 3.20.

Figure 3.20 Configuring the websocket to send to a public echo server. Do the same for the websocket out node.

Deploy. When you click on the inject node you will see the message printed out as shown in Fig 3.21

 

Figure 3.21 Output from a websocket listening for incoming data

 

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson3/3-7_websockets.json

Example 3.8 Sending TCP requests.

TCP 接続をする。読めばわかる!

This example shows you how to send TCP requests using the tcp node. In this case you will make an HTTP request following the specifications in (http://tools.ietf.org/html/rfc2616#section-5.1.2).

This example shows the use of the tcp node. It could equally be configured with the udp or http nodes in a similar manner.

 

To get started, let’s connect an inject, function, tcp request, and debug nodes as shown in Fig 3.22.

Figure 3.22 building a TCP request and sending on a tcp output node

Edit the first function node to add a function that sets the string “GET / HTTP/1.1\r\n\r\nHost: www.google.com” as payload as shown in Fig 3.23.

This string is a standard HTTP request, indicating it is a GET request, the protocol is HTTP 1.1 and the host is www.google.com. The \r\n\r\n is two return/newline pairs which is required in the HTTP protocol.

Figure 3.23 Building a TCP request in a function node

Configure the tcp request node to connect to the www.google.com server, on port 80. Configure it to close the connection after 1 second (1000 ms) as shown in Fig 3.24.

Figure 3.24 Configuring the end-point for a TCP request

The tcp request node response is a buffer and needs to be parsed. Configure the second function node to parse the tcp request node response as shown in Fig 3.25

Figure 3.25. A function node to parse a response buffer into a string

If you deploy the flow and click on inject, you will make a request to Google and will get a TCP response. The debug node will print the response as a string as shown in Fig 3.26.

Figure 3.26 Printing out the response to a well formed HTTP request sent over a TCP connection.

Some of you may be wondering why you need to use a function node to build the HTTP request that we sent over TCP. Why not just use the inject node to input the string? The reason is that the inject node ‘escapes’ the string it uses, causing the return/newline you inserted to be removed. This in turn confuses the receiving server (Google) into not returning a response as it waits for the missing return/newlines. So instead, you build the string in a function node. This is one of those ‘gotchas’ that trips up even experienced Node-RED programmers, so always read the info pane for nodes to make sure you understand any limitations or constraints.

 

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson3/3-8_tcp.json

Summary

In this lecture you have seen a series of small examples that use a number of the processing and communication nodes that are available in Node-RED. As you have seen, it is both easy and fast to wire together basic flows that take real-world input, carry out some processing, such as simple data analysis, and return results.

In these examples, you have done little or no coding, but still have been able to build quite complex programs – this is the power of Node-RED.

The next lecture is a quick summary of the basic set of nodes that are available in both vanilla Node-RED as well as the extended set that the FRED service provides. You can read through the lecture to understand the default capabilities, or you can treat the lecture as a reference and use it to look up examples of each node as used in this lecture series

最初のフローを作る。Node-REDレクチャー2

Node-RED: Lecture 2 – Building your first flows

This lecture will introduce you to the Node-RED visual tool and get you started building your first flow. You’ll learn how to create simple flows, use debug nodes to track messages through the flows and how to use the function node to write simple JavaScript code that tailors the node to your specific needs.

このレクチャーでは、視覚的なNode-REDのツールを使って、最初のフローを組み立てます。シンプルなフローを作成する方法を習得し、debug ノードを使ってフロウの中のメッセージを追跡し、function ノードを使ってシンプルな JavaScript コードを書き自分の希望にあったノードに調整していきます。

To get you started, you’ll be using a free cloud service that provides you with a preconfigured Node-RED setup and a wide range of built-in nodes. Later lectures will explain how to set-up Node-RED for yourself on devices such as a Raspberry PI.

はじめるにあたって、前もって設定され広い範囲のnodeが組み込まれたNode-REDを提供する無料のクラウドサービスを使用していきます。のちのレクチャーではNode-REDをラズパイ等の自分のデバイスにセットアップする方法も紹介します。

At the end of this lecture you’ll be able to create your own simple flows, you’ll know your way around the Node-RED UI and you’ll be familiar with some of the basic built-in nodes that Node-RED offers.

このレクチャーの最後には、シンプルなフローを自分で作成できるようになり、Node-REDのUIや、Node-REDに組み込まれた基本的なノードについて理解できるようになります。

FRED フロント・エンド・フォー・Node-RED

FRED – Front end for Node-RED

FRED is a cloud service that we’ve created that allows you to sign up and use Node-RED without the hassle of downloading and installing on a device such as a PI. It makes it easy to get started with Node-RED by managing an instance of Node-RED for you, keeping the instance up to date with the latest code releases and applying bug fixes or patches. Also included is a set of extra Nodes that are contributed by the community, which add to the standard basic set you get when you install Node-RED yourself. However, FRED is just a wrapper for Node-RED, so anything you write in FRED will work on a Node-RED instance running on a Pi or a Beagleboard.

FRED はクラウドサービスで、私達が開発したものです。これはサインアップするだけですぐにNode-REDを使うことができるもので、ダウンロードしたりラズパイといったデバイスにインストールする手間がありません。なのでNode-REDを簡単に始めることができ、自分のNode-REDインスタンスを管理でき、インスタンスを最新のコードにアップデートし続けてくれ、バグフィックスのパッチも当てられています。またコミュニティーによって開発されたノードも追加されており、これはNode-REDにふくまれるベーシックなものとは別のものです。とはいえFREDはNode-REDのラッパーなので、FREDで書いたものは全て、ラズパイやBeagleboardで走るNode-REDの中でも同様に動きます。

To begin our examples, make sure you have created your own Node-RED instance in the cloud by signing up for a free account at http://fred.sensetecnic.com.

作例をスタートするために、自分のNode-REDインスタンスを、クラウドサービス内で立ち上げてください。サインアップし、フリーアカウントを取得しましょう。

After registering, make sure to activate your account via your email. You will not be able to log in until you validate your account.

登録した後に、Eメールによるアクティベイトが必要です。アカウントを証明するまではログインできません。

Node-REDのUIについて

The Node-RED UI

Once you have logged in to your FRED account, you’ll see the standard Node-RED UI which consists of three main panes, as shown in Fig 2.1

まずFREDにログインすると、一般的なNode-RED UIが立ち上がります。これは3つの中心的なパネルから構成されています。

Screen Shot 2015-10-22 at 4.53.21 PM.png

Figure 2.1 The Node-RED UI  – showing the node palette (left), flow canvas (centre) and output pane (right)

(左)ノードパレット、(中)フロー・キャンバス、(右) アウトプット窓

The main pane is the flow creation workspace in the middle. This is where you drag and drop nodes and connect them with wires. Along the top of the workspace pane is a set of tabs. Each tab opens a previously created workspace and shows any flows created using that workspace.

メインの窓は、フローを作成するためのワークスペースで、中央に配置されています。ここにノードをドラッグ・アンド・ドロップし、そしてワイヤーで結線していきます。ワークスペースの上部には、タブがあります。それぞれのタブは、以前に作成されたワークスペースを示しています。

On the left is the node pane that contains all the built-in nodes that your instance of Node-RED supports. In the example above, you are seeing the FRED node set which contains a large selection that has been added to the basic set that comes with Node-RED. In later lectures you will learn about these nodes and use them to develop new flows. As you can see, nodes are grouped into categories. Opening up a category shows the individual nodes.

左側には、ノードが全て配置されているノード窓があります。上記の例では、Node-REDに最初から組み込まれているものに加えて、FREDノードが追加されているのがわかります。レクチャーを通して、これらのノードを使ってフローを作る方法を学んでいきます。ご覧の通り、ノードはカテゴリー分けされています。カテゴリーをクリックして開くことで、その中に含まれているノードを見えるようにしてみましょう。

On the right-hand side is the output pane that can be toggled between the info and debug tabs. When info is selected, documentation for the selected node is shown there.  When debug is selected, it will display the output of debug nodes, errors and warnings.

右手には、アウトプット窓があります。info と debugタブを切り替えられます。infoタブが選択されているときには、選択されているnodeのドキュメントがそこに表示されます。debug タブが選択されているときには、debug ノードのアウトプットが示され、エラーやワーニングを通知します。

Above these three main panes is the usual toolbar, and on the right-hand side are three widgets, a deploy button, a user info icon and a pulldown menu for admin and control. You’ll look in more detail at the pulldown later in these lectures. The user info icon allows you to return to the FRED front page with links to tutorials, your account information, status and other information as well as to log out of the FRED service.

これら3つのメイン窓の上には、ツールバーがあります。ツールバーの右側には3つのウィジェットがあります。デプロイボタン、ユーザーインフォのアイコンと、adminとコントロールのためのプルダウンメニューです。プルダウンメニューの中身については、このあとのレクチャーで取り上げます。ユーザーインフォアイコンは、FREDのフロントページに戻ることができます。そこにはチュートリアルへのリンクがあったり、自分のアカウントの情報があったり、ステータスや、ログアウトするための画面、その他様々な情報があります。

The Deploy button is used when a flow has been constructed and causes the flow to be deployed onto the Node-RED system and executed. You’ll be introduced to the details of what’s actually happening under the covers in lecture 5 and beyond. For now just treat the Deploy button as the way to get your flow running.

Deployボタンは、フローが完成し、フローをNode-REDシステム上にデプロイし、実行する際に使用します。詳細についてはレクチャー5以降で説明します。今のところはデプロイボタンは、作成したフローを実行するために使用することになります。

 Node-REDのノードとメッセージの概略

A quick tour of Node-RED nodes and messages

As you saw in lecture 1, Node-RED allows you to wire together nodes to create flows which carry out your programming task. Messages pass between nodes, moving from input nodes through processing nodes to output nodes. Let’s take a brief look at nodes, flows and messages.

レクチャー1で見てきたように、Node-REDはノードをつなげ、フローを作り、プログラミングによってタスクを処理します。メッセージはノード間で渡され、Inputノードからプロセシングノードを通り、outputノードに到着します。ノード、フロー、メッセージについてさっと見ていきましょう。

There are three main  types of nodes:

主要な3つのノードがあります。

  1. Input Nodes (e.g. inject) Inputノード(injectノードなど)
  2. Output Nodes (e.g. debug) outputノード(debubノードなど)
  3. Processing Nodes (e.g. function) Processingノード(functionノードなど)

basic-fred-intro-02

Figure 2.2 The main types of nodes: input, output and processing

Input nodes allow you to input data into a Node-RED application or “flow”. They have at least one output endpoint represented by the small grey square only on their right side. You use input nodes to connect data from other services, for example the  Twitter, Google, serial, websockets or tcp nodes, or to manually input data into a flow using the inject node.

Inputノードは、データをNode-REDアプリケーション、つまりフローに入力させることができます。これらは、少なくとも1つ以上のoutputエンドポイントを持ちます。outputエンドポイントは、小さな灰色の四角で表され、右側に配置されています。Inputノードを使うことで、外部サービスのデータと接続することができます。例えばTwitter, Google, Serial, websocket, tcp といったものと接続することができます。ほかにも手動でデータをInputするためにも使うことができます。その場合にはinjectノードを使用します。

Output nodes allow you to send data outside of a Node-RED flow. They have a single input endpoint on their left side. You use output nodes to send data to other services, for example via Twitter, tcp, serial or email nodes, or to use the debug node to output to the debug pane.

Output ノードはNode-RED flowの外にデータを送ることができます。Inputエンドポイントが左側に一つあります。Outputノードを使ってデータを他のサービスに送ったり、例えばTwitter, Google, Serial, websocket, tcp といったものと接続することができます。他にもデバグノードを使って、Outputをデバグ窓に表示することもできます。

Processing nodes allow you to process data. They have an input endpoint and one or more output endpoints. They allow you to transform the data type (e.g. json, csv, xml) nodes, use the data to trigger a message (e.g. trigger, delay) nodes and to write custom code that uses the data received (e.g. function node).

Processingノードは、データを処理することができます。1つのinputエンドポイントと、1つ以上のOutputエンドポイントを持ちます。例えばデータのタイプを変えるノードや(json,csv,xmlノードなど)、データをトリガーにしてメッセージを送るノードや(trigger,delayノード)、受け取ったデータをもとに自由な処理をかけるノードもあります(functionノード)

Note that some nodes, like the inject and debug messages, have a button that allows you to actuate a node (in the case of the inject node) or to enable and disable a node (in the case of the debug node).

ノードの中には、例えばinjectノードやdebugメッセージノードのように、ボタンを持ち、ノードをacuateさせたり(injectノードのように)、enable もしくはdisableにできるもの(debugノードのように)があります。

Flows consist of multiple nodes wired together, with output tabs linked to input tabs of the next node in the flow. Messages flow along the nodes carrying data from node to node.

flowは複数の接続されたノードからなり、各ノードのアウトプットは次のノードのインプットに接続されます。メッセージは、このノードの中を伝わっていきます。

Node-RED nodes consume input messages and produce output messages. Messages are JavaScript objects that contain at least a “payload” parameter, like this:

Node-REDはInputメッセージを受け、Outputメッセージを作成します。メッセージはJavaScriptオブジェクトで、少なくともpayloadパラメーターを持っている必要があります。次のように。

Listing 2.1 A basic Node-RED message structure

msg = {
payload:”message payload”
};

Nodes consume and produce messages, usually using msg.payload as the main placeholder for the data they consume and produce. However, messages can be extended to contain other parameters. For example, to set the topic of a message and add a new parameter, location, you could create a new msg object as shown in listing 2.2.

ノードはメッセージを受け取り、メッセージを生成します。大抵の場合はmsg.playloadがメッセージのやりとりにおける、メインのプレースホルダーとして用いられます。もちろんmsg.playload以外のメッセージをもたせることもできます。例えば、メッセージのトピックと、ロケーションを、新しい値として設定することもできます。

Listing 2.2 A more complex Node-RED message structure

  1. msg = {
  2.   payload:”message payload”,
  3.   topic:”error”,
  4.   location:”somewhere in space and time”
  5. };

Let’s use this knowledge to create your first flow.

学んだ知識を使って、最初のフローを作っていきましょう。

最初のフローを作ろう「ハローワールド」

Example 2.1 Building your first flow: Hello World

Let’s go ahead and start building your first flow so that you can see how simple it is to use the Node-RED UI to build and deploy a flow.

さあ最初のフローを作ることにしましょう。これを通して、Node-RED UIを使ってビルドとディプロイが簡単にできることが理解できるでしょう。

Let’s start with the easiest flow possible, a node to inject some information into the flow, wired to a debug node to see the output from the flow as a debug message. Once you have that running, you’ll build it up to the full Hello World flow.

さあ、なるべく簡単なフローにしました。injectノードを使って情報をフローに取り込み、debugノードにそれを繋いで、メッセージのアウトプットをデバグメッセージとして確認します。これが動けば、最初のハローワールド・フローを完成させたことになります。

Since this is the first time you’ll be shown how to actually build a flow, let’s start slowly and explain each step with a screen-shot. Once you’ve created your first flow and seen how easy it is, you’ll mostly be shown a single picture of the final flow rather than all the screenshots.

実際のフローを作る手順を説明するのは初めてなので、ゆっくりと各ステップをスクリーンショットを使って説明していきますね。最初のフローが完成した頃には、この作業がとても簡単だとわかることでしょう。

Let’s start with the simplest Node, the comment Node. You’ll find this in the function section of the node palette. Drag and drop a comment node onto the flow workspace as shown in Fig 2.3.

まずはcommentノードです。functionセクションの中にこのノードはあります。ドラッグ&ドロップをして。フローワークスペースに配置しましょう。

Screen Shot 2015-07-31 at 2.03.20 PM.png

 

Figure 2.3: Using a comment node is a great way to add visible comments into flows

 

Once you’ve done that, take a look at the info pane on the right (remember to switch to info if the debug tab is selected). You’ll see a little info on the node, including the node name, a unique ID, and a properties field with a description of the node. For the comment node there’s not much to say; however, more sophisticated nodes have a lot more info.

配置したら、右側にあるinfo窓をみてください。(info窓とdebug窓は切替可能のですので、info窓を選択するのを忘れないでください) するとノードにかんする情報を確認スルことができます。ノードの名前や、ユニークID、説明付きのproperties fieldがあります。commentのノードにはとりわけ説明すべきことはありませんが、より高機能なノードに関しては、より多くの情報を確認することができます。

Double-click on the comment node, and you’ll see a configuration window (Fig 2.4) You can give the comment node a name and add detailed text if you like.

コメントノードをダブルクリックすると設定画面が出ます。コメントノードに名前をつけたり、詳しいテキストを加えることができます。

Screen Shot 2015-07-31 at 12.16.33 PM.png

Figure 2.4 Give the comment a name and add any info you want in the text box

 

Ok, now let’s add the first node that actually does something, an inject node. The inject node is used to generate input into a flow and is one of the first nodes in the node palette under input. If you drag and drop an inject node onto the flow workspace, and then look at the info tab, you’ll see the documentation for the inject node. Note that the name of the node on the workspace changes from inject to timestamp, because the default behaviour for the node is to inject a timestamp – the current time in milliseconds since January 1, 1970.

次は実際に何かをするノードを追加してみましょう。今回はinjectノードです。injectノードは、インプットをフローに加えます。これはインプットカテゴリーにあります。injectノードをドラッグ&ドロップをして配置し、インフォタブを見てみましょう。このノードに関する説明があります。配置するとノードの名前がinjectからtimestampに変わったことにお気づきでしょうか。これはこのノードのデフォルトの挙動が、timestampを挿入する機能になっているからです。この機能は、現在の時間を1970年1月1日から数えた秒数で出力します。

Screen Shot 2015-07-31 at 12.03.59 PM.png

Fig 2.5 The inject node allows you to insert events as messages, defaulting to a timestamp

You’ll also notice that the inject node (now named timestamp) has a blue dot top right and a grey square centre right. The blue dot indicates that the node hasn’t been deployed since it was last changed; the grey square is the output point for the node. This is where you attach ‘wires’ that route output message from the inject node to the next node in the flow.

またinjectノードは(いまのところtimestampという名前が付けられていますが)青いドットが右上についており、灰色の四角が右側中央にあります。青いドットはノードが変更された後に、まだデプロイされていないことを示しています。灰色の四角はノードのOutputポイントです。これをつかってinjectノードのアウトプットメッセージを次のノードに渡すために、このポイントを使って接続していきます。

To get a sense for the inject node and the whole flow deployment process, let’s add a debug node to see what happens, wire them together and then deploy the flow and test it.

injectノードを理解するために、そしてフロー開発全体の理解をするために、デバグノードを追加し、デバグノードを使って何が起きているのか確認してみましょう。それらをつなぎ、デプロイし、フローをテストします。

Start by dragging a debug node from the node palette to the workspace. Again you can look at the info for the node.

debugノードをドラッグ・アンド・ドロップします。

Then you’ll wire the two nodes together. To do that, click on the grey output point for the inject node and, holding the mouse button down, drag towards the debug node. An orange wire appears, which you can then attach to the grey input point on the debug node.

そうしたら次に、2つのノードをつなぎましょう。そのためには、injectノードの灰色のOutputポイントをクリックして、マウスを押しっぱなしにしながら、デバグのノードに向かって進めていきます。オレンジのワイヤーが現れるので、デバグのノードの灰色のInputノードにつなげましょう。

Screen Shot 2015-07-31 at 12.40.55 PM.png

Figure 2.6 Wiring an inject node to a debug node

 

This is the simplest flow possible and will send the current timestamp to the debug node for display in the debug pane. Let’s try it!

これが一番簡単なフローで、これは現在の時間をデバグノードにおくり、デバグ窓にそれを表示するフローです。やってみましょう!

Click the deploy button in the Node-RED window (top right). You’ll see a pop-up saying the flow has been successfully deployed. You will also notice that the blue dots on the nodes disappear, indicating there are no undeployed changes.

Node-REDウィンドウの右上にあるディプロイボタンを押しましょう。するとフローがデプロイに成功したメッセージがポップアップで表示されるはずです。また青いドットが消え、変更が全てデプロイしたことを示します。

Now, before you try the flow, make sure the the debug tab is selected on the right pane. Then click on the left tab on the inject node and look at what appears in the debug pane.

デバグタブをまず開きます。そして

Screen Shot 2015-07-31 at 12.48.44 PM.png

Figure 2.7 Debug output from your first flow – the time when you clicked the inject node.

 

As you can see, the inject node, when clicked, generates a timestamp (number of milliseconds since January 1, 1970), which is converted to a message and sent along the output wire, which is delivered to the debug node as an input message. The debug node’s default behaviour is to show any message it receives, which it does in the debug pane on the right.

インジェクトノードをクリックすると、タイムスタンプが作成され、それがメッセージに変換され、Outputワイヤーを通して送信されます。それはdebugノードに運ばれ、inputメッセージとして入力されます。debugノードのデフォルトの挙動は、受け取ったメッセージを右側のdebug窓に示します。

Congratulations, you created and deployed your first flow!

おめでとうございます。最初のフローを作成し、デプロイできましたね!

Let’s now augment it a little to see what else we can do with this simple flow. Firstly, we’ll edit the inject node to deliver a text message rather than a timestamp. To do that, select the inject node in the flow and double-click it. You’ll see a configuration window like the one in Fig 2.8.

すこし追加の作業をして、このシンプルなフローでどんなことができるのか、より理解してみましょう。まずinjectノードを編集して、テキストメッセージを送るようにしてみましょう。そのためには、インジェクトノードを選択して、ダブルクリックします。すると設定画面が開きます。

Screen Shot 2015-07-31 at 12.54.29 PM.png

Figure 2.8 Editing an inject node to send text instead of a timestamp

 

In the payload field, select string instead of timestamp and then type any string you like into the blank field below the payload field. As is traditional, let’s start with “Hello World – from my first NR flow!”

playload fieldにおいて、stringを選んで、好きな文字列をplayload fieldの空欄に入力しましょう。伝統に則り、ハロー・ワールドと入力することにしましょう。

Once you’ve made the change, click ok to save the changes and take a look at the flow. You’ll see the blue dot has appeared on the inject node (which has also returned to being called inject rather than timestamp) to indicate that you have undeployed changes. Click the deploy button again to resolve that and then go ahead and click the tab on the inject node. If you look at the debug output you’ll see that instead of a timestamp, your text has been delivered as a message to the debug node, which displays it as usual.

この変更をして保存します。すると青いドットがinjectノードにあるのがみえます。これは変更がディプロイされていないことを示しています。では再度deployボタンを押して、ディプロイし、injectノードをクリックしましょう。するとあなたが入力したテキストがメッセージとしてデバグノードに送信され、それがいつも通りdebugノードに表示されます。

Screen Shot 2015-07-31 at 1.01.40 PM.png

Figure 2.9 Sending a text message rather than a timestamp

 

As you can see, it’s very easy to wire up some simple nodes and get data to pass through your flow as messages. At this stage, you’ll probably be wondering a little about the messages that are flowing between nodes. The debug node can be used to examine them in more detail.

ご覧の通り、簡単に、ノードをつないでデータを取得して、フロー中へ渡すことができました。この段階では、フローの中を移動するメッセージの内容について疑問がまだあると思います。デバグノードをつかって、メッセージの詳細を精査することもできます。

All messages in Node-RED have three default properties: the payload, which we are seeing above, a message topic, which is a user-defined string describing what the message is about (its topic, if you will) and an internal identifier. You can actually see this information if you edit the debug node configuration. Let’s do that and look at the output (Fig 2.10)

Node-REDのメッセージは全て、3つのデフォルトのプロパティを持っています。payloadは既にみてきました。message topicはメッセージが何についてのものなのかを、ユーザーが指定できる文字列です。そしてinternal identifierです。これらの情報はdebugノードの設定外面で変更を加えると、確認することができます。↓debugノードの設定画面で、outputをcomplete msg objectに変更する。

Screen Shot 2015-08-06 at 11.15.08 AM.png

 

Figure 2.10: setting the debug node to show the internals of a message

 

Select the debug node, double click and change the node output field to “Complete msg object”. If you then save this, deploy again and click the inject node, you will see in the debug pane a JSON structure that contains 3 fields: a “topic” which is currently blank, a “payload” which contains the string you set in the inject node and an internal ID field “_msgid”. Generally the internal message ID field isn’t used. However, both the topic and payload are used extensively when developing flows. You’ll see more of that later in the lecture series.

debugノードを選択して、ダブルクリックをしてノードのoutputフィールドを”complete msg object”に変更してください。これをセーブしてディプロイして、injectノードをクリックすると、debug窓にJSON構造のデータを確認することができます。これには3つのfiledがあります。topicは現在は空白で、”payload”にはあなたがinjectノードで指定した任意の文字列が、そしてinternal IDフィールド”_msgid”です。基本的にはinternal message IDは使いません。しかし、topicとpayloadはどちらともよく使われます。これらについてはこのシリーズでまた取り上げます。

These fields are extensible, so you can define new message properties, for example, msg.location, which could be used to add the latitude and longitude values for the source of the message. Let’s take a look at that in the next example flow.

これらのfieldは拡張可能です。ですから新しいmessage propatyを設定し、例えばmsg.location等を設定し、位置情報をメッセージに付加することができます。次のサンプルを通して、これをみていきいましょう。

You can find the node-red description of this flow at:

https://github.com/SenseTecnic/nrguideflows/blob/master/lesson2/2-1-firstflow.json

例2.2 天気アラート

Example 2.2 A second flow: weather alerts

In this example, which is similar to the one introduced in lecture 1, you’ll monitor the weather in your hometown and send yourself a tweet when the weather looks like it’s going to be good. You’ll use a built-in weather node – openweathermap – that retrieves the weather from openweathermap.org for the location you set it for. A simple function node will be used to check for ‘clear weather’ and a Twitter node will be used to send yourself a tweet when the weather looks good.

この例は、レクチャー1で紹介したものと同じもので、あなたの街の天気をモニターして、天気が良くなりそうになったら、ツイートをします。ここでは最初から組み込まれている天気用のノードである、openweathermapを使用することができます。これはopenweathermap.orgからあなたが設定したエリアの情報を取得するノードです。そしてシンプルなファンクションノードを使って、快晴かどうかを判断して、Twitterノードを使ってあなたにTweetを送ります。

First you will need to get an API key at OpenWeatherMap. OpenWeatherMap offers a great service that provides detailed weather information for worldwide locations. Visit http://openweathermap.org/appid and follow the instructions as shown in the screenshots below.

まずはOpenWeatherMapでAPI Key を取得しましょう。OpenWeatherMapは詳細な天気情報を提供してくれる、素晴らしいサービスで、世界中の場所に対応しています。http://openweathermap.org/appidにアクセスして、指示にしたがいましょう。

 

 

You will need to sign up for an OpenWeatherAccount as shown below:

まずはサインアップする必要があります。

After signing up you will be redirected to your Home page where you will be able to access or re-generate your API Key. It should look something like this:

サインアップしたあとは、自分の設定ページでAPIキーを作成しましょう。

Now, let’s use that API key to build a weather alerts flow. Drag and drop a weather node from the left pane onto the workspace, as shown in Figure 2.11.

ではこのAPIキーを使って天気アラートを作っていきます。weatherノードをドラッグ・アンド・ドロップしましょう。(訳注:ないけども!!なくない???しょうがないので、macにnode-redをnpmでインストールして、openweatherノードもnpmでインストールしました。さしあたってグローバルにインストールすれば良い模様。)

Figure 2.11. Drag and drop a weather node onto a blank workspace

 

If you select the info pane on the right, you can see a description of the openweathermap node with detailed information on how to configure and use it. Some interesting things to note:

選択して詳細窓を見ると、説明を見ることができます。

  • It has a full JSON structure as its msg.payload, with quite a lot of weather detail, all presented as name:value pairs, e.g. wind speed and tempc
  • JSON構造のmsg.payloadを持ち、これには膨大な天気情報が記されています。全ては名前:値のペアになっていて、名前には例えばwind speedとかtempc等があります。
  • The node defines 3 new message properties, msg.location, msg.time and msg.data. As mentioned above, you are free to add properties to messages, and the openweathermap node has added these new properties to carry extra information associated with the message.
  • ノードは新たに3つのmessage propertyを設定しています。msg.location, msg.time, msg.dataの3つです。既に解説したように、自由にmessageへプロパティを追加することができます。openweathermapノードは、これらの新しいプロパティを追加し、メッセージへさらなる情報を関連付けて運ぶのです。

Let’s configure the node and look at the actual data structure it generates after it has queried your local weather. Start by double-clicking on the node and fill out the form with your location. Type your city and country in the fields. Add the API key you obtained from http://openweathermap.org/appid and click on “Ok” as shown in Fig. 2.12.

 

 

Figure 2.12. Set your city and country in the configuration form, use the API key you obtained in the step above.

 

Then drag and drop a debug node and wire it to the openweathermap node. Click on “Deploy” to see that the payload object from the openweathermap node in the debug pane.

ディプロイしてplayloadオブジェクトの中身をデバグ窓でみてみましょう。

Listing 2.3 The message payload for the openweathermap node is a JSON structure describing weather conditions, temperature, wind, cloud cover and sunrise times.

このなかには色々な情報がJSON形式で含まれていることがわかります。

  1. {
  2.   “weather”: “Clear”,
  3.   “detail”: “sky is clear”,
  4.   “tempk”: 295.104,
  5.   “tempc”: 21.903999999999996,
  6.   “humidity”: 53,
  7.   “maxtemp”: 295.104,
  8.   “mintemp”: 295.104,
  9.   “windspeed”: 2.22,
  10.   “winddirection”: 273.007,
  11.   “location”: “Vancouver”,
  12.   “sunrise”: 1432038196,
  13.   “sunset”: 1432094081,
  14.   “clouds”: 8,
  15.   “description”: “Vancouver weather(49.25,-123.12) is Clear (sky is clear).”
  16. }

As you can see, the node delivers quite a lot of information about your local weather, all as the usual name:value pairs. For this example, you want to use the “weather” field which you’re going to test to see if it’s reported as “Clear”. If it’s “Clear” you’ll then send a tweet.

ご覧の通り、nodeはかなり大量のローカル天気情報を運搬し、それぞれの情報は一般的なname:value のペアで管理されています。例えば、その中からweatherフィールドに含まれる情報を使って、それが「clear 快晴」かどうかを判断するテストに使うことができます。もし快晴であればツイートするような機能を作ってみましょう。

To program that logic, you’ll use a function node. You saw one of these in lecture 1, but without the details. Let’s see how they are used by dragging one onto the flow workspace and double clicking it to open up the node editor.

このロジックをプログラミングするためにはfunctionノードを使うことができます。これは既にレクチャー1でみたものですが、詳細についてはまだ説明していませんでした。あらためてどのように使うのかみていきましょう。まずドラッグ・アンド・ドロップでワークスペースに配置し、ダブルクリックをして設定画面を開きましょう。

Figure 2.13. Add a function node and wire it to the openweathermap node.

Now double-click on the function node and type/copy this (Note if you use copy/paste – make sure you paste as plain text, wordpress sometimes inserts odd characters)

次の文字列をコピペしてください。

Listing 2.4 Function node “If Clear Weather”

  1. if (msg.payload.weather === “Clear”) {
  2.     msg.payload = “Clear skies ahead today!”
  3.     return msg;
  4. }
  5. return null;

Figure 2.14. Edit the function node adding the JavaScript shown in listing 2.4

Looking at Listing 2.4, you can see that this will parse the incoming message payload for the weather parameter and compare it to the string “Clear” (line 1). If it is equal, it will rewrite the message payload with your own string “Clear skies ahead today!” (line 2). Otherwise it will return a null message (line 5). This last bit is important because in Node-RED nodes ignore null messages.

このプログラムは、入力されたmessageのpayloadをパースして、weatherパラメータを取得し、これを文字列”Clear”と比較しています。これが等しければ、messageのpayloadを書き直して、“Clear skies ahead today!”とします。そうでなければ、nullメッセージを返します。この最後の短い行は大切で、なぜならNode-REDはnullメッセージを無視するからです。

You can do all sorts of things now, for example wire this message to an email node, or a pushbullet node. For this tutorial we will use the Twitter output node. Drag  a Twitter node onto the workspace, double-click and and fill out your Twitter account credentials as shown in Fig 2.15.

さあここまでくれば、どんなこともできますよ。例えば、メッセージをEmailノードにつなげたり、pushbulletノードにつなげたりできます。このチュートリアルでは、Twitter Outputノードを使うことにします。Twitterノードをドラッグして、設定画面からTwitterアカウントの情報を入力しましょう。

Figure 2.15. Set your Twitter account credentials into the node configuration

Once you’ve set up these credentials, Node-RED stores them and you can reuse them when you create another Twitter node in future flows.

一度認証してしまえば、それは記録され、あとで使いまわすことができます。

Once you’ve wired up the flow, you can hit the deploy button and then watch your Twitter account to see the new tweet every time the weather is reported as clear.

ではワイヤーでつないで、ディプロイしましょう。

Click on “Deploy”:

Figure 2.16. The full weather flow sending tweets if the weather report mentions clear skies.

Other useful UI features

One of the most useful features of the Node-RED UI is the ability to copy and paste nodes and even full flows using the standard cut’n’paste clipboard. Node-RED flows are simply coded as JSON strings and can be exported from a workspace, and imported into a workspace using the Node-RED pulldown menu in the top right of the Node-RED window.

Node-RED UIの中で一番便利な機能は、ノードをコピペする機能で、一般的なコピペコマンドで実行することができます。これを用いて、フロー全体をコピペすることもできます。Node-REDフローは、シンプルなJSON文字列でできているので、ワークスペースにあるフローを書き出したり、ワークスペースへ読み込んだりすることができます。Node-REDのプルダウンメニューから実行します。

Rather than building the flows in this example, or in fact anywhere in this lecture series, by hand yourself, you can simply copy them from our website and paste them into a workspace. After that all you need to do is configure them correctly, e.g. with credentials, and deploy them.

自分で全てを作る代わりに、私達のサイトからコピペーをして、いくつかの設定項目を理解し、変更するだけで、じつはすんでしまいます。

Let’s quickly show you how to do that.

どのようにやるのか、みていきましょう。

Click on the link for this example which is at the end of the example below and look for the JSON code. Copy it to the clipboard using the usual CTL C or copy item in the edit menu.

このサンプル解説の一番下にあるリンクから、このサンプルのJSONコードを取得して、一般的なコントロール+Cコマンドなどでコピーしてください。

Using the pulldown menu in the top right of the Node-RED window, select Import->Clipboard as shown in Fig 2.17

つぎに、Node-REDの右上にあるプルダウンメニューから、Import→クリップボードを選択します。

Screen Shot 2015-08-15 at 12.55.58 PM.png

Figure 2.17 Selecting the Import from Clipboard menu item in Node-RED

 

You will see a popup with an input field (Fig 2.18). Paste your clipboard into the input window and click OK.

するとインプットフィールドがポップアップで表示されますので、今コピーしてきた情報をペーストし、OKをおしましょう。

Screen Shot 2015-08-15 at 12.56.27 PM.png

Figure 2.18 Pasting a flow into the import window of Node-RED

 

The new flow will appear in the current workspace and can be moved to a location and dropped. Once it’s in place, you can configure it as you would a flow you created yourself and deploy it.

すると、新しいフローがワークスペースに登場するはずです。一度読み込んでしまえば、あとは自分が好きなように修正をして、ディプロイをして使うことができます。

You can find the node-red description of this flow at:

https://github.com/SenseTecnic/nrguideflows/blob/master/lesson2/2-2_weatheralerts.json

Summary

In this lecture you have created your first flows and seen how to wire together a set of basic nodes to achieve quite complex tasks. We’ve skipped over a few of the underlying details in order to get you going quickly, and we’ll return to those in lectures 3 and 4. However, so far you’ve seen how to use the Node-RED visual flow builder, the basic classes of input, output and processing nodes. You were given a brief overview of messages and how to use the function node to write your own JavaScript code to do simple processing on messages within a flow. In the next lecture, you’ll take a more in-depth look at the programming model of Node-RED and get a better understanding of the main programming elements and nodes and how to craft more complex flows using a variety of nodes.

このレクチャーでは、最初のフローを作る方法を紹介しました。その中で基本的なノードをワイヤーでつないで、複雑なタスクを実行する方法がわかってもらえたと思います。まずは概念を理解してもらうために、いくつか複雑なことは飛ばしましたが、これについてはレクチャー3か4で扱います。とはいえ、Node-REDの視覚的なエディタ、input、output、functionノードの使い方がわかったはずです。またメッセージがどんなものなのかもわかり、functionノードを使って自分でJavaScriptを書いて、シンプルにノードフローを流れるメッセージを処理する方法も学習しました。次のレクチャーでは、より踏み込んでNode-REDのプログラミングモデルを学習していきます。それによって主要なプログラミングに用いる要素の一層の理解と、より多様性のあるノードを使って複雑なフローを構築する方法についても学んでいくことになります。

Node-RED イントロダクション

Node-RED: Lecture 1 – A brief introduction to Node-RED

Node-RED: Lecture 1 – A brief introduction to Node-RED

This lecture will introduce you to some examples of Node-RED, both to give you a sense of its capabilities and to introduce its basic concepts. We’ll also discuss the history of Node-RED and its origins to give you an idea of what Node-RED is good for and of what types of tasks are best left to a more traditional programming language and environments.

このレクチャーでは Node-RED を用いた作例を紹介し、Node-RED でどのようなことができるか、またその基本概念についてもお伝えします。Node-RED の歴史と起源についても触れ、それによって Node-RED がどのようなタスクに向いていて、またどのようなタスクについては古典的なプログラミング言語で処理したほうがいいのか、ということについても考えていきます。

Node-RED is a powerful tool for building Internet of Things (IoT) applications with a focus on simplifying the ‘wiring together’ of code blocks to carry out tasks. It uses a visual programming approach that allows developers to connect predefined code blocks, known as ‘nodes’, together to perform a task. The connected nodes, usually a combination of input nodes, processing nodes and output nodes, when wired together, make up a ‘flows’.

Node-RED は IoT アプリケーションを構築するためのための強力なツールで、特に、様々な機能の連携をシンプルに実装することに注力しています。タスクを処理する役目を持つ「コードブロック」を、シンプルにつなぐだけで実装出来るのです。Node-RED は視覚的なプログラミング手法を採用しており、開発者は予め用意されたコード・ブロック = nodes をつなげることで、タスクを処理させます。通常は input 用の node があり、処理用の node があり、最後に output 用のノードがあります。これらが結線されて、「flows」を形成します。

Originally developed as an open source project at IBM in late 2013, to meet their need to quickly connect hardware and devices to web services and other software – as a sort of glue for the IoT – it has quickly evolved to be a general purpose IoT programming tool. Importantly, Node-RED has rapidly developed a significant and growing user base and an active developer community who are contributing new nodes that allow programmers to reuse Node-RED code for a wide variety of tasks.

Node-RED は IBM のオープンソースプロジェクトとして2013年に開発が始められました。IBM は、ハードウェアや各種デバイスを、ウェブサービスや様々なソフトウェアと接続する必要があり、そのために開発されたのです。つまり IoT におけるつなぎの役目を果たします。その後 Node-RED 急速に進展し、IoT 全般で用いることができるツールになりました。また Node-RED が特に優れているのは、 急速に莫大なユーザーを獲得し、それから開発者コミュニティーが成長し続けていることにあります。新しい node がどんどんと追加され、様々なタスクを処理することが可能です。

Although Node-RED was originally designed to work with the Internet of Things, i.e. devices that interact and control the real world, as it has evolved, it has become useful for a range of applications.

Node-RED はもともと IoT のために作られたものではあるのですが、今ではもっと広い範囲のアプリケーションの作成においても便利なものになっています。

This lecture will introduce you to some examples of Node-RED, both to give you a sense of its capabilities and to introduce its basic concepts. We’ll also discuss the history of Node-RED and its origins to give you an idea of what Node-RED is good for and of what types of tasks are best left to a more traditional programming language and environments.

このレクチャーでは Node-RED を用いた作例を紹介し、Node-RED でどのようなことができるか、またその基本概念についてもお伝えします。Node-RED の歴史と起源についても触れ、それによって Node-RED がどのようなタスクに向いていて、またどのようなタスクについては古典的なプログラミング言語で処理したほうがいいのか、ということについても考えていきます。

By the end of this lecture you should have a high-level understanding of Node-RED, its programming model and some simple pre-built nodes as well as an insight into the origins and best usage of Node-RED.

このレクチャーのおわりには、Node-RED の深い理解を得て、Node-RED プログラミングの構造と、予め用意された Node への理解、それから Node-RED の起源と、最適な使用状況についての理解を得ることが出来るはずです。

Node-RED を知ろう

Getting to know Node-RED

Let’s get started by looking at a few simple examples of the kinds of thing you can do with Node-RED. Our goal in this lecture is not to get you programming with Node-RED, but to give you a sense of its capabilities through some high level examples. If you really want to dive straight in, you can skip ahead to lecture 2 where you’ll be taken through the steps to create and run your first flow.

Node-RED でどんなことができるのか、シンプルな例をみていきましょう。この記事の目的は、Node-RED でのプログラミングの方法の学習ではなくて、作例をみながらどんなことが Node-RED によって可能になるのか、という知見をもってもらうことにあります。すぐにでもプログラミングを始めたい場合には、この記事はスキップしてレクチャー2に進んでください。そこでは実際にプログラミングをして最初のフローを作成していきます。

This first example flow will receive a message from a Twitter feed containing a hashtag and turn on and off a LED when a new tweet has arrived. For this example let’s assume that NODE-RED is running on a Raspberry PI – a common situation for many Node-RED users.

次の最初の flow の例は、Twitter からハッシュタグをもつメッセージをフィードから取得し、新しい Tweet がされた時に、LED を点滅させるものです。この例においては Node-RED は Rasberry PI 上で動作させられることが想定されています。これは Node-RED の使用方法として非常に一般的なものです。

例1.1 Twitter を用いて Raspberry PI をコントロールする

Example 1.1 Using Twitter to control a Raspberry PI

The Node-RED flow to check Twitter and to see if a hashtag #led is detected, turns on a LED connected to a Pi is shown in Fig. 1.1. As you can see, it’s quite simple; it consists of 3 nodes wired together – a twitter node on the left, a trigger node in the middle and a Raspberry Pi (gpionode) node on the right. (gpio stands for General Purpose Input/Output and is the name given to the generic Raspberry PI node that handles IO). The nodes, represented by rounded boxes, usually have an icon to represent their type, e.g. the Twitter bird icon in the first node, and a text name that can be set by the programmer.

Node-RED の flow は Twitter をチェックして、#led のハッシュタグが検知された場合には、Raspberry PI に接続された LED を点灯させます。これを示したのが下記の図です。ご覧の通り非常にシンプルです。3つの node がつなげられています。Twitter のためのノードは左側にあり、トリガー用のノードが真ん中に、Raspberry Pi 用のノード(goionode)は右側にあります。(gpio はGeneral Purpose Input/Output の略記で、同時にここでは Raspberry Pi のIn/Out をコントールする一般的な node のための名前でもあります) ノードは丸みを帯びた四角形で表され、通常はその役割を表すアイコンを持ちます。 また名前を自分でつけることができます。

Each of these three nodes is built into the Node-RED visual programming tool and can be dragged from a node palette onto the main workspace. They are then ‘wired’ together by joining their output tabs to the input tab of the next node in the flow (the little grey blobs on the right or left of the node boxes.) The next lecture will look at the UI in detail, but for now let’s focus on the high-level capabilities.

それぞれ3つのノードは、Node-RED に組み込まれており、ノード・パレットからメインの作業スペースにドラッグ・アンド・ドロップで配置することができます。ノードを接続するためには、outputを、フロー上で次にくるInputにつなぎます。(左右にある、小さい灰色の丸がそれです。) 次のレクチャーではUIをより詳細にみていきますが、いまのところは概念的な説明をしていきます。

The Twitter node is a built-in node in Node-RED and hides all of the complexity of using the Twitter API. It can be configured with a user’s account credentials and a variety of search strings, in our case it’s simply looking for hashtag ‘#led’.

Twitter 用の node は Node-RED に最初から組み込まれており、Twitter API を使う上で生じる複雑さに触れる必要がないようにしてくれています。必要なのは、ユーザー認証情報と、検索用の文字列、このケースでいえば単純に #led のハッシュタグを探していいます。

When the Twitter node sees the tag either in a tweet to the user, or the public tweet feed, it creates a new message with the details of the tweet, which is forwards to the next node in the flow. In our example, since the Twitter node’s output is wired to the trigger node’s input, the trigger node receives a message with the details of the tweet.

Twitter ノードは、ユーザーのツイートとそれ以外の全ユーザーのツイートにおいて、指定されたツイートがされたことを確認すると、そのツイートの詳細情報を元に新しいメッセージを作成し、これをフロー上の次のノードに渡します。この例では、ツイッターノードのoutputはトリガーノードのInputにつながっており、トリガーノードはツイートの情報をもったメッセージを受け取ります。

The trigger node is another built-in node in Node-RED and its default behaviour is to wait for any message on its input. When it receives a message, it ‘triggers’, and sends a message on its output with the value “1” as the message body. It then waits 1 second and sends a second message with the value “0” in the message body.

Trigger ノードも Node-RED に最初から組み込まれているノードで、デフォルトの挙動は、Inputにくるメッセージを待ち受けることです。メッセージを受け取ったら、「トリガー」し、outputにメッセージを送ります。そのメッセージのbody値は0です。その後、1秒待った後に、bodyの値が0のメッセージを送ります。

Since the trigger node is connected to the gpionode, which controls the Input/Output or IO pins on the Raspberry PI, it get’s these two messages, 1 second apart, on its input.

トリガーノードは、gpionode に接続されているので、gpinode は送られてくる2つのメッセージを、1秒開けて、Inputから受け取ります。

Again, the gpionode is a built-in node in Node-RED that hides the details of setting the IO pins on the PI. When it gets a message with a value of “1” in the body, it takes the IO pin high, and when it receives a message with body of “0”, it takes the pin low. In this example, the gpionode is configured to control pin number 12, and so the node shows that in the node icon.

繰り返しになりますが、gpionode はNode-RED に最初から組み込まれており、ラズパイのIOピンの詳細設定に触れる必要をなくしてくれています。このノードが、body が1であるメッセージを受け取ると、IO ピンをhighにし、0を受け取るとピンをlowにします。この例ではgpionodeはピンナンバー12をコントロールするように設定されていますので、それがノードのアイコンでも示されています。

If you have your PI wired up with an LED connected to Pin 12, the gpionode going high for 1 second and then low will cause the LED to blink on for 1 second.

ラズパイの12pinがLEDに接続されていれば、gpionodeは1秒high、その後lowになるので、LEDを1秒点滅させることになります。

If you think about what’s happening here, it’s actually an incredibly powerful example of Node-RED and the Internet of Things (IoT). It’s connecting the ‘Twitterverse’ to a PI and an LED, but requires no programming – all the tasks are carried out by pre-built nodes in Node-RED which just need configuring. This really demonstrates the power of Node-RED when running on a simple device such as a Raspberry PI.

ここでおきていることは、Node-RED と IoT の強力さを示しています。「ツイッターの世界」がラズパイとそのLEDに接続されているのですが、そのためにはプログラミングが必要ないのです。全てのタスクは、Node-RED に最初から用意されている node によってなされてしまうのです。この例はラズパイのようなシンプルなデバイス上で Node-RED を動かくことによるパワフルな効果を示す良い例です。

So just to recap. Node-RED is a flow-based programming tool with a visual editor that allows you to wire together nodes to create flows. In this case, 3 nodes create our first flow. Real-world events, e.g. a tweet with the #led hashtag, are converted to messages, which ‘flow’ along the wires between the nodes. Nodes process messages on their input and, as a result, send messages on their outputs to the next node in the flow. In this simple example, we look for a tweet with hashtag #led and use it to trigger a message to a Raspberry PI node that cause IO pin 12 to go high for 1 second, which in turns causes a LED to blink on for 1 second.

振り返ってみましょう。Node-RED はフロー・ベースのプログラミング・ツールで、視覚的なエディターをもっています。これによってノードをつなげて、フローを作成します。この例の場合は、3つのノードをつなげてフローを作成しました。実際の世界の変化が、ここでは#ledをもったツイートが、メッセージに変換され、結線されたノードの間を流れて=flowしていきます。NodeはInputに来たメッセージを処理し、アウトプットからメッセージをだし、それがフロー上の次のノードに渡されます。このシンプルな例においては、#ledをもつツイートを探しました。そしてラズパイ用のノードに送るメッセージをトリガーして、IO ピンの12番めを1秒ハイにすることで、LEDを1秒点滅させました。

This example – and the rest in this lecture – are mostly to show you the kinds of things we can do with Node-RED. If you want to play around with the example, you should look at lecture 2 to see how to setup an account with FRED (the cloud based Node-RED service we use) and how to get started. You can find the node-red description of this flow at:

この例、それから今後のレクチャーで用いられる例は、うまくNode-REDできることを伝えています。実際にNode-REDで作業をしたいのであれば、レクチャー2を参考にして、FRED(クラウドベースのNode-REDサービスです)のアカウントを設定して、はじめていきましょう。このフローの説明は次のリンクから確認できます。

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson1/1-1_twitter.json

例1.2 Node-REDを使ってトレーニングの予定を守らなかった時にアラートを鳴らす

Example 1.2 Using Node-RED to alert you when you’re falling behind on your exercise schedule

Our second example shows a different usage of Node-RED. Rather than controlling a device such as a Raspberry PI, this flow combines weather info and your fitbit usage to send you an email alert when the weather is good and you’re behind on your exercise schedule. The flow is a little more complicated, using 6 nodes (see Fig 1.2), but again, by using built-in nodes you can accomplish complex tasks with little or no programming.

付きの二つ目の例は、Node-REDの先ほどとは少し異なった使い方を示しています。ラズパイのようなデバイスをコントロールするのではなくて、このフローは天気情報とfitbit(訳注:フィットネス向けのアップルウォッチのようなウェアラブルデバイス、及び関連サービス)をつなげて、天気が晴れなのに、エクササイズをしていない時に、アラートメールを送ります。このフローは、少し複雑で、6つのノードを使います。しかしもとから用意されているノードを使うので、複雑なタスクを最小限にしてくれますし、もっといえばプログラミングのする必要もありません。

Figure 1.2 A simple flow to alert you when you are not exercising and the weather is good

As before, nodes are dragged from the node palette in the Node-RED UI and wired together on the flow canvas. Starting at the leftmost node, let’s begin with an openweather node which you can configure to check the weather for any major city at set intervals. When it checks, it packages up the results in a message which is forwarded to the next node, in this case, to a switch node. The switch node performs a simple test, checking the input message for a value and sending a message with a value of “1” if the test is true. In our case, it’s been configured to test the temperature value (tempc) to see if it’s 15 degrees celsius or higher.

先程と同じように、ノードをノードパレットからドラッグ・アンド・ドロップして、それをつなげていきましょう。一番左のノードから始めましょう。これは openweather ノードで主要な都市の天気を設定した間隔で確認することができます。確認をしたときに、その結果をメーセージにまとめあげて、次のノードに渡します。このケースではswitchノードです。switchノードは簡単な分析をします。つまり、Input送られてきたメッセージの値をチェックして、分析がtrueなら、値が1のメッセージを送信します。このケースでは、気温が(tempc)が15度以上であるかどうかを分析するように設定されています。

When the switch node tests to true, or ‘switches on’, it sends a message onto the fitbit node which is the next node in the flow. The fitbit node is another powerful built-in node that you can configure to get statistics on your fitbit device from the fitbit.com portal. The fitbit node packages the statistics for your device into a message and forwards it to the next node in the flow.

switchノードのテスト結果がtrueの場合には、「スイッチオン」になり、フローの次のノードにあるfitbitノードにメッセージを送ります。fitbitノードも最初から組み込まれている強力なノードで、fitbit.comポータルから、あなたのデバイスの情報を取得することができます。fitbitノードはその情報をパッケージにして、次のノードにメッセージとして送ります。

The next node is another switch node. This one has been configured to check if the number of steps you’ve walked today is less than 1000. It does this by testing to see if the fitbit data field, summary.steps, is less than 1000. Remember, it just got these statistics in a message from the fitbit node, which in turn got them by making a call to the fitbit API on fitbit.com.

次のノードもスイッチノードです。これは。今日あるいた歩数が1000より少ないかどうかをチェックします。fitbitデータのうち、summary.stepsの値をあっクニンして、1000より少ないかどうかを判断します。ここではあくまでfitbitノードから受け取った値を分析しているだけで、fitbit.com のAPIにアクセスしているのはfitbitノードです。

If you have walked less than 1000 steps today, then the switch node generates a message that is passed on through the flow to a function node. The function node is a generic all-purpose node that allows you to write your own programming logic in Javascript. This node will be discussed in more detail in the next lecture. For now you can assume that this node just creates a new message with an email subject line and a text body that can be sent by email.

もし今日1000歩歩いていなければ、スイッチノードはメッセージを作成し、次のファンクションノードに渡されます。ファンクションノードは、JavaScriptでロジックを自分で書くことができる、様々な目的のために使われるノードです。これについては次のレクチャーでより説明します。さしあたってここでは、このノードは単に新しいEメールのタイトルと、Eメールで送る内容をtext bodyとしてもったメッセージをつくっていると理解しておいてください。

Once this message is created within the function node, it is sent through the flow to the final node which is an email node. This node will take the body of any incoming message and send it to the email account configured when the node is initialized. In this case, you’d set it up to send a message to yourself.

このメッセージがファンクションノードの中で作られると、最後のノードに送られます。Emailノードです。このノードは、受け取ったメッセージのbodyをもとに、Eメールを設定されたアカウントに送ります。ここではあなた自身に送られるようにしておきます。

So again, a very simple flow that uses the power of Node-RED’s built-in nodes to check your local weather. And if it’s reasonably warm and you haven’t done much walking today, it sends you an email reminder.

振り返ってみましょう。とてもシンプルなフローですが、Node-REDが予め用意した便利なノードを使って天気をチェックします。そして温度がそれなりに暖かい日で、しかもあなたが今日十分に歩いていない場合には、リマインダーメールが送られます。

Although the example seems quite simple, just checking the weather and your fitbit activity, you can use similar flows to check the status of home devices, of computers in your server farm, of devices in a factory, etc., and you can then use output nodes to send mail, tweets, make API calls to back-office software, control real world devices – in fact the choices are endless. Node-RED is an extremely powerful tool for wiring together inputs and outputs and offers many nodes, either built in or developed by the Node-RED community, to carry out an amazing range of tasks.

この例はとてもシンプルで、天気やfibitの状態をチェックするだけですが、同様なフローを使って、家にある機器や、サーバーにあるコンピューターや、工場のデバイス等々をチェックすることができます。そしてoutputノードを使って、メールを送ったり、ツイートをしたり、バックオフィスにあるソフトウェアのAPIをたたり、実世界のデバイスをコントロールしたりすることができます。その選択肢は無限です。Node-REDはInputとoutputをつなぐパワフルなツールです。そのためのノードは、最初から組み込まれているものもありますし、ユーザーコミュニティによって開発されたものもあります。それによって驚くほど広範囲の処理をこなしてくれるのです。

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson1/1-2_weatheralert.json

例1.3 Node-REDのHTTPノードを使って、シンプルなウェブサービスを構築する

Example 1.3 Building a simple web service using Node-RED’s built-in HTTP nodes

Our final example in this high-level introduction is yet another class of flows. It shows how to create a simple web service that responds to a browser sending a HTTP request by querying some real-world data, and then delivers a web page with a graphical representation of that data back to the browser – essentially Node-RED is being used to provide a web server and simple service all with a few nodes.

次の例は、ブラウザが送るHTTPリクエストによるリアルワールドの情報に対するqueryに応答する、シンプルなウェブサービスです。そしてデータをもとにしたグラフィカルな表示が含まれるウェブページを、ブラウザに返します。Node-REDはWebサーバを提供するためにも使えるので、シンプルなサービスであればかなり少ないノードで実現できます。

Sticking with the fitbit node introduced in the previous example, and this example creates a simple web service that allows you to query your fitbit stats for the day and, using a nice donut chart, display how many calories you’ve ‘burned off’ through exercise.

先程の例で紹介したFitbitノードをもう一度扱います。この例では、fitbitのその日の状態を問い合わせ、円グラフを使ってどれだけのカロリーを消費したかを示す、シンプルなアプリケーションを作ってみましょう。

The flow is shown in Fig 1.3 and consists of 4 nodes. The first and final nodes are http input and output nodes that work together to listen for HTTP requests and send HTTP responses. This flow listens for a HTTP request from any source, but let’s assume a regular browser here. When it arrives, it queries your fitbit stats from fitbit.com, then uses a template node to build a HTTP page, and passes that to the http output node which sends back the webpage to the browser.

次の図をみてください。4つのノードから構成されています。最初と最後のノードはHTTPに関するもので、outputとInputを担います。HTTPリクエストうけ、HTTPレスポンスを返します。どんなHTTPリクエストも受けることが出来るのですが、今回は一般的なブラウザからのリクエストを受けることにしましょう。HTTPリクエストが届くと、Node-REDはfitbit.comに問い合わせをして、fitbitの状態を取得します。そしてHTTPページを送信するためのテンプレートノードを使ってデータを作成し、それをHTTPoutputにわたし、そのウェブページをブラウザを介して返送します。

Figure 1.3 A simple web server example to graph fitbit data

Again, this is just to give you a sense of the power and flexibility of Node-RED without going into all the details of how this flow works. You’ll get to know more about that in later lectures. At a high level, the http input node has been configured to listen for HTTP requests on a URL, which is a combination of the hosting service that’s used in these lectures plus your login name {username} and the /fitbit string. This will be explained in more detail in lecture two.

振り返ってみましょう。HTTPInputノードは特定のURLへのHTTPリクエストを待ち受けます。これはホスティングサービスの名前と、それからユーザーネームと、fitbitという文字列から構成されています。これについてはレクチャー2で解説します。

When a HTTP request comes in, the http input node creates a message to trigger the fitbit node, which is the next node in the flow. The fitbit node gets the current statistics for the user, and then passes those statistics, as a message, to a template node. The html template node is another pre-built node in Node-RED, which, like the function node, allows you to build arbitrary code. However, rather than using JavaScript like the function node, the template node works with text such as HTML.

HTTPリクエストが送られてくると、HTTPインプットノードは、fitbitノードをトリガーするためのメッセージを生成します。fitbitノードは現在の状態を取得し、それをテンプレートノードにわたします。htmlテンプレートノードは、最初から用意されているノードの一つで、自由にコードをかくことができます。JSを書くことができるファンクションノードに似ていますが、テンプレートノードは、HTMLのような単なるテキストを作成するためにあります。

The HTML code in the template node is shown in Listing 1.1, so you can see what’s happening. However, there’s no need to examine it in detail if you don’t want to. Basically, the template node takes the calorie consumption data from fitbit and, using a 3rd party graphing library, creates a simple HTML file that will tell the receiving browser to use the 3rd party graphing library to display a donut chart of calorie consumption.

基本的にはテンプレートノードはカロリー消費のデータを受け取って、サードパーティーのグラフライブラリを使ってシンプルなHTMLファイルを作成し、そのファイルによってブラウザへ、ドーナッツを描画させているだけです。

Listing 1.1 A simple HTML template to display a donut chart of calorie usage

  1. <!doctype html>
  2. <head>
  3.     <title>A Node RED Example</title>
  4.     <link rel=”stylesheet” href=”//cdnjs.cloudflare.com/ajax/libs/morris.js/0.5.1/morris.css”>
  5.     <script src=”//cdnjs.cloudflare.com/ajax/libs/raphael/2.1.0/raphael-min.js”></script>
  6.     <script src=”//ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js”></script>
  7.     <script src=”//cdnjs.cloudflare.com/ajax/libs/morris.js/0.5.1/morris.min.js”></script>
  8. </head>
  9. <html>
  10.     <div id=”chart-example” style=”height: 250px;”></div>
  11.     <script>
  12.         Morris.Donut({
  13.            element: ‘chart-example’,
  14.            data: [
  15.              {label: “Activity Calories”, value: {{payload.summary.activityCalories}} },
  16.              {label: “Calories BMR”, value: {{payload.summary.caloriesBMR}} },
  17.              {label: “Calories Out”, value: {{payload.summary.caloriesOut}} }
  18.           ]
  19.        });
  20.     </script>
  21. </html>

Once the template node has generated the HTML file, it passes it as a message to the final node, which is a http response node. This node packages up the HTML as a HTTP response which it send back to the browser.

テンプレートノードがHTMLファイルを作成すると、それはメッセージとして最後のノード、HTTPレスポンスノードに渡されます。このノードがブラウザにレスポンスを返します。

The user will then see a simple donut chart of their calorie usage for the day (see Fig 1.4)  – all built and served by a simple Node-RED flow!

ユーザーはシンプルな円グラフによってこの日にどれだけのカロリーを消費したのかを確認することができます。全てNode-REDだけで作成され、そしてその上で機能しています!

 

 

Figure 1.4 A donut chart, served up by Node-RED showing calorie counts from fitbit

 

You can find the node-red description of this flow at:

https://raw.githubusercontent.com/SenseTecnic/nrguideflows/master/lesson1/1-3_webservice.json

The History of Node-RED

読めばわかる。ということで翻訳パス。

As the examples in the previous section have shown, Node-RED is a powerful tool for building IoT applications and services. Its genesis was triggered exactly by this need to rapidly prototype IoT applications and Node-RED was created as an open source project by the IBM Emerging Technologies group, in particular by two researchers, Nick O’Leary and Dave Conway-Jones. They created Node-RED initially as a tool for themselves as they were working on IoT projects and were “looking for a way to simplify the process of hooking together systems and sensors when building proof-of-concept technologies for customers.”

An initial version of Node-RED was released as an open source project in late 2013 and built up a small but active user and developer group during 2014. At the time of writing, Node-RED is still an emerging technology, but has already seen significant adoption by makers, experimentalists and a number of large and small companies experimenting with using it for their needs.

Today there is a vibrant user and developer community, with a core group working on the Node-RED code itself and most developers contributing nodes or flows to the flow library. You can check out the mailing list and github repositories using the links provided in Appendix A or just google them.

Since Node-RED is still a rapidly evolving technology, be aware that things can change quickly. These lectures were written against the 0.11.0 release of Node-RED and the examples will be updated as Node-RED evolves. However, it’s always wise, as with any new technology, to check compatibility if things aren’t working the way you expect.

Node-REDとIoT

Node-RED and the IoT

When the IBM folks created Node-RED, they were mostly focused on the Internet of Things, i.e connecting devices to processing and processing to devices. As a tool for rapid application development for the IoT, Node-RED is both powerful and flexible. Its power comes from a combination of two factors:

IBMのメンバーはNode-REDを作ったときには、IoTにフォーカスしていました。つまりデバイスをプロセスにつないだり、プロセスをデバイスにつなげるという使用方法です。IoTのための迅速なアプリケーション開発ツールであるので、Node-REDはパワフルであり、フレキシブルです。その強みは、次の2つの要素の組み合わせによってもたらされています。

  • Node-RED is an example of a flow-based programming model – messages representing events flow between nodes, triggering processing that results in output. The flow-based programming model maps well to typical IoT applications which are characterised by real-world events that trigger some sort of processing which in turn results in real-world actions. Node-RED packages these events as messages which offer a simple and uniform model for events as they flow between nodes that make up the flows.
  • Node-REDはフローベースのプログラミングモデルを採用しています。つまり、メッセージはイベントを表しており、これがノードの間を伝わっていきます。そして処理をトリガーして、その結果がoutputにもたらされます。フローベースのプログラミングモデルは、典型的なIoTアプリケーションに上手く適合します。つまり実世界のイベントが、ある処理をトリガーし、そしてそれが順番に処理されていって、最後に実世界へのアクションという結果を生むアプリケーションです。Node-REDはこれらのイベントをメッセージへとまとめあげて、イベントをシンプルで単一モデルで扱うことができ、ノード間をこのメッセージを流していきます。これがフロウです。
  • The set of built-in nodes is the second part of the Node-RED story. By building a set of powerful input and output nodes, each of which hides much of the complexity of interacting with the real world, Node-RED offers developers powerful building blocks to allow them to quickly put together flows that accomplish a lot, without having to worry about the programming details.
  • パワフルなinput/outputノードを組み立てることで、実世界と連携するための面倒事のほとんどから遠ざけてくれ、開発者は素早く問題解決のためのフローを作成することができます。プログラミングの細かいことを気にする必要がありません。

These two factors make Node-RED a powerful tool for IoT application development. When combined with the flexibility to create and use nodes such as the function node, which allows the developer to quickly write arbitrary JavaScript, plus the Node-RED community, who are constantly creating and sharing new nodes, Node-RED is likely to be one of the main tools in the IoT developers toolbox.

この2つの要因によって、Node-REDはIoTアプリケーション開発のための強力なツールになります。JSで書けるより柔軟性の高いファンクションノードや、Node-REDコミュニティが提供するノードを使うことで、IoT開発者にとって主要なツールとなったのです。

However, Node-RED isn’t always the best tool for IoT application development. While powerful and flexible, it isn’t always the right solution. Some situations where Node-RED may not be the first choice include:

しかし、Node-RED は常にベストなツールとは限りません。パワフルでフレキシブルではありますが、常に最適な解決法ではありません。Node-REDが第一の選択肢に上がらない場合には、次のようなケースがあるでしょう。

  • Complex multi-function IoT applications. Node-RED excels at rapid application development and at acting as the glue for connecting events to actions, or sensors to actuators, if you like. However, when an application gets above a certain size, it becomes complex to visually program and manage through Node-RED. There are some features to help with this, e.g. sub-flows (see lecture 5), but eventually the UI becomes a bottleneck.
  • 複雑で複数の機能を持つIoTアプリケーションの場合。Node-REDは迅速な開発、それからイベントやアクションをつなぐための「のり」としての役割においては、他を圧倒しますが、アプリケーションの規模がある程度大きくなってしまうと、ビジュアル・プログラミングで扱うには複雑すぎ、Node-REDで管理をするのが難しくなってきます。もちろんこの問題をサポートする幾つかの機能はあります。例えばsub-flows(これはレクチャー5で扱います)などがありますが、しかしいつかはUIがボトルネックになるときがきます。
  • Flow-based programming is a programming model that is not always the most suitable for application development. In much the same way that certain programming languages excel at some tasks but not others, flow-based programming has its weaknesses. A good example are loops: Node-RED is cumbersome when handling loops.
  • フローベースのプログラミングは、アプリケーション開発にとって常に最適なモデルだとは限りません。あるプログラミング言語がある特定のタスクに向いていても、他のタスクについてはそうではないように、フローベースののプログラミング言語にも弱点があります。例えばループはNode-REDでは扱うのがとても面倒です。
  • Specific use cases. Flow-based programming is a general purpose model and not targeted or optimized for specific needs, for example Data Analytics or User Interface development. At the moment Node-RED has no specific support for these type of applications and no easy way to add such support. Obviously, because the underlying technology of Node-RED is JavaScript, you can leverage its capabilities for these needs. If want to use Node-RED to prototype something, one approach is to implement parts or all of your application in another language more suited to your task and use Node-RED for the overall control.
  • 特定のケース。フローベースのプログラミングは、汎用的な目的に使われるモデルであって、特定の目的のために最適化されていません。例えば、データアナリティクスやユーザーインタフェースの開発には向いていません。今のところNode-REDはこういった種類のアプリケーション開発をサポートしていませんし、それらの機能を追加するのも簡単ではありません。Node-REDはJavaScriptによってできているので、その能力を使うことでこういった問題に対処することはできます。Node-REDをプロトタイプの作成に使いたいのであれば、一つの方法として、アプリケーションでつかうパーツや、もしくはアプリケーション全体を、他のもっと適した言語で作成し、Node-REDは、全体をコントロールするためだけに使う方法があります。

Having said that, as has been shown in this lecture and will be demonstrated in the following lectures,  Node-RED is a powerful tool for a large number of IoT applications. As it evolves it will become both more sophisticated and more usable in a wider range of circumstances.

既に説明してきたように、Node-REDはかなり範囲の広いIoTアプリケーションにとってパワフルなツールです。進化続けてきたことで、様々な状況において便利で洗練された解決策を提供します。

Perhaps just as important, as you explore Node-RED in subsequent lectures, you will realise that although Node-RED’s roots are in the IoT, it is a tool that can be used to build a wide variety of applications, not just IoT applications. In fact, in these lectures you will see example of Node-RED being used for web apps, social media apps, back-office integration, IT task management, i.e. across the range of modern computing tasks.

Node-REDの続くレクチャーにおいて探求していくにつれてわかると思うのですが、Node-REDはIoTに軸足を持ちつつも、IoTだけではない、より広い範囲のアプリケーションをつくるためにも有効です。Node-REDをウェブアプリのために使ったり、SNSアプリのためにつかったり、バックオフィスの統合のために使ったり、ITタスクのマネジメントのために使うことができます。コンピューターを使っておこなわれるタスク全体をカバーします。

Our hope is that by the end of this lecture course, you will see Node-RED, as we do, as a flexible and powerful tool that can be used in many situations, both for prototyping but also for production level development.

このレクチャーを通して、Node-REDがフレキシブルで強力なツールであり、さまざまな状況で使うことができ、プロトタイプの作成にとっても、製品レベルの開発においても、有効であることが伝われば幸いです。

要約

Summary

In this lecture we’ve taken you through a high-level look at Node-RED. You’ve seen how Node-RED wires together building blocks, using a visual tool to rapidly create simple flows that actually carry out sophisticated real-world tasks. You’ve also learnt a little about the origins of Node-RED as a rapid application development tool for the IoT and how, as it has evolved, it’s now being used for a variety of tasks, not just IoT programming. Finally, we’ve discussed the limitations of Node-RED and indicated some areas where other languages and tools may serve you better. In the next lecture, we’ll start on some real programming and show you how to build your own flows using the basic nodes that Node-RED provides.

このレクチャーでは、Node-REDの概念について説明してきました。Node-REDはブロック同士を接続し、視覚的なツールをつかって速攻でシンプルなフローを作成し、洗練された方法で実世界のタスクを処理してくれます。またNode-REDの起源と歴史についても説明しました。IoTのためのツールで、迅速に開発するために生まれたのですそして今ではより広い範囲のタスクを処理するためにも使うことができ、IoTの範囲に留まりません。最後に、Node-REDの限界について検討し、一般的な他の言語やツールをもちいたほうがよいシーンについても考察しました。次のレクチャーでは、実際のプログラミングをしていきながら、フローを作成していきます。ここでは最初から組み込まれたノードを使っていきます。

WebStorm の設定を複数の端末で共有する

WebStorm の設定、例えばショートカットキーやエディター画面の色、等を Git で管理して、保存、参照することができます。現在の最新版、WebStorm 2017.1 には必要なプラグインが最初から入っています。

同期といってもローカルの設定を変更した場合に、それがリモートのリポジトリに勝手に反映されるのではないようです。ローカルでの変更をリモートのリポジトリに反映させたい場合には、File → Setting Repository から Overwrite Remote してあげればいいようです。

なので運用としては、常にローカルの設定をリモートと同期させておいて、ローカルで設定変更をしたら、それをリモートにプッシュ。でいいのではないでしょうか。

https://www.jetbrains.com/help/webstorm/2017.1/settings-repository.html

Sharing Your IDE Settings

On this page:

Introduction

WebStorm allows you to share your IDE settings between different instances of WebStorm (or other IntelliJ platform-based) products installed on different computers.

WebStorm は、複数の異なるコンピューターにインストールされていても、その設定を共有することができます。

This is useful if you are using several WebStorm installations, or want to implement the same settings among your team members or company-wide.

この機能は次の場合に有用です。例えばウェブストームを複数のパソコンにインストールしている場合や、同じ設定をチームメンバーや会社で共有したい場合です。

Prerequisites

 

Before you start working with Settings Repository, make sure that the Settings Repository plugin is enabled. The plugin is bundled with WebStorm and is activated by default. If the plugin is not activated, enable it on the Plugins page of the Settings / Preferences Dialog as described in Enabling and Disabling Plugins.

設定保存用のレポジトリでの作業をするまえに、まずは Setting Repository プラグインが有効になっていることを確認してください。このプラグインはウェブストームに最初から含まれており、初期設定で有効になっています。もし有効になっていなければ設定画面のプラグインページで有効にしてください。

Configuring settings repository

If you want to share your IDE settings, perform the following steps:

IDE の設定を共有するためには、次の作業をおこなってください。

  1. Create a Git repository on any hosting service, such as Bitbucket or GitHub.  Git リポジトリを Bitbucket や GitHub といたホスティングサービス上で作成してください。
  2. On the computer where the WebStorm instance whose settings you want to share is installed, navigate to File | Settings Repository. Specify the URL of the repository you’ve created and click Overwrite Remote.
    共有したい設定がされているウェブストームがインストールされているパソコンで次の作業をします。File → Settings Repository → 設定を保存するためのリポジトリのURLを記入します。その上で Overwite Remote を選択して、リポジトリに上書きします。
  3. On each computer where you want your settings to be applied, in the Settings/Preferences dialog, expand the Tools node and choose Settings Repository, specify the URL of the repository you’ve created, and click Overwrite Local.You can click Merge if you want the repository to keep a combination of the remote settings and your local settings. If any conflicts are detected, a dialog will be displayed where you can resolve these conflicts.
    次に、保存した設定を適用させたいパソコンでは次の作業をおこないます。Settings/Preferences → Tools → 先程作り設定を保存したリポジトリの URL を設定します。そして Overwrite Local をクリックしてローカルの設定を上書きします。もしリモートリポジトリの設定と自分のローカルの設定との組み合わせにしたい場合は、Merge を選択します。それによってコンフリクトが発生した場合は、そのコンフリクトを解消するようにダイアログが表示されます。If you want to overwrite the remote settings with your local settings, click Overwrite Remote.
    ローカルセッティングをリポジトリに上書きしたい場合には Overwrite Remote を選択します。

    Your local settings will be automatically synchronized with the settings stored in the repository each time you perform an Update Project or a Push operation, or when you close your project or exit WebStorm.

    ローカルの設定は自動的にリポジトリに保存された設定と、次のタイミングで同期します。プロジェクトをアップデートした時、プッシュした時、プロジェクトを閉じた時、ウェブストームを閉じたときです。

If you want to disable automatic settings synchronization, navigate to File | Settings | Tools | Settings Repository and disable the Auto Sync option. You will be able to update your settings manually by choosing VCS | Sync Settings from the main menu.

設定の自動同期を無効にしたい場合は、File → Setting → Tools → Settings Repository から Auto Sync を向こうにしてください。その場合は、VCS → Sync Setting から手動で同期を行うことができます。

Authentication

On the first sync, you will be prompted to specify a username and password.

It is recommended to use an access token for GitHub authentication. If, for some reason, you want to use a username and password instead of an access token, or your Git hosting provider doesn’t support it, it is recommended to configure theGit credentials helper.

Note that the macOS Keychain is supported, which means you can share your credentials between all IntelliJ Platform-based products (you will be prompted to grant access if the original IDE is different from the requestor IDE).

Configuring a read-only source

Apart from the Settings Repository, you can configure any number of additional repositories containing any types of settings you want to share, including live templates, file templates, schemes, deployment options, etc.

These repositories are referred to as Read-only sources, as they cannot be overwritten or merged, just used as a source of settings as is.

To configure such repositories, do the following:

  1. In the Settings/Preferences dialog, expand the Tools node and choose Settings Repository.
  2. Click /help/img/idea/2017.1/add_icon.png and add the URL of the GitHub repository that contains the settings you want to share.

Synchronization with the settings from read-only sources is performed in the same way as for the Settings Repository.

ScrollMagic のドキュメントを翻訳する

http://scrollmagic.io/docs/index.html

ランディングページで多用される、スクロール位置でトリガーされるアニメーションを実装するために便利なライブラリ、ScrollMagic について学びます。

今回は上から全部翻訳するのではなく、必要な順番に進めていきました。

結果できたもの

https://codepen.io/nakanishi/project/full/ZBwaVX/

Getting Started : How to use ScrollMagic

まずは次の記事を読むことで基礎的な使い方を理解。

https://github.com/janpaepke/ScrollMagic/wiki/Getting-Started-:-How-to-use-ScrollMagic

How does ScrollMagic work?

ScrollMagic はどのように動作しますか?

The principle design pattern of ScrollMagic is a controller[1] that has an arbirtary number of scenes[2] attached to it.

ScrollMagic は基本的に、controller[1] と、それに紐付けられる任意の下図の scenes[2] から構成されています。

  1. There is one controller for each scroll container. In most cases there is only one controller object and the scroll container is the browser window. But you can also use DIV elements for scrolling and even have multiple containers on your page. The controller also defines which direction should be scrolled (horizontal or vertical) and is responsible for keeping all scenes updated.

スクロールするコンテナ毎にそれぞれ1個の controller をもつようにします。大抵のサイトでは、ブラウザ・ウィンドウ用に1つのコントローラーをもつことになります。他にもスクロールする複数の要素を保つ場合には、複数のコントローラーを用意し、それぞれのスクロールに対して ScrollMagic を使うこともできます。controller は、どちらの方向に(縦か横か)スクロールするかを定義することができ、?また全てのシーンを常に最新の状態で保持します。

  1. A scene defines what should happen when, meaning at which scroll position. It can trigger animations, pin an element, change element classes or anything else you might desire.

Scene は、何が、いつ(つまりどのスクロールポジションで)始まるかを定義します。scene はアニメーションをトリガーしたり、要素を固定したり、要素のクラスを変更したり、他にもなんでもできます。

Defining the Controller

コントローラーを定義する

As mentioned above in most cases the scroll container is the browser window. To create a ScrollMagic controller with the default settings we use the main ScrollMagic.Controller()class. We create a new instance of it and assign it to a variable, so we can reference it later:

既に述べたように、多くの場合は controller はブラウザ・ウィンドウ用に一つだけ作成する場合が多いでしょう。ScrollMagic の controller を初期設定の状態で作成するには、ScrollMagic.Controller() クラスを使用します。これを用いて新しいインスタンスを作成し、これに対して変数を与えます。変数については後述します。

var controller = new ScrollMagic.Controller();

That’s it! Now for the more interesting part:

これだけです。では続いて、ScrollMagic の面白いパートに進みましょう。

Defining Scenes

Scene を定義する

Scenes are created by using the ScrollMagic.Scene() class. A ScrollMagic.Scene defines where the controller should react and how. Here we define a variable called “scene” and we’ll create a new ScrollMagic.Scene() instance.

Scene は ScrollMagic.Scene() クラスを用いて作成します。ScrollMagic.Scene は、どの位置から controller が反応し、そしてどのような動作をするかを定義します。次のコードで、scene という名前の変数を指定し、その中に ScrollMagic.Scene() で作成した新しいインスタンスを代入しましょう。

var scene = new ScrollMagic.Scene();

Inside ScrollMagic.Scene we can place an object of associated properties and values that are made available according to the docs
These options describe the behavior of our Scene and in order to figure out what value has what effect you can play around in the Scene Manipulation Example

ScrollMagic.Scene の中に、オブジェクトを配置することができます。このオブジェクトはプロパティと値を持ちます。どんなものが使用可能かは docs  を参照してください。これらのオプションでどのような挙動をシーンにさせるのかを定義します。どんな効果があるのかを Scene Manipulation Example で色々試してみてください。

var scene = new ScrollMagic.Scene({
  offset: 100, // start scene after scrolling for 100px
  duration: 400 // pin the element for 400px of scrolling
})

100px スクロールした後に scene をスタートさせて、400px スクロールするまで固定します。

Adding Scenes to Controller

Scene を コントローラーに追加する

In order to have the scenes react to the scrolling of the container we have to add our scene to the controller we defined at the very beginning…

scene をコンテナのスクロールに反応させるために、scene を controller に追加しなくてはいけません。そう、一番最初に定義した controller にです。

var scene = new ScrollMagic.Scene({
  triggerElement: '#pinned-trigger1', // starting scene, when reaching this element この要素にスクロールが到着したら、シーンを始めます
  duration: 400 // pin the element for a total of 400px 要素を400px固定します
})
.setPin('#pinned-element1'); // the element we want to pin 固定したい要素を指定します

// Add Scene to ScrollMagic Controller シーンを Controller に追加します
controller.addScene(scene);

If you desire multiple scenes at once you can pass them to the controller just as the example shows below:

一度に複数のシーンを追加したい場合には、次のように書くこともできます。

// Add Scene to ScrollMagic Controller
controller.addScene([
  scene1,
  scene2,
  scene3
]);

Instead of telling the controller what scenes to add you can also tell the scene to be added to a certain controller:

controller に対してどのシーンを追加するかを指定するのではなくて、シーンに対してどの controller に自分自身を追加するかを指定することもできます。

var scene = new ScrollMagic.Scene({
  triggerElement: '#trigger1'
})
.addTo(controller); // Add Scene to ScrollMagic Controller

var scene2 = new ScrollMagic.Scene({
  triggerElement: '#trigger2'
})
.addTo(controller); // Add Scene to ScrollMagic Controller

In the above example we’re using a technique called ”chaining” with the addTo(). If no Semicolon ends the line, we can continue adding ScrollMagic.Scene methods and ”chain” them together.

上記の例で、addTo()の部分でいわゆる「チェイニング」という技術を使っています。セミコロンが行の終わりにない場合には、ScrollMagic.Scene のメソッドを続けていくことができ、それによって連結していくことができます。

Next let’s start adding some animation to our scenes in the next Chapter: Tweens

Plugin: Velocity

ScrollMagic 単体よりも、Velocity.js と連携することでより多用なアニメーションを可能にすることが出来る。そのためのプラグインとメソッドについて。

http://scrollmagic.io/docs/animation.Velocity.html#Scene.setVelocity

This plugin is meant to be used in conjunction with the Velocity animation framework. It offers an easy API to trigger Velocity animations.

このプラグインは アニメーションのためのフレームワークである Velocity と連携するためのものです。これによって 簡単に Velocity のアニメーションをトリガーする API を使うことができます。

With the current version of Velocity scrollbound animations (scenes with duration) are not supported.
This feature will be added as soon as Velocity provides the appropriate API.

現在の Velocity のバージョンでは、scrollbound アニメーションは対応していません。(scene に duration を与えた場合) これは Velocity 側が適切な API を提供をしてくれれば、すぐに実現できます。

To have access to this extension, please include plugins/animation.velocity.js.

この拡張機能を使うには次のプラグインをインストールしてください。

Source:

(訳注:多分ここからも手に入る https://github.com/janpaepke/ScrollMagic/tree/master/scrollmagic)

Scene.setVelocity(elems, properties, options) → {Scene}

順番が逆になりますが、こちらのほうが重要なので。

Add a Velocity animation to the scene. The method accepts the same parameters as Velocity, with the first parameter being the target element.

Velocity アニメーションをシーンに追加します。このメソッドは Velocity と同じパラメーターを使うことができます。最初のパメーターは対象の要素になります。

To gain better understanding, check out the Velocity example.

より理解するために、次のサンプルを参照してください。Velocity example.

Parameters:

Scene.setVelocity(elems, properties, options) → {Scene}

Name Type Description
elems object | string One or more Dom Elements or a Selector that should be used as the target of the animation.

1つ以上の Dom 要素か、セレクタを指定します。これがアニメーションの対象となります

properties object The CSS properties that should be animated.

アニメーション用の CSS プロパティ

options object Options for the animation, like duration or easing.

アニメーションのためのオプション
例えば duration や easing

Source:
Returns:

Parent object for chaining. { Scene }

Example
// trigger a Velocity animation
scene.setVelocity("#myElement", {opacity: 0.5}, {duration: 1000, easing: "linear"});

Scene.removeVelocity(reset) → {Scene}

?あとで

Remove the animation from the scene. This will stop the scene from triggering the animation.

Using the reset option you can decide if the animation should remain in the current state or be rewound to set the target elements back to the state they were in before the animation was added to the scene.

Parameters:
Name Type Argument Default Description
reset boolean <optional> false If true the animation will rewound.
Source:
Returns:

Parent object for chaining. { Scene }

Example
// remove the animation from the scene without resetting it
scene.removeVelocity();

// remove the animation from the scene and reset the elements to initial state
scene.removeVelocity(true);

Plugin: addIndicators

http://scrollmagic.io/docs/debug.addIndicators.html#Scene.removeIndicators

This plugin was formerly known as the ScrollMagic debug extension. It enables you to add visual indicators to your page, to be able to see exactly when a scene is triggered.

このプラグインは以前 ScrollMagic debug extension と呼ばれていました。このプラグインを使うことで、ページにデバグ用のインジケーターを追加し、視覚的にシーンがいつトリガーされるのかを確認することができます。

To have access to this extension, please include plugins/debug.addIndicators.js.

Source:

 

new ScrollMagic.Controller(options)

Every ScrollMagic.Controller instance now accepts an additional option.
See ScrollMagic.Controller for a complete list of the standard options.

それぞれの ScrollMagic.Controller インスタンスは、追加オプションを受け取ることができます。受け取ることが出来るオプションの全リストは ScrollMagic.Controller をみてください。

Parameters:

Name Type Argument Description
options object <optional> Options for the Controller.

Properties

Name Type Argument Default Description
addIndicators boolean <optional> false If set to true every scene that is added to the controller will automatically get indicators added to it.

true を指定すると、このコントローラーに追加された全てのシーンに対して、自動的にインジケーターを表示するようになります。

Source:

Example

// make a controller and add indicators to all scenes attached
// コントローラーを作り、このコントローラーに追加される全てのシーンに対して、インディケーターを表示させる
var controller = new ScrollMagic.Controller({addIndicators: true});

// this scene will automatically have indicators added to it
// 次のコードで作成されたシーンは自動的にインディケーターが表示されます

new ScrollMagic.Scene()
               .addTo(controller);

triggerHook

http://scrollmagic.io/docs/ScrollMagic.Scene.html#constructor

これはシーンが持つことができるオプションの一つで、シーンのトリガー位置を微調整できる。( ここで試すといい http://scrollmagic.io/examples/basic/scene_manipulation.html )

triggerHook number | string  トリガーフックの持つことが出来るパラメーターは数字か文字列
デフォルトの設定は “onCenter”
Can be a number between 0 and 1 defining the position of the trigger Hook in relation to the viewport. 0から1までの数字を設定でき、これによってどの視線位置(ブラウザのどの位置)からトリガーを開始するかを指定する。

Can also be defined using a string: 次のように文字列で指定することもできる。

“onEnter” => 1 //これはブラウザの一番下の部分でスタートさせる
“onCenter” => 0.5 //これはブラウザの真ん中
“onLeave” => 0 // これはブラウザの一番上でスタート

// create a standard scene and add it to a controller
new ScrollMagic.Scene()
.addTo(controller);

// create a scene with custom options and assign a handler to it.
var scene = new ScrollMagic.Scene({
duration: 100,
offset: 200,
triggerHook: “onEnter”,
reverse: false
});

reverse

これも triggerHook と同じで、シーンが持つことができるオプションの一つで、スクロール位置を戻した時に、アニメーションを逆再生するかしないかを指定する。

boolean をとる
true が初期値
Should the scene reverse, when scrolling up? スクロールを戻した時に、アニメーションを逆再生させるかどうかを指定する。