cck/modules/content_multigroup/README.txt

   1 ; $Id: README.txt,v 1.1.2.2 2008/10/14 15:28:14 karens Exp $
   2
   3 THIS MODULE IS STILL EXPERIMENTAL AND NOT READY FOR PRODUCTION!
   4 ===================================================================
   5
   6 To try it out, add a content_multigroup.info file to the module.
   7 The info file should be a plain text file that looks like:
   8 ===================================================================
   9 name = Content Multigroup
  10 description = Combine multiple CCK fields into repeating field collections that work in unison. This module is experimental and not ready for production.
  11 dependencies[] = content
  12 dependencies[] = fieldgroup
  13 package = CCK
  14 core = 6.x
  15 ===================================================================
  16
  17 USING MULTIGROUPS
  18
  19 The Multigroup group treats all included fields like a single field,
  20 keeping the related delta values of all included fields synchronized.
  21
  22 To use a Multigroup, create a new group, make it the 'Multigroup' type,
  23 set the number of multiple values for all the fields in the Multigroup,
  24 and drag into it the fields that should be included.
  25
  26 All fields in the Multigroup will automatically get the group
  27 setting for multiple values. On the node form, the group is rearranged
  28 to keep the delta values for each field in a single drag 'n drop group,
  29 by transposing the normal array(field_name => delta => value) into
  30 array(delta => field_name => value).
  31
  32 During validation and submission, the field values are restored to
  33 their normal positions.
  34
  35 FIELDS AND WIDGETS THAT WORK IN MULTIGROUPS
  36
  37 All fields that allow the Content module to handle their multiple
  38 values should work here. Fields that handle their own multiple values
  39 will not be allowed into Multigroups unless they implement
  40 hook_multigroup_allowed_widgets() to add their widgets to the allowed
  41 widget list.
  42
  43 All fields that allow the Content module to handle their multiple
  44 values should work correctly when a Multigroup is changed back to
  45 a normal group. Fields that handle their own multiple values
  46 which may store different results in Multigroup and standard groups should
  47 implement hook_multigroup_no_remove_widgets() to add their widgets
  48 to the list of widgets that cannot be removed from Multigroups.
  49
  50 If a simple array of widgets is not sufficient to test whether this
  51 action will work, modules can implement hook_multigroup_allowed_in()
  52 and hook_multigroup_allowed_out() to intervene.
  53
  54 Custom code and modules that add fields to groups outside of the UI
  55 should use multigroup_allowed_in() and multigroup_allowed_out()
  56 to test whether fields are allowed in or out of a Multigroup.
  57
  58
  59 TROUBLESHOOTING
  60
  61 The most likely cause of problems with field modules not working in
  62 multigroup is if they wipe out #element_validate with their own
  63 validation functions, or they hard-code assumptions into submit or
  64 validation processes that the form is structured in the usual
  65 field => delta => value order instead of allowing for the possibility
  66 of a different structure. See Nodereference for an example of a field
  67 that handles validation without making assumptions about the form
  68 structure.