UX best practices to report Logux synchronization status to user
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
badge
test
.editorconfig
.eslintrc
.gitignore
.jsdocrc
.lintstagedrc
.npmignore
.size-limit
.travis.yml
.yaspellerrc
CHANGELOG.md
LICENSE
README.md
attention.js
badge.js
confirm.js
favicon.js
index.js
jest.config.js
log.js
package.json
status.js
yarn.lock

README.md

Logux Status Cult Of Martians

UX best practices to report Logux synchronization status to user.

var CrossTabClient = require('logux-client/cross-tab-client')
var client = new CrossTabClient({ … })

var attention = require('logux-status/attention')
var confirm = require('logux-status/confirm')
var favicon = require('logux-status/favicon')
var log = require('logux-status/log')

var badgeMessages = require('logux-status/badge/en')
var badgeStyles = require('logux-status/badge/default')
var badge = require('logux-status/badge')

attention(client)
confirm(client, i18n.t('loguxWarn'))
favicon(client, {
  normal: '/favicon.ico',
  offline: '/offline.ico',
  error: '/error.ico'
})
badge(client, {
  position: 'bottom-left',
  messages: badgeMessages,
  styles: badgeStyles
})
log(client)
Sponsored by Evil Martians

attention

Highlight tab on synchronization error to notify user.

var attention = require('logux-status/attention')
attention(client)

User could switch current tab in the middle of synchronization process. So error could be returned from server when website is in background tab.

User expect correct synchronization until we told about a error. So good UX must notify user, return her/him to website tab and show error.

It will add * to tab title on error event. Because of changed title, browser will highlight tab until user will open it.

It returns a function to disable itself.

var unbind = attention(client)
function disableLogux() {
  unbind()
}

confirm

Show confirm popup, when user close tab with non-synchronized actions.

var confirm = require('logux-status/confirm')
confirm(client)

User could close app tab in offline or in the middle of synchronization process. So good UX must notify user and request confirmation to close the tab.

Use optional second argument to specify a text of warning.

confirm(client, 'Post was not saved to server. Are you sure to leave?')

It returns a function to disable itself.

var unbind = confirm(client)
function disableLogux() {
  unbind()
}

favicon

Change favicon to show synchronization status.

var favicon = require('logux-status/favicon')
favicon(client, {
  normal: '/favicon.ico',
  offline: '/offline.ico',
  error: '/error.ico'
})

User should always be sure, that she/he have latest updates. If pages goes offline, we must notify user, that data could be outdated. By using favicon we could notify user even if user is in other tab.

Use second argument to specify favicon links. You can miss any icon:

favicon(client, {
  normal: '/your_default_link.ico',
  error: '/your_error_link.ico'
})

Recommendations for favicon versions:

  • For offline you could make a black-and-white version and make it a little lighter.
  • For error you could put a red dot to favicon.

It returns a function to disable itself.

var unbind = favicon(client, favicons)
function disableLogux() {
  unbind()
}

badge

Display Logux synchronization state in widget.

var badgeMessages = require('logux-status/badge/en')
var badgeStyles = require('logux-status/badge/default')
var badge = require('logux-status/badge')

badge(client, {
  position: 'bottom-left',
  messages: badgeMessages,
  styles: badgeStyles
})

This feature will be useful for application users to be aware of current Logux server connection status. To make sure that they won’t lose any unsaved data because of server malfunctioning.

Use second argument to configure widget appearance in different states.

First of all you must define base styles for widget and optional styles for different states. Icon for widget injecting as background image, so remember about left padding for appropriate positioning.

Possible states are: synchronized, disconnected, wait, sending, error and protocolError. Use states as keys in styles object to define desired styles for states.

  styles: {
    ...badgeStyles,
    base: {
      position: absolute,
      height: '50px',
      width: '200px',
      paddingLeft: '50px'
    }
    synchronized: {
      backgroundColor: 'green'
    },
    error: {
      backgroundColor: 'red'
      backgroundIcon: require('./error.svg'),
    }
  }

To configure custom messages appearing on different states, use messages object with states as keys and desired strings as value. Use <br> tag for multiline messages.

  messages: {
    ...badgeMessages,
    synchronized: 'Your data has been saved',
    error: 'Server error.<br>Your data has not been saved'
  }

Also there is an opportunity to configure location of widget. Possible options to X-axis: left, center, right. Possible options to Y-axis: top, middle, bottom.

badge(client, {
  ...styles,
  ...messages,
  position: 'top-left'
})

It returns a function to disable itself and remove widget from DOM.

var unbind = badge(client)
function disableLogux() {
  unbind()
}

status

Low-level function to display Logux synchronization status in your own UI. Like badge but with own design.

var status = require('logux-status/status')

status(client, function (state, details) {
  if (state === 'synchronized') {
    show('Everything is fine')
  } else if (state === 'synchronizedAfterWait') {
    show('We returned from offline')
  } else if (state === 'disconnected') {
    show('We lost connection to server')
  } else if (state === 'wait') {
    show('We have action for synchronization, but have no connection')
  } else if (state === 'connecting') {
    show('Connecting to server')
  } else if (state === 'connectingAfterWait') {
    show('Connecting to server and we have actions for synchronization')
  } else if (state === 'sending') {
    show('Sending actions to server')
  } else if (state === 'sendingAfterWait') {
    show('Sending actions to server after disconnected')
  } else if (state === 'syncError') {
    show('Error during synchronization', details.error.message)
  } else if (state === 'protocolError') {
    show('You need to update client. Reload page.')
  } else if (state === 'error') {
    show('Server error during processing your action')
  } else if (state === 'denied') {
    show('Your action was denied')
  }
})

It returns a function to disable itself.

var unbind = status(client, callbacks)
function disableLogux() {
  unbind()
}

log

Display Logux events in browser console.

var log = require('logux-status/log')
log(client)

This feature will be useful for application developer to understand Logux life cycle and debug errors.

In second argument you can disable some message types. Possible types are: state, role, error, add, clean.

log(client, { add: false })

Logux events in browser console are colorized by default, if console styling is supported by browser. To disable this feature, set color to false in the second argument.

log(client, { color: false })

It return a function to disable itself.

var unbind = log(client)
function disableLogux() {
  unbind()
}