1
|
/**
|
2
|
* $Id: README.txt,v 1.4.2.1 2007/12/14 20:16:15 rconstantine Exp $
|
3
|
* @package CCK_Address
|
4
|
* @category NeighborForge
|
5
|
*/
|
6
|
This module adds an amalgamated address field to nodes via the CCK mechanisms.
|
7
|
|
8
|
There are many standard features, several of which you will never use but which were needed by the author.
|
9
|
|
10
|
--CONTENTS--
|
11
|
REQUIREMENTS
|
12
|
INSTALL
|
13
|
FEATURES
|
14
|
USAGE (Example)
|
15
|
THEMING
|
16
|
UNINSTALL
|
17
|
CREDITS
|
18
|
HELP
|
19
|
|
20
|
--REQUIREMENTS--
|
21
|
This module depends on Drupal 5.X, CCK, and for some advanced features, the Activeselect module. Activeselect uses
|
22
|
AJAX, but this module degrades nicely for those who haven't enabled javascript in their browser.
|
23
|
|
24
|
--INSTALL--
|
25
|
The site admin must first install the module per the regular drupal installation pattern. This
|
26
|
will:
|
27
|
1) Create a table to store country names and abbreviations.
|
28
|
2) Create a table to store state/province names, their abbreviations, and the country they belong to.
|
29
|
3) Add U.S. data to both tables.
|
30
|
4) If you install the Canada module, it will install data to both tables.
|
31
|
|
32
|
--FEATURES--
|
33
|
8 fields make up an address in this module: Address, Address continued, Apt/suite number, City, State, ZIP, Country,
|
34
|
and Other.
|
35
|
|
36
|
All fields can be turned on or off. This is for both input and display.
|
37
|
|
38
|
All fields can be renamed. Ex. Instead of State, you could have Province, or State/Province.
|
39
|
|
40
|
The creator of the content type can order the fields as he/she wishes. I often put 'Other' first and call it 'Location
|
41
|
name'. Warning, the CSS file and the themes have been designed for a certain order of fields, so you may need to
|
42
|
override them.
|
43
|
|
44
|
You can specify the length of these fields: Address, Address continued, Apt/suite number, City, and Other. State and
|
45
|
Country are not adjustable as they are select fields.
|
46
|
|
47
|
All fields can have a default value specified. State and Country are selected view select drop down (either AJAX or
|
48
|
not depending on if you have Activeselect enabled), while the rest of the fields are text fields.
|
49
|
|
50
|
You can reset settings to default values by deleting any changes you've made, saving the settings, then saving them
|
51
|
again. [You'll see before the second save that the fields have been populated with the default values.] This does
|
52
|
not apply to field order, or turning fields on/off.
|
53
|
|
54
|
--USAGE--
|
55
|
This can be found when once you add this field to a content type via the normal CCK routine and will later be found
|
56
|
here: admin/content/types/CONTENTTYPEHERE/fields/field_YOURFIELDNAMEHERE
|
57
|
|
58
|
There is quite a lot here. First, this module is based around database-stored address data. What that means is that
|
59
|
you can install modules that are specific to the countries you need. For example, this package comes with support for
|
60
|
both the United States and Canada. The main module installs all database information for the U.S. and its states.
|
61
|
Likewise, the Canadian module adds its own information to the tables created by the main module. This data, together
|
62
|
with a new hook, hook_validate_address_fields, allows each module to validate the address information it is
|
63
|
responsible for. See the Canada module for an example.
|
64
|
|
65
|
--In this admin interface, you can select how the states are presented - abbreviated, full name, or free text.
|
66
|
Abbreviated gives you a two letter representation. Full name is the state name spelled out in full. Free text means
|
67
|
that the user can write whatever they want, rather than select from a select list as the other two methods do. You
|
68
|
can also choose to abbreviate the country or not.
|
69
|
|
70
|
--Next, you select which countries that this use of the field should use under 'Allowed Countries'. You can now choose
|
71
|
to allow other countries. This will change the country field into a text box, rather than a selector. This bypasses
|
72
|
both the database-stored countries and the database-related validation. This is required if you use 'Free-text Entry'
|
73
|
for your states.
|
74
|
|
75
|
--'Customize fields to use' is next and this is where you decide which address fields to display. As noted there, this
|
76
|
affects both input and display. What is not mentioned there is that this does not affect storage. Blank fields are
|
77
|
stored if not used.
|
78
|
|
79
|
--'Maximum field lengths' are max lengths for the standard text entry fields. If you elect to make the country and state
|
80
|
fields text entry as well, then they will use the max length from the city field.
|
81
|
|
82
|
--'Customize field names' is where you change the names of the fields as presented to the user at the time of node
|
83
|
creation or editing.
|
84
|
|
85
|
--'Customize field display order' is where you order the fields from 1 to 8, which is how they will be presented. I
|
86
|
suggest that you come up with just a couple of standards for your sites and stick to them as you will probably have
|
87
|
to modify your theme's style.css file to override the standard css file that comes with this module as well as the
|
88
|
theme functions if you do anything too radical.
|
89
|
|
90
|
--'Customize field defaults' is where you can specify what fills the fields when a new node is going to be created.
|
91
|
Of course, users may change the values, but for sites that are highly localized, specifying at least a City, State
|
92
|
and Country (and maybe even ZIP) speeds up the entry process for such sites.
|
93
|
|
94
|
--MARGINAL USE CASE-- (ignore this if you don't need it and don't complain if it doesn't meet your needs)
|
95
|
The next section in the admin is made for the rare case that addresses are known in advance. If it isn't obvious, this
|
96
|
was needed for a special case by the author. Part of user registration at his site is to validate against a known address
|
97
|
list stored in his database. In case you may find a similar need down the road, I'll explain how to use it.
|
98
|
|
99
|
Before I begin, you need to know that the ActiveSelect module is REQUIRED for the operation of this part.
|
100
|
|
101
|
The first item is a checkbox which activates the use of the rest of the items in the other parts of the module. Setting the
|
102
|
other items without checking the box will do nothing.
|
103
|
|
104
|
Next is a listing of every table in your database. I implemented a special permission just for this called 'administer
|
105
|
databases'. This entire fieldset shouldn't even show up unless you have this permission. Select the table that contains
|
106
|
your stored addresses. The next four fields should then populate with the column names from that table. In turn, select
|
107
|
the column that relates to each field. Next is a country selector. Choose the country of the known addresses, then the
|
108
|
state once its field is populated. Make sure the Country is selected in 'Allowed Countries' as well.
|
109
|
|
110
|
That's it. The user will not be able to choose a country or a state. They will be able to select a city and a zip, though
|
111
|
in my case there will always(?) only be one choice. The street number and street names are text fields for the user so that
|
112
|
they don't see the possible addresses. They must already know one (hopefully their own) that is in the database as each
|
113
|
field is validated alone and then together.
|
114
|
|
115
|
This section of the module completely bypasses the regular validation and only validates against this table. Oh, except for
|
116
|
state and country. Those use the regular tables for validation.
|
117
|
|
118
|
--THEMING--
|
119
|
This module comes with a CSS file and implements two theme functions. I have constructed the CSS file so that two cases of
|
120
|
display order should look okay when nodes are created/edited. The first case is the for the order listed in the 'Customize
|
121
|
fields to use' section. The second case is where 'Other' is the first field, then 'Address', 'Apt/suite number', 'Adress
|
122
|
continued', 'City', 'State', 'ZIP', and 'Country'. Also, these assume max field lengths as mentioned in that section's
|
123
|
fieldset description, namely 30, 30, 7, 30, 30.
|
124
|
|
125
|
Use Firefox's Firebug plugin to inspect and test changes to the CSS values, then cut and paste them into your theme's
|
126
|
style.css file.
|
127
|
|
128
|
If you need to override the theme functions, just copy them to the appropriate places in your theme files. I think they
|
129
|
would go in node.tpl.php for standard Drupal themes.
|
130
|
|
131
|
If you look at the source code, you'll find a couple of TODOs. One would be to elaborate on the node display theme. Right
|
132
|
now, I have it so that the display of the fields in nodes comes out just fine in both cases I mentioned above. However,
|
133
|
using complicated 'if' statements, others could probably be supported. The difficulty lies in accounting for spaces between
|
134
|
fields on the same line, where to break lines, put commas, and so on and having a flexible system.
|
135
|
|
136
|
--UNINSTALL--
|
137
|
This is done the usual way, first by deactivating, then uninstalling. A reversal of any changes made during installation is
|
138
|
performed. It is best if you completely uninstall supporting modules, like Canada, and then remove the main module.
|
139
|
|
140
|
--CREDIT--
|
141
|
This module was created by Ryan Constantine (rconstantine)
|
142
|
|
143
|
--HELP--
|
144
|
Post issues to the issue queue of this project.
|