Surplus offers a faster, simpler approach to Reactive web app development than React.

Intro

This is a JavaScript webapp using Surplus and S as a development framework with no other libraries or platforms. It’s modular with purely functional components. No classes, and no this or new anywhere. It’s all built from scratch.

This small app is not just a demo, but a working SPA with complete documentation and source code. It has asynchronous resource loading, image prefetch and cache, touch event handling and dynamic bilingual language selection for all menus and text across the app. This document is best read while looking at the live app. Note that I wrote the app, but not the content other than some editing.

My goal was to make a simple, fast and mobile-friendly reactive app without any server code. The result is 403 lines of source code, (excluding comments and text files), in 16 ES6 modules. After compression, the app bundle is about 25K, not gzipped.

It’s not an S tutorial, but shows the power of S for tracking and updating data bindings in the DOM, and Surplus as a component framework. Take a look at S and Surplus on Github.

S and Surplus

S and Surplus are written by Adam Haile, and are separate projects on Github that work together.

S (aka S.js) is for reactive programming in JavaScript. When data changes, “S automatically updates downstream computations” says the Github page.

Surplus adds JSX web views to S applications, according to its docs. To me, it looks like a less complex React with better functionality and can be a first-rate development framework.

S.js

The idea behind S is wonderfully simple. There is no virtual DOM, but data changes are tracked and the real DOM is updated accordingly. S implements data binding with functions that use data signals, rather than using variables. When a value is changed, signals are sent to all components that depend on the value and are automatically updated.

This is a big deal because it greatly simplifies building and understanding an app. Component lifecycles are gone. No mounting/unmounting of components, because there is nothing to mount. It’s just the DOM. It’s like React with a whole unnecessary middle layer removed and replaced with something better.

Troubleshooting using the Chrome debugger is easier, because there’s no magic between what the debugger sees and the DOM. There are no synthetic events or component lifecycle changes. All components can be purely functional.

Surplus

Surplus uses JSX to create Components that use S, and has React-friendly keyword aliases and conventions. This is another big plus for learning and portability. It’s a React lookalike, but not a workalike. Load times are quick (important for mobile), memory footprint is small and it consistently runs the fastest benchmarks of any platform.

Hello World → Hola Mundo

There are nine S.data() functions in the app, used for modal and navbar display states, indexes into data arrays, file names, and CSS property values. When a new value (data signal) is passed to one of these functions, S data binding updates any DOM properties that depend on them, in all components.

This example (and this whole app) barely hints at the computational power of S. Using S to update elements by referencing a single value is as simple as can be.

For example, one S.data() value is used to index into dozens of JavaScript arrays that contain text strings like so:

const langIndex = S.data(0) // S returns a function initialized to 0
console.log(langIndex()) // 0 <- returns its value if no parameter passed.
const someText = ['hello ','hola ']
const otherText = ['world','mundo']
// JSX div displays text from array.
<div>
  {someText[langIndex()]} {/* 0 index == 'hello '*/}
  {otherText[langIndex()]} {/* 'world' */}
</div> // div element's text node is 'hello world'
...
langIndex(1) // DOM updates, now displays 'hola mundo'

Notice the C-style comment inside braces. This is a way to put comments within JSX, and is not Surplus-specific.

langIndex is a monad used to get (and change) the language index dynamically throughout the app. Wherever it’s used inside a component or element, S adds the element as a subscriber internally. When the value inside the monad changes, each subscriber is notified and the element is updated. This is the ‘reactive’ part of the app.

Changing this index results in an display update in every DOM element that uses the index to get a string value. This can be a text node, a CSS class value, an href string or anything else. My trivial example shows one div, but if a hundred elements depended on this index, they would all change. The langIndex() is S, and the div in JSX is Surplus.

Because there is no virtual DOM, there are no Component Lifecycles, and no Synthetic Events. There are Components that, like React, start with a capital letter. For compatibility with React, keywords like className and onClick are aliased, but need not be. props are passed in the same way as React. Native DOM event handlers, classes, properties etc. work with Surplus components seamlessly.

Surplus components look like the pure functional components in React and Inferno. JSX is a standard separate from React which Surplus follows.

What is this App?

It’s a website for a local church. The users like up-to-date status and info, and pictures of events. Half of the parish speak Spanish, so every label, message, dropdown, menu, etc. is bilingual using the string array indexes described above, plus separate content files. The live version can be seen at stleotx.org. The app could easily be adapted to any community organization.

I inherited a Network Solutions server which doesn’t run node, so all code runs on the client. I wanted to provide a website for the parish, to demonstrate S and Surplus, and have a public-facing open source app as an example of my work. It’s a successor to a previous version I wrote using AngularJS, and I started this version’s development using React, then Inferno, then Surplus.

It has standard dropdown menus, a sidenav bar, header, footer, modals, event calendar and a picture slideshow. There are 16 Components, each in a separate ES6 module. Other JavaScript files have text data and there is a directory in each language for html and text content files. A gallery directory has jpg pictures. A util directory has some helper scripts for generating html files from templates, and for building this document from Markdown files in the doc directory.

App.css was written by me from scratch, except where noted. Much of my effort went into this, but details are outside of the scope of this document.

Development environment

I use standard command line and scripted JavaScript developer tools, like git, npm, webpack with babel, bash and others. The package.json and webpack.config.js should look familiar to any modern developer.

Emacs is my IDE. Emacs does everything an IDE does if it’s setup right.

I use the web-mode Emacs package for html, js, jsx, css files along with aggressive-indent-mode. They both understand mixed modes like embedded JSX and CSS in HTML. Add fly-check, and you’ll have automatic indenting and formatting, syntax highlighting and error checking all on the fly. Check out emmet-mode too for shortcut tag generation in JSX and HTML.

I use Arch Linux on a Lenovo W520. I also have a MacBook Pro, which my wife says I can use after I pry it from her cold, dead fingers, but she tests my stuff with it along with her iPhone, iPad, etc. I’ve been using Linux since before kernel version 1.0 when Linus Torvalds was still a grad student and usenet was the thing. Unix before that.

I’m not a Windows developer, and development using node command line tools on Windows is not my specialty. Google and StackOverflow should help if you prefer Windows for development.

Source Code

index.html

The root node is appended to the document body in a minimal index.html, which also sources bundle.js and App.css. Webpack and babel with plugins and presets create bundle.js from all JavaScript in the app, compressed.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="theme-color" content="#000000">
    <link rel="manifest" href="./manifest.json">
    <link rel="shortcut icon" href="./favicon.ico">
    <link href="./App.css" rel="stylesheet"/>
    <title>St Leo Centerville TX</title>
  </head>
  <body>
    <noscript>
      You need to enable JavaScript to run this app.
    </noscript>
    <script src='./bundle.js'></script>
  </body>
</html>

Modules

App.js

App is the entry point and does little else other than import component modules, and create an S root node. The components and their ordering create the main display page, which in this Single Page Application is the whole app (most of which is hidden at this point).

Modules and Components

Though the app is made of purely modular components, most were isolated from other code as my development evolved. Eventually, everything became a module with a purely functional component in it.

With a more complex app, I’d create an index.js module that imports and exports these components, but no need here.

There are more components than these seven. These are the top level components, out of 15 in all.

All components in my app are ES6 modules, in addition to modules that are not components, such as objects with text arrays.

App.js

import S from 's-js'
import * as Surplus from 'surplus'
import TopNav from './TopNav.js'
import Header from './Header.js'
import Intro from './Intro.js'
import Pictures from './Pictures.js'
import News from './News.js'
import Events from './Events.js'
import Footer from './Footer.js'
/**
   It all starts here. The entry point to the application. Index.html
   will import the bundle that contains this, and provide the document
   body that this appends as a child.

   The top level components are introduced here. Order is important!
 */
let view = S.root(() =>
  <div className='App'>
    <div className='main'>
      <TopNav />
      <Header />
      <Intro />
      <Pictures />
      <News />
      <Events />
      <Footer />
    </div>
  </div>
)
document.body.appendChild(view)

langIndex.js

This monad is used by every component that displays text in more than one language. The langIndex data stream provides an index into text arrays. When it changes, all displayed text changes too. Magic! Well, S data binding magic anyway.

Compare this to React Component’s setState(). With React, each component has its own state, and its child components only update theirs if forceUpdate is passed to setState. Here, any component can use langIndex simply by importing it. S takes care of the data binding. [Update: I see React’s context is now un-deprecated.]

The toggleLang function does what it says. It’s invoked from the TopNav menubar at the rightmost position.

langIndex() is used by most other components.

This is not a component, but just a module with exports. Note that it starts with lower case, which Surplus uses to distinguish between Components (upper) and Elements (lower), like React. In this case, it’s neither, but Surplus won’t treat it as a Component.

langIndex.js

import S from 's-js'
export const langIndex = S.data(0) // Initialize to English as default.
export const toggleLang = () => {
  langIndex() === 0 ? langIndex(1) : langIndex(0)
}

TopNav.js

This is a relatively simple Top Navigation bar, or rather a misnamed menubar. Since I have other menus in another context I’ll leave the name as is.

An important aspect of this component is its fixed position placement at the top of the page as set in App.css. The SideNav and ModalBase components are children of TopNav to take advantage of this fixed position, even though they are unrelated otherwise, and hidden until opened.

The background is initially transparent, but when a non-contrasting background underneath scrolls under it, the text would be obscurred. To prevent this, a more opaque style is added when the underlying window is scrolled up more than 30px, and removed when not.

The window.addEventListener event handler is plain old JavaScript and DOM. Platforms with virtual DOMs like React can’t do this directly, but Surplus doesn’t get in the way.

Menu elements use onClick to act as buttons, and either produce dropdown menus or invoke actions.

TopNav takes text for menu names and content from textStrings. As in the “hello world” example, there is an object key with an array of strings. langIndex() selects the text to display. This pattern is repeated thoughout the app.

The SideNav component exports a function that controls its visibility, called displayState which is controlled by the hamburger menu icon. It opens or toggles this display with openSide() and toggle() functions.

Another important toggle is the li element that controls toggleLang(), a function imported from langIndex.js which also exports the S data function langIndex(). A click on this element changes all displayed text to another language.

TopNav.js

import * as Surplus from 'surplus'
import {textStrings as txt} from './textStrings.js'
import {langIndex, toggleLang} from './langIndex.js'
import Dropdown from './Dropdown.js'
import SideNav, {displayState} from './SideNav.js'
import ModalBase from './ModalBase.js'

// Give topNav some opacity when scrolled down past 30px.
window.addEventListener('scroll', () => {
  if (window.scrollY > 30) {
    document.getElementsByClassName('topNav')[0].className = 'topNav opaque'
  } else {
    document.getElementsByClassName('topNav')[0].className = 'topNav'
  }
})
const toggleSide = () => {
  displayState() === 'block' ? displayState('none') : displayState('block')
}
/**
   TopNav is fixed at the top of the page, so it acts an an anchor to
   Components that don't scroll with the rest of the page content.  It
   has a dual purpose, one being a navbar displayed at the top of the
   page, and the other anchoring dropdown menus, as provided by
   its child component Dropdown with parameters and children.
 */
export default function TopNav () {
  return (
    <nav className='topNav'>
    {/* Horizontal menu, starting with the hamburger 'button'. */}
    <ul>
      <span className='menu' onClick={toggleSide}>
        <li className='burger dropbtn' >☰&nbsp;</li>
      </span>
      <li>
        {/* Dropdown children invoke modals on selection. */}
        <Dropdown name={txt.masstimes[langIndex()]}>
          {/* size is the width of the modal invoked. Mobile displays will
              override this value in Listings.js and MenuItem.js */}
          <content size='50%'>sundaymass</content>
          <content size='50%'>weekdaymass</content>
        </Dropdown>
      </li>
      <li>
        <Dropdown name={txt.aboutUs[langIndex()]}>
          <content size='60%'>about</content>
          <content size='60%'>aboutLeo</content>
        </Dropdown>
      </li>
      {/* This toggles the entire site's language content. It's always displayed. */}
      <li className='dropbtn' title={txt.toggle[langIndex()]} onClick={toggleLang}>{txt.language[langIndex()]}</li>
    </ul>
    {/* SideNav menubar is hidden until invoked. */}
    <SideNav />
    {/* Hidden until invoked. ModalBase is here for display fixed anchor point. */}
    <ModalBase className='modal' />
  </nav>)
}

Dropdown.js

TopNav uses this for creating a list of dropdown menus in its menubar.

The text label is passed in from TopNav as props.name.

Any number of children are passed from TopNav as content nodes. Each child becomes a MenuItem.

Each content node is a props.textContent string that is passed to MenuItem. MenuItem uses the string both as a property key from labeledText to get a label, and as a file name for the modal text content. See MenuItem for details.

A clicked menu item displays a Modal, and Modal width is passed as props.size. This width will be overridden for small screens like mobile devices.

Dropdown.js

import * as Surplus from 'surplus'
import MenuItem from './MenuItem.js'
/**
   TopNav uses this for dropdown menus. Each child property is a MenuItem.
   Size (width) is optional from props. Otherwise the default is taken.
   Child content elements are used for each menu item of the dropdown,
   and the number is unlimited.
   See TopNav for details and examples.
 */
export default function Dropdown (props) {
  let content = <div className='dropdown-content' />
  // Fill in content element with child menus.
  if (props.children.length) {
    props.children.forEach(p => {
      if (p.size) { // Prop has a width parameter.
        content.appendChild(
          <MenuItem size={p.size}>{p.textContent}</MenuItem>
        )
      } else {
        content.appendChild(
          <MenuItem>{p.textContent}</MenuItem>
        )
      }
    })
  }
  return (
    <div className='dropdown'>
      <div className='dropbtn'>{props.name}
        {content}
      </div>
    </div>
  )
}

MenuItem.js

Used by TopNav and SideNav to create and display menu items.

The child text node passed in is used to display this component’s label, and is passed to FetchHtmlText to get a file for the modal’s display content.

Each instance of MenuItem gets its own click handler, which sets up modal properties and invokes the modal for display. Note that FetchHtmlText loads asynchronously before (hopefully) the element is clicked. If not yet loaded, the modal will display without text, but will fill in as it’s read.

The size prop determines the width of the modal unless overridden when a small screen width is detected.

MenuItem.js

import * as Surplus from 'surplus'
import {textStrings as txt} from './textStrings.js'
import {langIndex} from './langIndex.js'
import {displayModal} from './ModalBase.js'
import {modalTitle, modalMsg, modalWidth} from './Modal.js'
import FetchHtmlText from './FetchHtmlText.js'

/**
   Create menu items with click handlers for display.

   Props.children is a single word of text. This text has two uses:
   The menu title is displayed from textStrings.js using the label as
   a key, and FetchHtmlText to find the filename to fetch for display
   when the menu item is clicked.
 */
export default function MenuItem (props) {
  let label = props.children,
      size = props.size,
      title = txt[label],
      html = <FetchHtmlText>{label}</FetchHtmlText>,
      clickme = () => {
        if (window.screen.width > 760) {
          modalWidth(size)
        } else {
          modalWidth('98%')
        }
        modalTitle(title[langIndex()])
        modalMsg(html)
        displayModal('block')
      }
  return (
    <div className='menuitem' onClick={clickme}>
      {title[langIndex()]}
    </div>
  )
}

ModalBase.js

This serves as an anchor or placeholder for displaying Modal. It hides the modal initially by setting the displayModal function, which is used by the modal’s CSS display style property.

It creates a Modal child component, and sets several properties before returning it. The tabIndex property and focus function probably are not needed.

The node.style.width and node.style.display properties are set to S.data() streams so they will be updated automatically with their state changes.

ModalBase.js

import S from 's-js'
import * as Surplus from 'surplus'
import Modal, {modalWidth} from './Modal.js'

export const displayModal = S.data('none')

export default function ModalBase () {
  let node = <Modal />
  node.tabIndex = 1
  node.focus()
  node.style.width = modalWidth()
  node.style.display = displayModal()
  return (
    node
  )
}

Modal.js

There are several S.data() streams and CSS classes used by this component.

The obviously named close function uses the S stream displayModal from ModalBase, which sets the modal’s CSS display style to ‘none’.

The modalTitle and modalMsg data streams are initially empty, to be filled in by the Listings and MenuItem components when invoked.

The modalTitle div element has the Unicode ‘X’ close button and the title for this modal.

There is a placeholder for a footer which is currently unused.

Modal.js

import S from 's-js'
import * as Surplus from 'surplus'
import {displayModal} from './ModalBase.js'

const close = () => {
  displayModal('none')
}
export const modalTitle = S.data('')
export const modalMsg = S.data('')
export const modalWidth = S.data('40%')

export default () => {
  return (
    <div className='modal-content'>
      <div className='modal-header' onClick={close}>
        <div>{modalTitle()}
          <span onClick={close} className='closemodal'>{String.fromCharCode(215)}</span>
        </div>
      </div>
      <div className='modal-body'>
        <p>{modalMsg()}</p>
      </div>
      <div className='modal-footer' />
    </div>
  )
}

SideNav.js

The SideNav menu opens with the TopNav hamburger menu, and closes with its own clickable X div.

The myside variable holds the Surplus JSX nodes rather than returning the outer node directly. This is to allow properties of the outer node to be manipulated, such as the displayState().

The menu is made up of MenuItem components. Each MenuItem is given a size property which used by the modal that is invoked when selected. The child text node is used to select both the key in the labeledText object and filename to be read into the modal.

SideNav.js

import S from 's-js'
import * as Surplus from 'surplus'
import MenuItem from './MenuItem.js'

export const displayState = S.data('none')
const close = () => {
  displayState('none')
}
export default function SideNav () {
  let divStyle = {
    fontSize: '2em',
    padding: '0 0 0 0.3em'
  }
  let myside = <div className='sidenav'>
  <div />

  <MenuItem size='840px' >calendar</MenuItem>
  <MenuItem size='370px' >readings</MenuItem>
  <MenuItem size='60%' >pastors</MenuItem>
  <div><hr /></div>
  <MenuItem size='30%' >confession</MenuItem>
  <MenuItem size='30%' >adoration</MenuItem>
  <div><hr /></div>
  <MenuItem size='60%' >sick</MenuItem>
  <MenuItem size='60%' >troops</MenuItem>
  <MenuItem size='40%' >vocations</MenuItem>
  <div><hr /></div>
  <MenuItem size='40%' >gift</MenuItem>
  <MenuItem size='60%' >family</MenuItem>
  <MenuItem size='60%' >prayrosary</MenuItem>
  <div><hr /></div>
  <MenuItem size='40%' >knights</MenuItem>
  <MenuItem size='40%' >maidens</MenuItem>
  <MenuItem size='40%' >firstfriday</MenuItem>
  <div onClick={close} style={divStyle}>&times;</div>
  </div>
  myside.style.display = displayState()
  return (
    myside
  )
}

Header.js

Displays a header with a title and subtitle taken from textStrings.js. These change content when the langIndex() S data stream changes.

Header.js

import S from 's-js'
import * as Surplus from 'surplus'
import {textStrings as txt} from './textStrings.js'
import {langIndex} from './langIndex.js'

export default function Header () {
  return (
    <header className='App-header'>
      <h1 className='App-title'>{txt.title[langIndex()]}</h1>
      <h2 className='App-subtitle'>{txt.subtitle[langIndex()]}</h2>
    </header>
  )
}

Intro.js

The Intro component displays an introduction message taken from the welcome.html file in the selected language.

At first glance it would appear that the message doesn’t change when another language is selected, but it does because FetchHtmlText notices the langIndex() change.

Intro.js

import S from 's-js'
import * as Surplus from 'surplus'
import FetchHtmlText from './FetchHtmlText.js'

export default function Intro () {
  return (
    <div className='App-intro'>
      <FetchHtmlText>welcome</FetchHtmlText>
    </div>
  )
}

FetchHtmlText.js

Uses ES6 fetch to read text from a URI asynchronously. In this case the URI is a file, but it could be another resource.

A div node is returned, but its innerHTML is filled in as it is read from the HTTP response using fetch’s promise.

The langIndex() data stream function’s value is used to index the lang array, which has the directory name for the file to be fetched.

The HTTP request parameters prevent caching, as file contents are expected to change more often than fixed text strings.

The innerHTML is set dangerously (in React-speak) meaning that malicious content could come from an untrusted URI. Since we’re reading from our own files here, that’s unlikely. There are no condescending warnings about this. Sorry!

HTML tags in the fetched file are passed unmodified, so styling, etc. works fine.

FetchHtmlText.js

import S from 's-js'
import * as Surplus from 'surplus'
import {langIndex} from './langIndex.js'

export default function FetchHtmlText (props) {
  const lang = ['EN', 'ES'] // Directory names.
  let node = <div className='loadText' />
  fetch(`./${lang[langIndex()]}/${props.children}.html`,
        {cache: 'no-cache, no-store, must-revalidate'})
    .then(resp => resp.text())
    .then(text => node.innerHTML = text)
  return (node)
}

Pictures.js

This is a slideshow of pictures, with some interesting features. It’s the largest component in the app.

The image files

The imported filelist.js has an array of image filenames like:

export const filelist = [
    'somepic.jpg',
    'anotherpic.jpg',
    ...
]

These image files are in the gallery directory on the server. The code looks for file names in this filelist, and finds them in the directory. As image files are added, the filelist object must be edited manually, because JavaScript browser clients can’t read the server’s filesystem directory to construct the list.

Displaying an image the easy way

Displaying a jpg photo image is as simple as creating an img node and assigning a resource to its src, like so:

let mypic = <img/>
mypic.src = 'pictures/mypic.jpg'

Here mypic is a node on the browser, and mypic.jpg is a file that’s loaded over a network from the server.

The problem with this approach is that loading new images, which can be large, takes too much time for a mobile device on a slow network. Preloading images in the background before they’re displayed is better.

Prefetching images

Prefetching all images would be too much to handle, so I only use three. current, previous and next are Surplus nodes that will contain the images for display.

Properties on Surplus nodes may be added and modified directly, as in current.position = 'absolute'.

The nextPic() and prevPic() functions select a new picture as the user cycles through the filelist array by clicking on chevrons or swiping on touch-sensitive devices, and updating the array index picIndex(), which cycles through the array to make it seem circular to the user. The same is done for prevIndex() and nextIndex().

With each click (or swipe) a new image is loaded. But the trick here is that the newly loading image isn’t the one the user sees. The user sees an image that’s already loaded, while a new one is fetched asynchronously in the background.

The user can only select the previous or next image, as there is no option for random selection. Prefetching these two unseen images anticipates the user’s next selection in either direction. This forms a three image sliding window that moves across the array of pictures, with the oldest dropped, the newest preloaded, and the user viewing the one in the middle.

The users could easily outrun the prefetch, but hopefully they will spend enough time looking at the selected pic to allow the prefetch to catch up. Outrunning the prefetch doesn’t hurt, but clicking or swiping has no effect until the image is loaded.

The current, previous and next views are initialized to contain their respective images before any user interaction.

When nextPic() is invoked, the current.src image is copied to previous.src. We know that it’s already been loaded. In the same way, next image content is copied to current, and next.src is given new content by fetchPic(). The current node doesn’t change. Instead, current.src gets new content. Likewise with previous and next. The indexes for the three nodes are updated, and next has a new image loaded asynchronously in the background.

prevPic() is identical to nextPic(), except it cycles in the other direction.

fetchPic() does what it says, using ES6 fetch, which returns a promise. Note that the actual update is done inside this function closure after it returns. This allows the operation to work in the background, asynchronously.

When the page first loads, the user hasn’t yet selected an image, so nothing would be displayed without initialization. We initialize our three image nodes. The current image is loaded first, followed by the other two so that the user only has to wait for the first to see an image on startup.

Swipe event handler

For devices that support touch events, swiping to select previous and next images is convenient. Attaching the right event handlers to invoke prevPic() and nextPic() does the trick.

There are libraries like hammer.js that provide functions for this, but they also add lots of extra code for features I don’t need.

Chrome’s debugger let me examine events for clues about how to use them. Chrome on my Linux laptop doesn’t support touch events, but their debugger simulates them if a smartphone emulator is selected.

I use swipeStart() and swipeEnd() to capture the coordinates for the user action. A little diff helper tells me how far across the screen they swiped regardless of direction in the X coordinate. swipeEnd() is where things happen. The last line looks at the direction of the swipe to invoke the proper action.

I noticed that almost any touch will invoke an X coordinate change, which can lead to annoying picture changes while swiping up or down. To avoid this I ignore X coordinate changes smaller than an arbitrary pixel value picked by experimentation.

Attaching the touch event handler

When working with JSX it’s easy to fall for the illusion that you’re working with HTML, when in fact it’s all JavaScript. Some event handlers like onClick are effectively passed through, but others have to directly attached to a DOM node. I tried onTouch but it had no effect, so I went down a level of abstraction to capture the DOM event.

I always try to understand at least one level of abstraction below the one I’m using. It’s a good rule of thumb for all software development.

With Surplus (and other JSX implementations) this is done by creating a JavaScript variable and assigning a Surplus node to it, like so:

let foo = <div/>
foo.addEventListener(...)

So foo can invoke the addEventListener() function while a simple <div/> by itself could not. It’s still a Surplus node, but assigning it to a JavaScript variable lets us add and modify its properties. This is why the Picture component returns JavaScript rather than more readable JSX.

The original (before adding the touch events) code looked like this:

return(
    <div className='container'>
      <div className='picture'>
        <span id='previous'>
          <span onClick={prevPic} className='chevron left'></span>
        </span>
        <span id='next'>
          <span onClick={nextPic} className='next chevron right'></span>
        </span>
        {current}
      </div>
    </div>
)

I converted the JSX into a series of JavaScript variables containing Surplus nodes. The event listeners are then added to pic (with the element containing current), and the return node is constructed by appending child nodes so that it all behaves like the JSX shown above.

After converting to Javascript nodes and adding event listeners it looks like this:

// Construct the containing element, with event listeners.
let left = <span onClick={prevPic} className='chevron left'></span>, (1)
    right = <span onClick={nextPic} className='next chevron right'></span>,
    container = <div className='container'></div>,
    prespan = <span id='previous'>{left}</span>,
    nextspan = <span id='next'>{right}</span>,
    pic = <div className='picture'>{current}</div>

pic.addEventListener('touchstart',swipeStart) (2)
pic.addEventListener('touchend',swipeEnd) (3)

export default function Pictures() {
  pic.appendChild(prespan) // left chevron (4)
  pic.appendChild(nextspan) // right chevron (4)
  container.appendChild(pic)
  return(container) (5)
}

1	Each JSX element is now a node referenced by a variable.
2	The `touchstart` event handler has a node to attach to.
3	`touchend` has one too. Separate handlers for different events.
4	The clickable chevrons are for `previous` and `next` along with the touch events.
5	The `container` is just like the old JSX return node, but with added event handlers.

Pictures.js

import S from 's-js'
import * as Surplus from 'surplus'
import {filelist} from '../public/gallery/filelist.js'
/**
   Display a slideshow of photo images.
 */

// Init image elements and indexes into the picture file list.
let current = <img width='900' />,
  previous = <img />,
  next = <img />,
  picIndex = S.data(0), // Index to initial picture in array.
  nextIndex = S.data(1),
  prevIndex = S.data(filelist.length - 1)

current.position = 'absolute'
// Hander for right chevron or right swipe.
let nextPic = () => {
  picIndex() >= filelist.length - 1 ? picIndex(0) : picIndex(picIndex() + 1)
  previous.src = current.src
  current.src = next.src
  nextIndex(picIndex() >= filelist.length - 1 ? 0 : picIndex() + 1)
  // prefetch next pic
  fetchPic('./gallery/' + filelist[nextIndex()], next)
}
// Handler for left click or swipe.
let prevPic = () => {
  picIndex() <= 0 ? picIndex(filelist.length - 1) : picIndex(picIndex() - 1)
  next.src = current.src
  current.src = previous.src
  prevIndex(picIndex() <= 0 ? filelist.length - 1 : picIndex() - 1)
  fetchPic('./gallery/' + filelist[prevIndex()], previous)
}

let fetchPic = (name, node) => { // Pic filename, and node to load into.
  return (fetch(name, {cache: 'public, max-age=0'}) // Cache if possible.
    .then((res) => { return res.blob() })
    .then((myBlob) => {
      let url = URL.createObjectURL(myBlob)
      node.src = url
      node.alt = name // File name. A better alt text would be nice.
    })
  )
}
// Initialize current pic first, then others in the background.
fetchPic('./gallery/' + filelist[picIndex()], current)
  .then(fetchPic('./gallery/' + filelist[nextIndex()], next))
  .then(fetchPic('./gallery/' + filelist[prevIndex()], previous))

// Use swipe on devices that use touch events. Record swipe start, end.
let sStart = 0,
  sEnd = 0
let swipeStart = (e) => {
  sStart = e.touches[0].screenX
}
// End of swipe is where we decide action.
let swipeEnd = (e) => {
  sEnd = e.changedTouches[0].screenX
  if (diff(sStart, sEnd) > 45) { // ignore accidental changes
    sStart > sEnd ? prevPic() : nextPic() // swiped left or right?
  }
}
// Difference between start and end of swipe ignoring direction.
let diff = (start, end) => {
  let df = start > end ? start - end : end - start
  return df
}
// Construct the containing element, with event listeners.
let left = <span onClick={prevPic} className='chevron left' />,
  right = <span onClick={nextPic} className='next chevron right' />,
  container = <div className='container' />,
  prespan = <span id='previous'>{left}</span>,
  nextspan = <span id='next'>{right}</span>,
  pic = <div className='picture'>{current}</div>

pic.addEventListener('touchstart', swipeStart)
pic.addEventListener('touchend', swipeEnd)

export default function Pictures () {
  pic.appendChild(prespan) // left chevron
  pic.appendChild(nextspan) // right chevron
  container.appendChild(pic)
  return (container)
}

News.js

Displays a list of newsworthy items as clickable text. All of the real work is done by Listings.

Identical to Events.js except for some string content.

The news items come from newsStrings.js, which is manually edited for updated content along with matching text content files.

News.js

import * as Surplus from 'surplus'
import {textStrings as txt} from './textStrings.js'
import Listings from './Listings.js'
import {langIndex} from './langIndex.js'

export default function News () {
  return (
    <div className='news'>
      <div>
        <span className='title'>{txt.news[langIndex()]}</span>
        <hr />
        <Listings type='news' />
      </div>
    </div>
  )
}

Events.js

Displays a list of event items as clickable text. All of the real work is done by Listings.

These are social Events like dinners, not DOM events or the like.

Identical to News.js except for string content.

The event items come from eventsStrings.js, which is manually edited for updated content along with matching text content files.

Events.js

import S from 's-js'
import * as Surplus from 'surplus'
import {textStrings as txt} from './textStrings.js'
import Listings from './Listings.js'
import {langIndex} from './langIndex.js'

export default function Events () {
  return (
    <div className='events'>
      <div>
        <span className='title'>{txt.events[langIndex()]}</span>
        <hr />
        <Listings type='events' />
      </div>
    </div>
  )
}

Listings.js

Displays a list of News or Events. Since they share the same format, I use the same component for both by setting the correct object from the props.type.

This is much like other menus, except that it has some extra information to display. Because News and Events are so similar, they share this component.

First props.type is used to set newsEvents to contain the appropriate text objects. The newsStrings.js and eventsString.js are each object literals with a series of property keys having an array of strings.

A single div contains each listing as child elements.

The keys in the object file are iterated through, and an entry is made for each. Because each entry is clickable, it gets its own click handler. The click handler fetches its file content and displays a modal. Note that this doesn’t happen until the click, so there is no prefetch (unlike SideNav). If a second item is clicked while the modal is open, the same modal just displays new content rather than creating a new one.

The number of listings is determined by the number of keys in the object files, with no limit.

The text object files have four strings in each array, rather than two as seen in other text object files. This is for additional messages such as dates and notes. A numeric 2 is added to the language index to select the right message. An even number index is for one language, and odd for another. This could be extended for more text easily.

Listings.js

import S from 's-js'
import * as Surplus from 'surplus'
import {newsStrings as news} from './newsStrings.js'
import {eventsStrings as events} from './eventsStrings.js'
import {langIndex} from './langIndex.js'
import {modalTitle, modalMsg, modalWidth} from './Modal.js'
import FetchHtmlText from './FetchHtmlText.js'
import {displayModal} from './ModalBase.js'

/**
   Display a list of News or Events. Since they share the same format, we
   can use the same component for both, by setting the correct object
   from the props.type.
 */
export default function Listings (props) {
  /* set a constant that contains the object with strings */
  const newsEvents = props.type === 'news' ? news : events
  let div = <div /> // One div holds all of the listings.
  Object.keys(newsEvents)
        .forEach(key => {
          let clickMe = () => { // Each listing gets its own click handler.
            let html = <FetchHtmlText>{key}</FetchHtmlText>
            if (window.screen.width > 760) { // Accomodate small screens.
              modalWidth('60%')
            } else {
              modalWidth('98%')
            }
            modalTitle(newsEvents[key][langIndex()])
            modalMsg(html)
            displayModal('block') // Open Modal.
          }
          let child = <div className='listing' onClick={clickMe}>
          {newsEvents[key][langIndex()]}
          </div>
          let hr = <hr />
          let date = <div className='date'>{newsEvents[key][langIndex() + 2]}</div>
          div.appendChild(child)
          div.appendChild(date)
          div.appendChild(hr)
        })
  return (div)
}

Footer.js

Returns a div containing text labels and brief content.

See the GetLabeledText component for more detail.

The first footertitle entry doesn’t change when languages are switched, because it doesn’t vary. The rest of the text changes.

Footer.js

import S from 's-js'
import * as Surplus from 'surplus'
import {textStrings as txt} from './textStrings.js'
import GetLabeledText from './GetLabeledText.js'

export default function Footer (props) {
  return (
    <div className='footer'>
      <div className='label address'>
        <div className='footertitle'>{txt.title[0]}</div>
        <GetLabeledText>address</GetLabeledText>
      </div>
      <div className='label'>
        <GetLabeledText>admin</GetLabeledText>
      </div>
      <div className='label contact'>
        <GetLabeledText>contact</GetLabeledText>
      </div>
      <div className='label'>
        <GetLabeledText>hours</GetLabeledText>
      </div>
      <div className='label'>
        <GetLabeledText>email</GetLabeledText>
      </div>
      <div className='brag'>powered by <span className='me'>Les </span> (bithits@gmail.com)</div>
    </div>
  )
}

GetLabeledText.js

Used only by the Footer component, it reads the file labeledText.js. The format is the same as eventsString.js and newsStrings.js. Only the content is different.

Unlike the other two files, this content is only used for displaying labels and static text strings, and should rarely change. The second string msg can contain HTML tags and styles.

GetLabeledText.js

import S from 's-js'
import * as Surplus from 'surplus'
import {langIndex} from './langIndex.js'
import {labeledText as lt} from './labeledText.js'

export default function GetLabeledText (props) {
  let textNode = <div className='msg' />
  let label = props.children
  textNode.innerHTML = lt[label][langIndex() + 2]
  return (
    <div className='labeledtext'>
      <div className='labeled'>{lt[label][langIndex()]}</div>
      {textNode}
    </div>
  )
}

Responsive Web App with Surplus

Intro

S and Surplus

S.js

Surplus

Hello World → Hola Mundo

What is this App?

Development environment

Source Code

index.html

Modules

App.js

Modules and Components

langIndex.js

TopNav.js

Dropdown.js

MenuItem.js

ModalBase.js

Modal.js

SideNav.js

Header.js

Intro.js

FetchHtmlText.js

Pictures.js

The image files

Displaying an image the easy way

Prefetching images

Swipe event handler

Attaching the touch event handler

News.js

Events.js

Listings.js

Footer.js

GetLabeledText.js