Project

General

Profile

Download (8.83 KB) Statistics
| Branch: | Tag: | Revision:
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.
(2-2/47)