Issue #1925760 by windmaomao: add proximity styling to count down/up timers.
[project/jstimer.git] / README.txt
1
2 -------------- OVERVIEW -------------------------------------------
3 The Javascript Timer module provides a timer api that can hook html elements to
4 javascript widget objects. This is useful if you want a moving timer/clock or a
5 widget that updates every second. It comes with widgets for a countdown timer, a
6 countup timer, and a clock.
7
8
9 -------------- INSTALLING -----------------------------------------
10 Simply by activating the module and a widget.
11 There are no module dependencies.
12 There are no table components.
13
14
15 -------------- GENERAL USAGE -----------------------------------------
16 You can either build-up your own nested <span tags within
17 a full html (or filtered with <spans allowed) input format, or
18 use php directly.  There are now theme functions to help with
19 the php formatted strings.
20
21 NOTE: the date format is an ISO8601 subset, so use the
22       formats as you see them below.
23
24
25 -------------- Inline HTML Examples --------------
26
27 Countdown timer (with DateTime specified):
28 <span class="jst_timer">
29  <span style="display:none" class="datetime">2015-05-02T08:11:00-08:00</span>
30 </span>
31
32 Countdown timer (with interval specified in seconds):
33 <span class="jst_timer">
34  <span style="display:none" class="interval">22</span>
35 </span>
36
37 Countdown timer with output format number setting:
38 <span class="jst_timer">
39 <span class="datetime" style="display: none;">2015-11-27T10:15:00-07:00</span>
40 <span class="format_num" style="display:none;">2</span>
41 </span>
42
43 Count up timer:
44 <span class="jst_timer">
45   <span style="display:none" class="datetime">2010-09-20T08:11:00Z</span>
46   <span style="display:none" class="dir">up</span>
47 </span>
48
49 NASA style down/up timer:
50 <span class="jst_timer">
51   <span class="datetime" style="display: none;">2012-10-26T10:28:00-07:00</span>
52   <span class="dir" style="display: none;">up</span>
53   <span class="format_txt" style="display:none;">%sign%%hours%::%mins%::%secs%</span>
54 </span>
55
56 SVG Clock:
57 <span class="jst_clock">
58  <span style="display:none" class="clock_type">3</span>
59  <span style="display:none" class="size">400</span>
60 </span>
61
62 HTML Canvas Clock:
63 <span class="jst_clock">
64  <span style="display:none" class="clock_type">2</span>
65  <span style="display:none" class="size">200</span>
66 </span>
67
68
69
70 -------------- PHP Input Format Examples --------------
71
72 Countdown timer:
73 <?php
74 print theme('jstimer', array(
75   'widget_name' => 'jst_timer',
76   'widget_args' => array(
77     'datetime' => '2015-05-02T08:11:00-08:00'
78   )
79 ));
80 ?>
81
82 Countdown timer with output format number setting:
83 <?php
84 print theme('jstimer', array(
85   'widget_name' => 'jst_timer',
86   'widget_args' => array(
87   'datetime' => '2015-05-02T08:11:00-08:00',
88     'format_num' => 2,
89   )
90 ));
91 ?>
92
93
94 Count up timer:
95 <?php
96 print theme('jstimer', array(
97   'widget_name' => 'jst_timer',
98   'widget_args' => array(
99     'datetime' => '2010-05-02T08:11:00+02:00',
100     'dir'=>'up'
101   )
102 ));
103 ?>
104
105 NASA style down/up timer:
106 <?php
107 print theme('jstimer', array(
108   'widget_name' => 'jst_timer',
109   'widget_args' => array(
110     'datetime' => '2015-05-02T08:11:00+02:00',
111     'dir'=>'up',
112     'format_txt' => '%sign%%hours%::%mins%::%secs%'
113   )
114 ));
115 ?>
116
117 Clock Widget:
118 <?php
119 print theme('jstimer', array(
120   'widget_name' => 'jst_clock',
121   'widget_args' => array(
122     'clock_type' => 2,
123     'size' => 200
124   )
125 ));
126 ?>
127
128
129
130 -------------- Timer widget OUTPUT FORMAT ---------------------------------------
131 The display of the actual timer is configurable in the Site configuration
132 admin menu: countdowntimer.
133
134 IMPORTANT: If you have a format_num and a format_txt in a timer, the format_txt
135 value will trump the format_num value.
136
137 Currently supported replacement values are:
138
139 Target date replacements:
140 %day%   - Day number of target date (0-31)
141 %month% - Month number of target date (1-12)
142 %year%  - Year number of target date (2013)
143 %dow%   - Day-Of-Week (Mon-Sun)
144 %moy%   - Month-Of-Year (Jan-Dec)
145
146 Duration/Interval replacements:
147 %years% - Years from set date (ex:2013, integer number)
148 %ydays% - (Days - Years) from set date(integer number)
149 %days%  - Total Days from set date (integer number)
150 %hours% - (Hours - Days) from set date (integer number, zero padded)
151 %hours_nopad% - (Hours - Days) from set date (integer number, no padding)
152 %mins%  - (Minutes - Hours) from set date (intger number, zero padded)
153 %mins_nopad%  - (Minutes - Hours) from set date (intger number, no padding)
154 %secs%  - (Seconds - Minutes) from set date (integer number, zero padded)
155 %secs_nopad%   - (Seconds - Minutes) from set date (integer number, no padding)
156 %months%       - (Months - Years) from set date, will be 11 or less (integer number)
157 %tot_months%   - Total months from set date, can be larger than 11 (integer number)
158 %tot_hours%    - Total hours from set date, can be larger than 23 (integer number)
159 %tot_minutes%  - Total minutes from set date, can be larger than 59 (integer number)
160 %tot_seconds%  - Total seconds from set date, can be larger than 59 (integer number)
161 %sign%         - Is used for NASA style countdown, will be '-' before set date and '' after set date (blank or '-')
162
163
164
165 -------------- CAVEATS ---------------------------------------------
166 If a daylight saving time shift should occur in either the client's tz or
167 the target's tz between the current date/time and your target datetime,
168 you could be off by one hour until you pass the point of conversion.
169
170 If you use the PHP input format beware.  If you have a syntax or other PHP error
171 and you've put your code in a block visible on all pages your entire site
172 may go down and you'll need to edit your database directly to delete that block!