modules/cck_fullname/README.txt

/**
 * $Id:$
 * @package CCK_Fullname
 * @category NeighborForge
 */
This module adds a full name CCK field to your installation. There are two sets of five fields,
prefix, first, middle, last, and suffix. There are several configuration options allowing you
to use legal names and preferred names.

--CONTENTS--
  REQUIREMENTS
  INSTALL/SETUP
  FEATURES
  USAGE (Example)
  FUTURE
  UNINSTALL
  CREDITS
  MIGRATION
  HELP
  
--REQUIREMENTS--
  This module requires the CCK content module.
  
  This module also supports the DIFF module and the TOKENS module. If you find something wrong
  with the support for these modules, please post and issue on the project's issue queue,
  preferably with a solution.
  
--INSTALL/SETUP--
  Download and ungzip/untar the package and place it wherever you have you other modules installed.
  
  If this is a new installation, that's it because this only uses CCK database stuff and CCK takes
  care of most of it.
  
  If this is an update to an existing install of this module, you'll need to run the Drupal update
  script. I added an install file because CCK doesn't take care of changes to the tables it
  manages. Hopefully someone has/will fix this in a future release of CCK.
  
--FEATURES--
  Two sets of five field names; 'legal name' and 'preferred name'.
  
  'Legal' is the default name with options of REQUIRED and OPTIONAL while 'preferred' has options
  of REQUIRED, OPTIONAL and HIDDEN.
  
  The five fields each name has are prefix, first, middle, last, and suffix. You may turn any of
  these fields on or off. You may REQUIRE individual fields without REQUIRING the entire name.
  This has the effect of only coming into effect if ANY field for that name is filled in.
  
  You may specify the maximum length of every field.
  
  You may limit middle names to initials.
  
  Multiple values works. If you have a name that is REQUIRED, only the first pair of names is
  affected as would be expected with multiple entries.
  
--USAGE--
  ADMINS-------
    Create a content type as you would normally. See the CCK docs for more info.
    
    Add a content type. Name it as you wish and select the 'fullname' widget. Save your choice. You
    are then presented with the settings page.
    
    Fill the upper section as you see fit, then turn your attention to the bottom section labeled
    'Data settings'. Here you will find all of the admin settings for this cck field set.
    
    At the top is a note I've added and is labeled "Notes:..." Read it and copy the note to your
    users into the 'Help text' section above it. Feel free to change the wording to reflect the 
    options you choose below.
    
    Next are two check boxes. The first enables the option to have multiple fields. If you don't
    know why you'd need this, you probably don't. The second check box is for restricting the
    middle name to 1 character, for storage as an initial. This is probably redundant since you
    could manually specify a field size of 1 below.
    
    The next section is 'Legal Name' and has several radio buttons and check boxes in it. The radio
    button set is for choosing the overall REQUIREMENT of the 'Legal name'. The 'Legal name' is the
    default for this module so there are only two options for use - REQUIRED and OPTIONAL. I'll
    explain the interaction of all options after I lay them all out. Keep in mind that this is a
    setting for the WHOLE NAME. The check boxes allow you to show/hide fields for input. If you
    don't care about prefixes and suffixes, for example, just uncheck them. Default is unchecked.
    
    The next section is 'Preferred Name' and is the same as the section just outlined except for
    one addition. There is an extra radio button labeled DON'T USE. This will hide this second
    name field from your users and effectively makes this a single name module.
    
    The next section is 'Required Parts' and lists all of ten parts of both name fields. Checking
    these boxes makes them individually REQUIRED. They only go into effect when the checkboxes
    in the previous two sections are also checked. In other words, REQUIRING hidden fields has no
    effect and no side effects. So feel free to check them all if you like.
    
    The above three sections interact in this way:
      Scenario A - You have marked one of the name's radio buttons as REQUIRED and checked all
      boxes in both its section and the 'Required Parts' section. This will behave as any other
      REQUIRED field you are use to where all sub-fields are also required.
      
      Scenario B - You have marked one of the name's radio buttons as REQUIRED and checked all
      boxes in its section, but only some in the 'Required Parts' section. The user must fill
      in only those fields marked in the 'Required Parts' section and can leave the others blank.
      
      Scenario C - You have marked one of the name's radio buttons as OPTIONAL and checked all
      boxes in both its section and the 'Required Parts' section. This means that the user won't
      have to fill in any fields, but if they choose to fill in one, they must fill them all in.
      
      Scenario D - You have marked one of the name's radio buttons as OPTIONAL and checked all
      boxes in its section, but only some in the 'Required Parts' section. The user must fill
      in only those fields marked in the 'Required Parts' section, and only if they fill in ANY
      of the fields for that name.
      
      Scenario E - I don't think there is one.
      
      NOTE: For display purposes, only one name is displayed on a node. If the user has specified
            a preferred name, that is used. If not, then the legal name is used. Use the translation
            features of Drupal to change any terms you don't like.
            
    The next two sections are identical, but for each of the two names in turn. In them, you may
    specify the maximum lengths of all fields.
  
  USERS-------
    From a user's perspective, there really isn't much to see. At node creation/editing, a table
    is presented to the user. The header is filled with the field names of which ever name has more
    fields. The legal name is on the first row, followed by the preferred name on the second. If
    you have multiple fields enabled, these two will alternate. Only the first two are affected by
    NAME-WIDE REQUIREMENTS. Latter names are only affected by FIELD REQUIREMENTS. In other words,
    all names after the first pair operate as though they have the OPTIONAL setting, even if one
    or both have the REQUIRED setting for the first rows.
    
    If you set the 'Preferred Name' to DON'T SHOW, then those rows won't even show up in the table.
    If you choose not to use individual fields, they won't show for that name type. If both name
    types don't have that field, then it is eliminated from the table.
    
    Validation works for any number of names in any REQUIREMENT combination.
    
    A side note: if you use the messageFX module, required fields flash if missing when submitted.
    That's pretty cool.
    
  THEMES-------
    I have mad an effort to sprinkle DIV and SPAN throughout. This release adds a CSS file which
    is pretty much necessary to get the REQUIRED indicator (*) to show and be in the right place
    since this complex interaction of REQUIREMENTS can't use Drupal's defaults. Feel free to
    override both the CSS entries and the theme functions.
    
--FUTURE--
  I would like to get this VIEWS compatible, but I currently don't have time to figure it out.
  Patches are very welcome. Also, if you'd like more output/display options, let me know, or
  roll patches for that as well. I've got a few options, but haven't actually figured out how to
  use them myself. I think someone contributed them earlier and I have simply updated them.
  
--UNINSTALL--
  Just disable the module. CCK should do its thing to remove any remnants (unless they still
  haven't fixed those issues).
  
--CREDITS--
  This module developed by Ryan Constantine (rconstantine). Thanks to linuxbox for ideas and a
  little bit of code (in the admin settings) for the new features. That was about all I could
  integrate of his code into mine for features that his module had that this didn't. I think I
  have now integrated all features from his module into this one. If you see his module's page
  (namefield module) you'll see that he didn't know this module pre-dated his and he agreed he'd
  rather there just be one. Hopefully, this module will work for him.
  
--MIGRATION--
  If you are currently using his (linuxbox) module (namefield) and would like to move to this
  one, encourage him to write an update routine. With the same number of fields for the names,
  it could possibly be as simple as renaming database columns. Admin settings are resaved each
  time a field is edited and saved, so if you don't have too many such fields, you could update
  the admin settings by hand easily enough. And if you only have one or two field instances, you
  could probably even update the database fields (and references) by hand too.
  
--HELP--
  As usual, go to http://drupal.org/project/issues/cck_fullname to post issues of support, bug
  reports, and feature requests. Contribute to the code if you can. I have too many modules to
  keep on top of everything all of the time.
1	/**
2	* $Id:$
3	* @package CCK_Fullname
4	* @category NeighborForge
5	*/
6	This module adds a full name CCK field to your installation. There are two sets of five fields,
7	prefix, first, middle, last, and suffix. There are several configuration options allowing you
8	to use legal names and preferred names.
9
10	--CONTENTS--
11	REQUIREMENTS
12	INSTALL/SETUP
13	FEATURES
14	USAGE (Example)
15	FUTURE
16	UNINSTALL
17	CREDITS
18	MIGRATION
19	HELP
20
21	--REQUIREMENTS--
22	This module requires the CCK content module.
23
24	This module also supports the DIFF module and the TOKENS module. If you find something wrong
25	with the support for these modules, please post and issue on the project's issue queue,
26	preferably with a solution.
27
28	--INSTALL/SETUP--
29	Download and ungzip/untar the package and place it wherever you have you other modules installed.
30
31	If this is a new installation, that's it because this only uses CCK database stuff and CCK takes
32	care of most of it.
33
34	If this is an update to an existing install of this module, you'll need to run the Drupal update
35	script. I added an install file because CCK doesn't take care of changes to the tables it
36	manages. Hopefully someone has/will fix this in a future release of CCK.
37
38	--FEATURES--
39	Two sets of five field names; 'legal name' and 'preferred name'.
40
41	'Legal' is the default name with options of REQUIRED and OPTIONAL while 'preferred' has options
42	of REQUIRED, OPTIONAL and HIDDEN.
43
44	The five fields each name has are prefix, first, middle, last, and suffix. You may turn any of
45	these fields on or off. You may REQUIRE individual fields without REQUIRING the entire name.
46	This has the effect of only coming into effect if ANY field for that name is filled in.
47
48	You may specify the maximum length of every field.
49
50	You may limit middle names to initials.
51
52	Multiple values works. If you have a name that is REQUIRED, only the first pair of names is
53	affected as would be expected with multiple entries.
54
55	--USAGE--
56	ADMINS-------
57	Create a content type as you would normally. See the CCK docs for more info.
58
59	Add a content type. Name it as you wish and select the 'fullname' widget. Save your choice. You
60	are then presented with the settings page.
61
62	Fill the upper section as you see fit, then turn your attention to the bottom section labeled
63	'Data settings'. Here you will find all of the admin settings for this cck field set.
64
65	At the top is a note I've added and is labeled "Notes:..." Read it and copy the note to your
66	users into the 'Help text' section above it. Feel free to change the wording to reflect the
67	options you choose below.
68
69	Next are two check boxes. The first enables the option to have multiple fields. If you don't
70	know why you'd need this, you probably don't. The second check box is for restricting the
71	middle name to 1 character, for storage as an initial. This is probably redundant since you
72	could manually specify a field size of 1 below.
73
74	The next section is 'Legal Name' and has several radio buttons and check boxes in it. The radio
75	button set is for choosing the overall REQUIREMENT of the 'Legal name'. The 'Legal name' is the
76	default for this module so there are only two options for use - REQUIRED and OPTIONAL. I'll
77	explain the interaction of all options after I lay them all out. Keep in mind that this is a
78	setting for the WHOLE NAME. The check boxes allow you to show/hide fields for input. If you
79	don't care about prefixes and suffixes, for example, just uncheck them. Default is unchecked.
80
81	The next section is 'Preferred Name' and is the same as the section just outlined except for
82	one addition. There is an extra radio button labeled DON'T USE. This will hide this second
83	name field from your users and effectively makes this a single name module.
84
85	The next section is 'Required Parts' and lists all of ten parts of both name fields. Checking
86	these boxes makes them individually REQUIRED. They only go into effect when the checkboxes
87	in the previous two sections are also checked. In other words, REQUIRING hidden fields has no
88	effect and no side effects. So feel free to check them all if you like.
89
90	The above three sections interact in this way:
91	Scenario A - You have marked one of the name's radio buttons as REQUIRED and checked all
92	boxes in both its section and the 'Required Parts' section. This will behave as any other
93	REQUIRED field you are use to where all sub-fields are also required.
94
95	Scenario B - You have marked one of the name's radio buttons as REQUIRED and checked all
96	boxes in its section, but only some in the 'Required Parts' section. The user must fill
97	in only those fields marked in the 'Required Parts' section and can leave the others blank.
98
99	Scenario C - You have marked one of the name's radio buttons as OPTIONAL and checked all
100	boxes in both its section and the 'Required Parts' section. This means that the user won't
101	have to fill in any fields, but if they choose to fill in one, they must fill them all in.
102
103	Scenario D - You have marked one of the name's radio buttons as OPTIONAL and checked all
104	boxes in its section, but only some in the 'Required Parts' section. The user must fill
105	in only those fields marked in the 'Required Parts' section, and only if they fill in ANY
106	of the fields for that name.
107
108	Scenario E - I don't think there is one.
109
110	NOTE: For display purposes, only one name is displayed on a node. If the user has specified
111	a preferred name, that is used. If not, then the legal name is used. Use the translation
112	features of Drupal to change any terms you don't like.
113
114	The next two sections are identical, but for each of the two names in turn. In them, you may
115	specify the maximum lengths of all fields.
116
117	USERS-------
118	From a user's perspective, there really isn't much to see. At node creation/editing, a table
119	is presented to the user. The header is filled with the field names of which ever name has more
120	fields. The legal name is on the first row, followed by the preferred name on the second. If
121	you have multiple fields enabled, these two will alternate. Only the first two are affected by
122	NAME-WIDE REQUIREMENTS. Latter names are only affected by FIELD REQUIREMENTS. In other words,
123	all names after the first pair operate as though they have the OPTIONAL setting, even if one
124	or both have the REQUIRED setting for the first rows.
125
126	If you set the 'Preferred Name' to DON'T SHOW, then those rows won't even show up in the table.
127	If you choose not to use individual fields, they won't show for that name type. If both name
128	types don't have that field, then it is eliminated from the table.
129
130	Validation works for any number of names in any REQUIREMENT combination.
131
132	A side note: if you use the messageFX module, required fields flash if missing when submitted.
133	That's pretty cool.
134
135	THEMES-------
136	I have mad an effort to sprinkle DIV and SPAN throughout. This release adds a CSS file which
137	is pretty much necessary to get the REQUIRED indicator (*) to show and be in the right place
138	since this complex interaction of REQUIREMENTS can't use Drupal's defaults. Feel free to
139	override both the CSS entries and the theme functions.
140
141	--FUTURE--
142	I would like to get this VIEWS compatible, but I currently don't have time to figure it out.
143	Patches are very welcome. Also, if you'd like more output/display options, let me know, or
144	roll patches for that as well. I've got a few options, but haven't actually figured out how to
145	use them myself. I think someone contributed them earlier and I have simply updated them.
146
147	--UNINSTALL--
148	Just disable the module. CCK should do its thing to remove any remnants (unless they still
149	haven't fixed those issues).
150
151	--CREDITS--
152	This module developed by Ryan Constantine (rconstantine). Thanks to linuxbox for ideas and a
153	little bit of code (in the admin settings) for the new features. That was about all I could
154	integrate of his code into mine for features that his module had that this didn't. I think I
155	have now integrated all features from his module into this one. If you see his module's page
156	(namefield module) you'll see that he didn't know this module pre-dated his and he agreed he'd
157	rather there just be one. Hopefully, this module will work for him.
158
159	--MIGRATION--
160	If you are currently using his (linuxbox) module (namefield) and would like to move to this
161	one, encourage him to write an update routine. With the same number of fields for the names,
162	it could possibly be as simple as renaming database columns. Admin settings are resaved each
163	time a field is edited and saved, so if you don't have too many such fields, you could update
164	the admin settings by hand easily enough. And if you only have one or two field instances, you
165	could probably even update the database fields (and references) by hand too.
166
167	--HELP--
168	As usual, go to http://drupal.org/project/issues/cck_fullname to post issues of support, bug
169	reports, and feature requests. Contribute to the code if you can. I have too many modules to
170	keep on top of everything all of the time.