JavaScript Components

Hyperstack gives you full access to the entire universe of JavaScript libraries and components directly within your Ruby code.

Everything you can do in JavaScript is simple to do in Opal-Ruby; this includes passing parameters between Ruby and JavaScript and even passing Ruby methods as JavaScript callbacks.

For more information on writing Javascript within your Ruby code...

Importing Javascript or React Libraries

Importing and using React libraries from inside Hyperstack is very simple and very powerful. Any JavaScript or React based library can be accessible in your Ruby code.

Using Webpacker there are just a few simple steps:

• Add the library source to your project using yarn or npm

• Import the JavaScript objects you require

• Use the JavaScript or React component as if it were a Ruby class

Here is an example using the Material UI library:

Firstly, you install the library:

yarn add @material-ui/core

Next you import the objects you plan to use:

// app/javascript/packs/client_and_server.js

// to import the whole library
Mui = require('@material-ui/core')
// or to import a single component
Button = require('@material-ui/core/Button')

Theoretically webpacker will detect the change and rebuild everything, but you might have to do the following:

bin/webpack # rebuild the webpacks
rm -rf tmp/cache # clear the cached sprockets files

Now you can use Material UI Components in your Ruby code:

# if you imported the whole library
Mui::Button(variant: :contained, color: :primary) { "Click me" }.on(:click) do
  alert 'you clicked the primary button!'
end

# if you just imported the Button component
Button(variant: :contained, color: :secondary) { "Click me" }.on(:click) do
  alert 'you clicked the secondary button!'
end

Libraries used often with Hyperstack projects:

• Material UI Google's Material UI as React components
• Semantic UI A React wrapper for the Semantic UI stylesheet
• ReactStrap Bootstrap 4 React wrapper

Making Custom Wrappers - WORK IN PROGRESS ...

Hyperstack will automatically import Javascript components and component libraries as discussed above. Sometimes for complex libraries that you will use a lot it is useful to add some syntactic sugar to the wrapper.

This can be done using the imports directive and the Hyperstack::Component::NativeLibrary superclass.

Importing Image Assets via Webpack

If you store your images in app/javascript/images directory and want to display them in components, please add the following code to app/javascript/packs/application.js

webpackImagesMap = {};
var imagesContext = require.context('../images/', true, /\.(gif|jpg|png|svg)$/i);

function importAll (r) {
  r.keys().forEach(key => webpackImagesMap[key] = r(key));
}

importAll(imagesContext);

The above code creates an images map and stores it in webpackImagesMap variable. It looks something like this

{
     "./logo.png": "/packs/images/logo-3e11ad2e3d31a175aec7bb2f20a7e742.png",
     ...
}

Add the following helpers to your HyperComponent class

# app/hyperstack/helpers/images_import.rb

class HyperComponent
  def self.img_src(file_path)  # for use outside a component
    @img_map ||= Native(`webpackImagesMap`)
    @img_map["./#{file_path}"]
  end
  def img_src(file_path) # for use in a component
    HyperComponent.img_src(file_path)
  end
  ...
end

After that you will be able to display the images in your components like this

IMG(src: img_src('logo.png'))               # app/javascript/images/logo.png
IMG(src: img_src('landing/some_image.png')) # app/javascript/images/landing/some_image.png

jQuery

Hyperstack comes with a jQuery wrapper that you can optionally load. First add jQuery using yarn:

yarn add jquery

then insure jQuery is required in your client_only.js packs file:

// app/javascript/packs/client_only.js
jQuery = require('jquery');

finally require it in your hyper_component.rb file:

# app/hyperstack/hyper_component.rb

require 'hyperstack/component/jquery'

You can access jQuery anywhere in your code using the jQ method. For details see https://github.com/opal/opal-jquery

Note most of the time you will not need to manipulate the dom directly.

The dom_node method

Returns the HTML dom_node that this component instance is mounted to. For example you can use dom_node to set the focus on an input after its mounted.

class FocusedInput < HyperComponent
  others :others
  after_mount do
    jQ[dom_node].focus
  end
  render do
    INPUT(others)
  end
end