-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
168 lines (167 loc) · 11.2 KB
/
index.html
File metadata and controls
168 lines (167 loc) · 11.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Postal Code Atumatic plugin documentation</title>
</head>
<body>
<h1 style=" text-align: center;">Postal Code Automatic documentation</h1>
<p> </p>
<p style="margin-left: 20px;">Postal Code Automatic v2.0.x is an
encapsulated plugin for Zen Cart v2.1 and above that automatically fills
state, city and if available street address fields in a form when you
enter postal/zip code. An Ajax request and JavaScript (jQuery) make this
possible on the fly without submitting the form.<br>
It uses extra tables with postal codes data per countries.<br>
An external jQuery plugin is used to display multiple possible answers in
a JavaScript popup tool window:<br>
PowerTip from Steven Benner at <a href="https://stevenbenner.github.io/jquery-powertip/"
title="PowerTip" target="_blank">https://stevenbenner.github.io/jquery-powertip/</a>.<br>
<br>
'Postal Code Automatic' is provided with ten countries data/tables: United
States, Spain, France and its territories, Germany, Italy, Swiss,
Liechtenstein (included with Swiss), Austria, Australia and Japan. If you
want to add a country, you must build a new table with necessary data and
add some PHP code (in SWITCH loop) to the Ajax query function.<br>
Instructions for that are at the end of this page.</p>
<h3 style="margin-left: 40px;">INSTALL:</h3>
<p style="margin-left: 80px;"><b>Copy <code>zc_plugins</code> folder</b>
content to the <code>zc_plugins</code> folder in your cart. Then go to
Zen Cart <b>admin menu <code>Modules->Plugin Manager</code></b>. You
should now see Postal Code Automatic in the plugin list. <b>Click on <i>Install</i></b>
button on the right. The postal codes tables to install in database are
big and it may take a while. <b>Wait</b> (and wait more) until a success
message displays.</p>
<p style="margin-left: 80px;"><strong><em>Important notes:</em></strong></p>
<ol style="margin-left: 80px;">
<li>If your server is slow you might encounter script timeout during
install. Installer already increased script execution time to 240s, but
if it is not enough, you can increase this time by editing <code>ScriptedInstaller.php</code>
on line 21 or in Zen Cart admin menu <code>Configuration->MyStore->Admin
Set max_execution_time for processes</code>. In case it already
happened, see note below.</li>
<li>Postal code tables are big, depending on countries they can have few
thousand records to over 124 000 records for Japan. If the server
encountered a <b>timeout during installation</b>, plugin won't be
installed. In this case you have to <b>run again the installer</b> (by
clicking on install button again), but <b>before</b> that you must <b>delete</b>
(using phpMyAdmin for example) the <b>last created postal code table</b>
(<code>zones_to_post_code_jp</code> for example) which is probably
incomplete due to the timeout. Installer won't try to install again
tables that are already there, only those that are missing.</li>
</ol>
<h3 style="margin-left: 40px;">USAGE:</h3>
<p style="margin-left: 80px;">When filling the form, it is better to start
by postal code. As soon as you have entered 4 characters, the Ajax script
will try to find, if exists, the postal code and data for the country
actually set. When the postal code is found, the state and city are filled
and eventually the street address one if there is some data.<br>
</p>
<p style="margin-left: 80px;">In case there are multiple results for the
city (and street address), the first on the list will be used to fill up
the city field. Other possible choices are accessible through a JavaScript
hover tool tips. When you mouse hover the city field, a clickable list of
possible cities for the entered postal code will appear on the right.<br>
Same goes for the street field if data are available, except here, all the
options for all possible cities are displayed at first. If you click on
one of the optional cities name, it will fill the city field<b>*</b> and
the options, if available, for the street address field will be restricted
to this city only.</p>
<p style="margin-left: 80px;"><small><b>*</b> The Javascript PowerTip tool
used here seems to have few bugs and sometime, at first use, clicking on
a city name has no effects. But if you close and reopen the tip tool by
moving the mouse out and in again, it should work properly.</small></p>
<h3 style="margin-left: 40px;">UNINSTALL:</h3>
<p style="margin-left: 80px;">Like for installation, use Zen Cart's <b>Plugin
Manager</b> in admin: <code>Modules->Plugin Manager</code>. You can
either disable the plugin or uninstall it. <b>Disable</b> option will
just deactivate the plugin but deletes nothing. <b>Uninstall</b> will
delete postal code tables in database and deactivate the plugin.</p>
<p style="margin-left: 80px;">Once uninstalled and you do not plan to use it
again, you can save space on server by deleting folder <code>PostAuto</code>
in Zen Cart's <code>zc_plugins</code> folder.</p>
<p style="margin-left: 80px;"><em><strong>Note:</strong></em></p>
<p style="margin-left: 120px;">If you want to keep postal codes tables when
uninstalling, you can do it by commenting out the appropriate line
(between 54 and 62) in file <code>zc_plugins/PostAuto/v2.0.x/installer/ScriptedInstaller.php</code>.</p>
<h3 style="margin-left: 40px;"> UPDATING ZONES ID:</h3>
<p style="margin-left: 40px;">When you add zones for a country listed in
this plugin after the plugin was installed, you can update zones ids in
the plugin table using this SQL query:</p>
<p style="margin-left: 80px;"><code>UPDATE zones_to_post_code_{CountryCode}
AS ztp INNER JOIN zones AS z ON ztp.zone_name = z.zone_name AND
ztp.zone_country_id = z.zone_country_id SET ztp.zone_id = z.zone_id;</code></p>
<p style="margin-left: 40px;">Replace <code>{CountryCode}</code> by the two
letters ISO code for the country you want to update. Note that the new
zones names must match the data in this plugin for this to work.</p>
<h3 style="margin-left: 40px;"> BUILDING A NEW COUNTRY TABLE DATA:</h3>
<p style="margin-left: 40px;">- First you need to download data. First place
to start is your country's national Post Office site. Be careful that
there are lots of services providing postal code data, but they are not
often free to distribute or even use.<br>
- You then must format these data to build a MySQL database table with a
name following this format <code>zones_to_post_code_{2 letters country
code}</code> and with these fields at minimum:</p>
<ul style="margin-left: 40px;">
<li> <b><code>zone_country_id</code></b> for the country id number
used in Zen Cart. Set for the country you downloaded data.</li>
<li> <b><code>zone_id</code></b> for this country zones id numbers in Zen
Cart if they exist. First setting it to zero is easier and then when
table is created (and zones exist), update it with an SQL query like
this:
<p style="margin-left: 40px;"> (example for United States):<br>
UPDATE zones_to_post_code_us INNER JOIN zones ON
zones_to_post_code_us.zone_name = zones.zone_name AND
zen_zones.zone_country_id = <i>223</i> SET
zones_to_post_code_us.zone_id = zones.zone_id;<br>
(example for France and other countries that includes territories or
other small countries):<br>
UPDATE zones_to_post_code_fr INNER JOIN zones ON
zones_to_post_code_fr.zone_name = zones.zone_name SET
zones_to_post_code_fr.zone_id = zones.zone_id;<br>
(example for Japan):<br>
UPDATE zones_to_post_code_jp INNER JOIN zen_zones
ON zones_to_post_code_jp.zone_name = zen_zones.zone_code AND
zen_zones.zone_country_id = <i>107</i> SET
zones_to_post_code_jp.zone_id = zen_zones.zone_id;</p>
</li>
<li> <b><code>post_code</code></b> obviously for postal/zip code. This
plugin is programmed for a minimum of five characters long.</li>
<li> <b><code>zone_name</code></b> for state, district, prefecture or
whatever it is called in the country.</li>
<li> <b><code>zone_city_name</code></b> for city name corresponding to
the postal code.</li>
<li> <b><code>zone_street_name</code></b> for area, county, or any street
level information. This can be omitted like in US table, but it must be
taken in account in PHP code in AJAX function.</li>
</ul>
<p style="margin-left: 80px;"> Then I add a <b><code>post_zone_id</code></b>
field as an auto_increment index. Have a look at provided tables data to
get an idea of the structure. All this can be done using different tools,
like Excel and/or a good text editor like notepad++ to finally build an
SQL file to import in Zen Cart.<br>
With countries using non-alphabet writing you might want to double fields
(adding an alphabet written field), but it will make SQL requests and PHP
loops more complicated. Have a look at Japanese version.</p>
<p style="margin-left: 40px;"> - Finally, few files need to be
updated/created: </p>
<ul style="margin-left: 40px;">
<li>Create a new file <code>zc_plugins/PostAuto/v2.0.x/installer/sql/install/zone_to_post_code_{NewCountryCode}.php</code>.
Look at other files in same folder to reproduce the structure.</li>
<li>Update file <code>zc_plugins/PostAuto/v2.0.x/catalog/includes/classes/ajax/zcAjaxPostcodeQuery.php</code>.
In the 'switch' loop you need to add a 'case' for the new country. You
can copy an existing one and modify country code and SQL request
especially if you have street data or not.</li>
<li>Update file <code>zc_plugins/PostAuto/v2.0.x/installer/ScriptedInstaller.php</code>.
In function <code>executeUninstall()</code>, add a line like this:<br>
<span style="margin-left: 80px;"><code>$this->executeInstallerSql("DROP
TABLE IF EXISTS " . TABLE_ZONES_TO_POST_CODE_{NewCountryCode});</code></span></li>
<li>Update files <code>zc_plugins/PostAuto/v2.0.x/admin/includes/extra_datafiles/postcode_auto__database_names.php</code>
and <code>zc_plugins/PostAuto/v2.0.x/catalog/includes/extra_datafiles/postcode_auto__database_names.php</code>.
add a line like this:<br>
<span style="margin-left: 80px;"><code>zen_define_default('TABLE_ZONES_TO_POST_CODE_{NewCountryCode}',
DB_PREFIX . 'zones_to_post_code_{NewCountryCode}');</code></span></li>
</ul>
<hr>
</body>
</html>