You are here

Home » API reference » User Import Framework 6

README.txt in User Import Framework 6

Same filename and directory in other branches
  1. 7 README.txt
The User Import Framework (uif) module provides simple, extensible user import via CSV (comma-separated value) files. The guiding philosophy is to make the import process as simple as possible for the end-user (the user doing the import). Hooks allow the developer to add the bells and whistles they need, e.g. content_profile support, while providing a strong base of support. 

User import is a two-step process. 1) The user chooses a csv file, along with specifying the number of records they'd like to preview (this preview can be skipped by power users). The user can also choose whether new users get a welcome email. 2) If happy with the preview, user submits the form again and users are created (or modified, if the user already exists).


Alternatives
------------
This module is unrelated to User Import (http://drupal.org/project/user_import). User Import has a great deal of functionality built in, and endeavors to integrate with several other modules. It has a more involved user interface, which may be better suited for technical administrators. This module, on the other hand, includes only critical user interface elements, with the goal of optimizing the user experience for non-technical administrators. Added functionality is provided by you, the developer, and to that end don't expect too much in the way of feature extensions to this module (but try me anyway).


Installation
------------
1) Copy the uif directory to the modules folder in your installation.

2) Enable the module using Administer -> Modules (/admin/build/modules)

3) Enable 'import users' permission for any role(s) you want to be able to do imports.

4) Go to User management -> Import users (/admin/user/uif) and import some users.


Basic Setup
-----------
Out of the box, this module does very basic user import. It can only import only users' email, username, and password. Of these three, only an email address is required. If no username is provided, the module creates a unique one based on the email. If no password is provided, a random one is generated. 

Only CSV file format is supported. The import file must have a header row, and it must contain a column labeled "email" (no quotes). If username and/or password is provided in any of the user data rows, there must be header columns labeled "username" or "password" respectively. Header case in input files is ignored.  Programmers should use lower case when referring to column data.


Extensibility
-------------
Several hooks are provided so that you can, for example, import more information about users, such as profile info. It is the developer's responsibility to write hook functions to do the work, e.g. create a profile node for content_profile module.

hook_uif_help()
This hook allows you to insert help text on the import page. The text appears beneath the basic help provided by the module.

hook_uif_validate_header($header, $form_state)
Your module can implement this hook to validate the array of header values. You may require certain fields for a profile. This is the place to check if the column exists in the import file. Return an array of error strings, all of which will be displayed, and the user will not be allowed to do the import. An empty array (or NULL) is success.

hook_uif_validate_user($user_data, $uid, $form_state)
This hook is called for every row of user data in the file. Like hook_uif_validate_header(), you can return any number of error strings, which are displayed to the user and which cause the import to fail. $user_data is an array of key => value pairs, where the key is the header column and the value is the data from the user row. All values are trimmed. $uid is either 0 for a new user or a positive integer for an existing user.

hook_uif_validate_all_users($user_list, $form_state)
Once all users have been individually validated via calls to hook_uif_validate_user(), if there are no errors this hook is called with the full array of users. This can be useful if, for example, your requirements limit the total number of users to be imported. As with hook_uif_validate_header() and hook_uif_validate_user(), the hook upon error should return any number of error strings, which are displayed to the user and which cause the import to fail.

hook_uif_pre_create($account, $user_data, $form_state)
This hook is called before a new user is created (before user_save() is called). $account contains basic account data (mail, name, pass). $user_data contains key => value pairs for the user about to be created.

hook_uif_post_create($account, $user_data, $form_state)
This hook is called after a new user is created (after user_save() is called). Same arguments as hook_uif_pre_create(). Good place to do work, like creation of a profile node.

hook_uif_pre_update($account, $user_data, $form_state)
Same idea as hook_uif_pre_create(), but used for existing (updated) users. In this case, $account->uid will be a positive integer.

hook_uif_post_update($account, $user_data, $form_state)
Same idea as hook_uif_post_create(), but used for existing (updated) users. In this case, $account->uid will be a positive integer.

Of course, since user_save() is called, core's hook_user() is available to you as well.

File

README.txt
View source 
  1. The User Import Framework (uif) module provides simple, extensible user import via CSV (comma-separated value) files. The guiding philosophy is to make the import process as simple as possible for the end-user (the user doing the import). Hooks allow the developer to add the bells and whistles they need, e.g. content_profile support, while providing a strong base of support. 

  2. 

  3. User import is a two-step process. 1) The user chooses a csv file, along with specifying the number of records they'd like to preview (this preview can be skipped by power users). The user can also choose whether new users get a welcome email. 2) If happy with the preview, user submits the form again and users are created (or modified, if the user already exists).

  4. 

  5. 

  6. Alternatives

  7. ------------

  8. This module is unrelated to User Import (http://drupal.org/project/user_import). User Import has a great deal of functionality built in, and endeavors to integrate with several other modules. It has a more involved user interface, which may be better suited for technical administrators. This module, on the other hand, includes only critical user interface elements, with the goal of optimizing the user experience for non-technical administrators. Added functionality is provided by you, the developer, and to that end don't expect too much in the way of feature extensions to this module (but try me anyway).

  9. 

  10. 

  11. Installation

  12. ------------

  13. 1) Copy the uif directory to the modules folder in your installation.

  14. 

  15. 2) Enable the module using Administer -> Modules (/admin/build/modules)

  16. 

  17. 3) Enable 'import users' permission for any role(s) you want to be able to do imports.

  18. 

  19. 4) Go to User management -> Import users (/admin/user/uif) and import some users.

  20. 

  21. 

  22. Basic Setup

  23. -----------

  24. Out of the box, this module does very basic user import. It can only import only users' email, username, and password. Of these three, only an email address is required. If no username is provided, the module creates a unique one based on the email. If no password is provided, a random one is generated. 

  25. 

  26. Only CSV file format is supported. The import file must have a header row, and it must contain a column labeled "email" (no quotes). If username and/or password is provided in any of the user data rows, there must be header columns labeled "username" or "password" respectively. Header case in input files is ignored.  Programmers should use lower case when referring to column data.

  27. 

  28. 

  29. Extensibility

  30. -------------

  31. Several hooks are provided so that you can, for example, import more information about users, such as profile info. It is the developer's responsibility to write hook functions to do the work, e.g. create a profile node for content_profile module.

  32. 

  33. hook_uif_help()

  34. This hook allows you to insert help text on the import page. The text appears beneath the basic help provided by the module.

  35. 

  36. hook_uif_validate_header($header, $form_state)

  37. Your module can implement this hook to validate the array of header values. You may require certain fields for a profile. This is the place to check if the column exists in the import file. Return an array of error strings, all of which will be displayed, and the user will not be allowed to do the import. An empty array (or NULL) is success.

  38. 

  39. hook_uif_validate_user($user_data, $uid, $form_state)

  40. This hook is called for every row of user data in the file. Like hook_uif_validate_header(), you can return any number of error strings, which are displayed to the user and which cause the import to fail. $user_data is an array of key => value pairs, where the key is the header column and the value is the data from the user row. All values are trimmed. $uid is either 0 for a new user or a positive integer for an existing user.

  41. 

  42. hook_uif_validate_all_users($user_list, $form_state)

  43. Once all users have been individually validated via calls to hook_uif_validate_user(), if there are no errors this hook is called with the full array of users. This can be useful if, for example, your requirements limit the total number of users to be imported. As with hook_uif_validate_header() and hook_uif_validate_user(), the hook upon error should return any number of error strings, which are displayed to the user and which cause the import to fail.

  44. 

  45. hook_uif_pre_create($account, $user_data, $form_state)

  46. This hook is called before a new user is created (before user_save() is called). $account contains basic account data (mail, name, pass). $user_data contains key => value pairs for the user about to be created.

  47. 

  48. hook_uif_post_create($account, $user_data, $form_state)

  49. This hook is called after a new user is created (after user_save() is called). Same arguments as hook_uif_pre_create(). Good place to do work, like creation of a profile node.

  50. 

  51. hook_uif_pre_update($account, $user_data, $form_state)

  52. Same idea as hook_uif_pre_create(), but used for existing (updated) users. In this case, $account->uid will be a positive integer.

  53. 

  54. hook_uif_post_update($account, $user_data, $form_state)

  55. Same idea as hook_uif_post_create(), but used for existing (updated) users. In this case, $account->uid will be a positive integer.

  56. 

  57. Of course, since user_save() is called, core's hook_user() is available to you as well.

  58.