@omensi/world_clock v1.0.5

What is World Clock?

If you need a simple, easy to use, responsive world clock widget for your project, then you came to the right place. World Clock is a Frontend (UI) widget, which is written using modern WEB technologies - HTML5, CSS, JS. It is as simple as it gets - you see time and date in the selected timezone. Widget was written in a Plug-n-Play fashion, you only need to import module code to your JS code and you are ready to go (almost), check out Installation and Examples for a reference.

Component can be used in all major browsers where ES5 standard is compliant. Source code is written in ES6, but is compiled with Babel to ES5.

Table of contents

• Description
  • Purpose
  • Functions
  • Restrictions
  • Dependancies
• Documentation
  • Configurable attributes
    • Required attributes
    • Optional attributes
  • Classes, fields and methods
    • Classes
    • Fields
    • Methods
  • Installation
• Examples
  • Usage guide
• Change log
• License
• Appendix
  • List of available timezones

Description

Purpose

• If you are too busy with other problems and don't want to waste time re-inventing the wheel
• If your boss asks you to create a frontend world clock widget within a few days
• If the requirements meet functions, which are implemented in this widget

Then grab a copy of this code, install it to your project, check examples and Rock-n-Roll!.

Functions

The widget provides these functions:

• Date and time display
• Timezone selection and search
• Timezone memorization
• Customization:
  • Color theme (dark, light)
  • Toggle show date
  • Toggle show seconds

Restrictions

The widget can only be used in the frontend, it was designed to meet HTML5 standard, so it's a pure UI widget.

Dependancies

World Clock widget is dependant on the Moment.js library and Moment Timezone plugin. These dependancies are required in order to have a manageable API when selecting different timezone, because we didn't want to deal with the different timezone offsets and daylight savings (we also don't want to re-inventing the wheel).

Important: If your project doesn't have these libraries included in the scope, widget automatically imports these at initialization.

At release time:

• Moment.js was on version 2.29.1
• Moment Timezone was on version 0.5.33

Dependancies are imported through CDN services.

Documentation

Configurable attributes

Required attributes

container - field is required. It's an HTML component id attribute.

Optional attributes

theme - field is optional. Controls widget color theme.

Default value = WorldClock.Theme.Light.

Available values = WorldClock.Theme.Light, WorldClock.Theme.Dark.

showSeconds - field is optional. Show seconds in the clock?

Default value = true.

showDate - field is optional. Show date in the widget?

Default value = true.

Classes, fields and methods

Public API allows to only access WorldClock instance, its public fields and methods, which will be documented below.

Classes

WorldClock - World Clock public API component, which allows to initialize widget with the defined attributes.

Fields

Class WorldClock:

Methods

Class WorldClock:

All documentation in regards to classes, methods and fields is available in JSDoc generated documents, which are listed here.

Additional documentation available here.

Installation

In order to use component you need to:

1. Get the source code:
   • Clone repository git clone https://github.com/omenSi/world-clock.git ;
   • Install from npm npm i @omensi/world_clock .
2. Copy /build/world_clock.js file and paste it into your application source, for example /static/components/world_clock directory.
3. Check Dependancies and make sure they are met;
4. Import WorldClock from the source to your JS;

To start using World Clock widget you only need to import the JS of the component into your code base. Go to the footer of you HTML layout and add this line:

<script src="components/world_clock/world_clock.js"></script>

Note: src - should be equal to the path in your server public directory, where component source is accessible. After this step WorldClock will be accessible in your code base, because library was exposed to the window object.

5. Initialize WorldClock object with required attributes (see Examples);

Examples

1. We want to initialize widget in the default configuration:

    const clock = new WorldClock({
        container: "worldClockContainer"
    });

2. We want to initialize widget with the dark theme:

    const clock = new WorldClock({
        container: "worldClockContainer",
        theme: WorldClock.Theme.Dark
    });

3. We want to initialize widget with dark theme and hidden date field:

    const clock = new WorldClock({
        container: "worldClockContainer",
        theme: WorldClock.Theme.Dark,
        showDate: false
    });

4. We want to initialize widget with light theme and hidden seconds field:

    const clock = new WorldClock({
        container: "worldClockContainer",
        theme: WorldClock.Theme.Light,
        showSeconds: false
    });

More examples:

See live example (Express.Js application) in directory /demo, where you will be able to configure widget live.

Usage guide

1. We make sure to follow steps defined at installation.
2. We make sure that we correctly initialize world clock in our code following defined examples.
3. We give some width/height for the container, which will hold our world clock.

<style>
.clock {
    width: 300px;
    height: 150px;
}
</style>
<div id="worldClock" class="clock"></div>

4. We see widget view in the UI after we load the page.

5. We want to change the timezone:

   1. First we need click on the icon.
   2. Now we will be able to see the view like this:

   

   3. We can scroll the list and click on one of the list elements:

   

   4. Or we can search for a timezone if we know what we want to select and then click on it:

   

   5. Once we click on the timezone we want, widget will update its state and we will be returned to the main view of the widget:

   

6. After page reload, timezone will be selected from memory.

Change Log

• v1.0
  • v1.0.0
    • Initial project release.
  • v1.0.1
    • Readme updates.
  • v1.0.2
    • Readme updates.
  • v1.0.3
    • Added Github Pages to serve JSDoc documentation. See here
  • v1.0.4
    • Readme updates.
  • v1.0.5
    • Readme updates.

License

World Clock is released under the Apache 2.0 license.

Appendix

List of available timezones

The list of available timezones is based on the moment.js timezone plugin. We retrieve all available zones and group them into three categories: TimezoneGroup, TimezoneRegion, TimezoneCity.

Link from documentation here.

Example of a list of timezones:

- Africa
    - Abidjan
    - Accra
    - Addis_Ababa
    ...
- America
    - Adak
    - Argentina
        - Buenos_Aires
        - Catamarca
        ...
 ...

Full list is available here.