Developer Instructions - Covers installation and instantiation. Describes how to add an EZ Time JS field to your page and how to get the time value out of it.

User Instructions - Describes how to perform data entry using EZ Time JS.

• Developer Instructions
  • Quick Installation
  • Creating an EZ Time Input Field
  • API
  • Retrieving the Time Value
• User Instructions
  • Quick Start
  • Detailed Data Entry Instructions
  • Shortcut Codes
  • Submitting the Input
  • Editing Entered Values
  • Errors
  • Customization of Style

Developer Instructions

Quick Installation

Installation is very simple and fast.

1. Download the eztime.zip file and extract it to any location in the document folder of your website. In this example, we place the extracted eztime folder in the top level of the document root of the website as follows: /var/www/html/MyWebSiteFolder/eztime/

2. On your web page, include the eztime.js file by indicating the correct path:

3. Now you must include the JQuery framework, which is also found in the eztime folder. If you are already using JQuery on your site, you can skip this step. 

4. Include the eztime.css file for styling.

That's it! You are ready to use EZ Time JS.

Creating an EZ Time Input Field

Create a span element with a unique id attribute and assign it the EZ Time class as follows:

Now simply refresh the page. You should see an EZ Time input field where you placed the span field.

The span element acts as a container for all elements required by each EZ Time instance. 

API

EZTimeInit()

The initialization of all EZ Time fields is done through the EZTimeInit() function, which is called automatically after the page loads. However, you can call it any other time as well. For example, you may need this if you dynamically load the eztime.js file. Do not instantiate more than once. In other words, avoid calling this function if it has already been called.

MyEZTime(id)

This class allows you to programmatically retrieve the value of your EZ Time instance. You must instantiate it using the id attribute of the span element that you specified to hold the EZ Time instance. For example:

function doSomething() {
	var MyEZTimeField= new MyEZTime('MyTimeField')
	var timeEntered = MyEZTimeField.getTime()
}
window.onload = doSomething; 

Be sure to include and load the eztime.js Javascript file BEFORE you make any instantiation of the MyEZTime() class.

Retrieving the Time Value

You can retrieve the time value in two ways. The first way, described above in the API section, is to get the value using Javascript. The second way is to get the value on the server side after an HTTP request if the time field has been placed within a form and the form is then submitted.

EZTime creates a text input element whose name and id attribute are both the id of the parent span element that you declared followed by '-input'. For example, the following span element results in a form text input field as shown below:

Declared span element:

Resulting text input element created by EZ Time:

You can then access this form element as usual via an HTTP request value on the server side. Here is an example using PHP:

User Instructions

Quick Start

This table shows many useful patterns to follow in order to begin using EZ Time JS quickly.

To submit the value for validation, simply press Enter, exit out of the field by pressing Tab, or click out of the field by clicking with the mouse.

Detailed Data Entry Instructions

Data must be entered according to the following format:

HOUR [MINUTE] [AM/PM]

The minimum value required for valid entry is the hour, as indicated in the following table:

EZ Time JS expects up to 3 pieces of data from the user: hour, minute and either AM or PM. These can be separated by spaces but this is unnecessary.

Instead of a space, a colon can be used between the hour and minute as well.

EZ Time JS also allows you to enter the hour and minute with no space between them as well. If a total of 3 digits are entered, the first digit only is interpreted as the hour.

If 4 digits are entered, the first two are taken as the hour.

However, the only required input is the hour. Both minute and AM/PM are optional. If minute is not specified, it is automatically set to 00. If AM/PM is not specified, AM is assumed by default.

AM/PM can be included without the minutes. AM/PM can be abbreviated as 'p' or 'a'. The space can also be omitted. Entering 'am' or 'pm' is also accepted.

Shortcut Codes

Several shortcuts are available to greatly simplify data entry. Using capital versus lower case input makes no difference with EZ Time JS. You can use shortcuts together at the same time.

Errors

If an error notice appears, you can hide by clicking anywhere on it. Or you can press escape while in the field and this clears the field and hides the error message.

Customization of Style

The design can be completely customized by altering the eztime.css file. However, it is not recommended to alter positioning attributes without a good understanding of how these work.