Skip to content

Latest commit

 

History

History
161 lines (100 loc) · 5.19 KB

README.md

File metadata and controls

161 lines (100 loc) · 5.19 KB
Raw

ITU OB editor

Build/release

Standalone application for editing ITU OB website data.

Get the app

Download the application from the Releases page.

Note: binaries are unsigned, which means your computer will warn you about launching an untrusted application.

  • On macOS, copy the application into your Applications folder.

  • On Windows, run the one-click installer. App’s shortcut should appear on your desktop.

Updating to latest version

Simply download the latest release and go through the same copy/install process.

If you have trouble using the app after upgrade, try resetting application data as described in the troubleshooting section below.

Using the app

Access application help at https://www.ituob.org/docs/. (You can also do that using Help menu in the app, but that feature is macOS-only for now.)

Troubleshooting problems

ITU OB Editor is under active development, so please mind that sometimes the app may misbehave.

If you have encountered an error or other possible malfunction while using the application, please report it here.

You may try removing application data:

  • From ~/Library/Application Support/itu-ob-editor on macOS
  • From %USERPROFILE%\AppData\Roaming\itu-ob-editor\ on Windows

Developer’s documentation

The app is based on Electron and is intended to be run on any OS supported by Electron.

App’s upstream data repository is located at https://github.com/ituob/itu-ob-data/.

The website and OB deliverables are statically generated from that repository using Jekyll. Site source is located at https://github.com/ituob/ituob.org/.

Setting up

You’ll need Node & Yarn.

# Install dependencies
yarn

# Run development copy
yarn dev

Debugging

Text logs are written in default locations as set by electron-log:

  • on macOS: ~/Library/Logs/<app name>/log.log
  • on Windows: %USERPROFILE%\AppData\Roaming\<app name>\log.log
  • on Linux: ~/.config/<app name>/log.log

To debug in production mode on macOS, run built binary as follows (from inside repository root):

./dist/mac/ITU\ OB\ Editor.app/Contents/MacOS/ITU\ OB\ Editor --remote-debugging-port=8315

Resetting app data manually during development

If the app errors out, a fix could be to manually delete the cloned data repository.

  1. Close the app
  2. Locate and delete itu-ob-data directory and itu-ob-settings.yaml file (on macOS, they’re in ~/Library/Application Support/itu-ob-editor/)
  3. Start the app again

Implementation Guide

Note: Publications of OB are interchangeably called “edition” and “issue” within source code.

SSE library

This app is using the SSE elements library. In addition to using the tools it provides, the app also follows its underlying philosophy, e.g. using “API endpoints” for communicating between main and renderer threads.

File layout under src/

  • main/: Electron’s main thread code.

    Contains app initialization, menu definitions, and sets up main thread API endpoints that browser windows can call from renderer thread.

  • renderer/: Electron’s renderer thread initialization.

    Organized by high-level React component.

  • static/: Application icons.

Renderer

Window initialization

When opening a new window, SSE supplies GET query parameter c which specifies the component to be loaded at top level in the window. (See: main/window.ts in sse-elements.)

Based on that value, renderer initialization picks the appropriate React component class.

If a top-level component is expected to be passed any props renderer initialization will expect GET query parameters to be passed. Only string prop values can be expected by top-level components. (For example, issue editor expects OB edition ID to be passed.) (See: src/renderer/index.tsx.)

Authoring React components

Refer to documentation for SSE elements for conventions.

Generic Electron Webpack docs

Note: These are kept for reference and may be obsolete.

Based on electron-webpack, this project comes with...

  • Use of webpack-dev-server for development
  • HMR for both renderer and main processes
  • Use of babel-preset-env that is automatically configured based on your electron version
  • Use of electron-builder to package and build a distributable electron application

Make sure to check out electron-webpack's documentation for more details.

Development Scripts

# run application in development mode
yarn dev

# compile source code and create webpack output
yarn compile

# `yarn compile` & create build with electron-builder
yarn dist

# `yarn compile` & create unpacked build with electron-builder
yarn dist:dir