root / drupal7 / sites / all / modules / commerce / modules / customer / commerce_customer.api.php @ 70a4c29b
1 |
<?php
|
---|---|
2 |
|
3 |
/**
|
4 |
* @file
|
5 |
* Hooks provided by the Customer module.
|
6 |
*/
|
7 |
|
8 |
|
9 |
/**
|
10 |
* Defines customer profile types used to collect customer information during
|
11 |
* checkout and order administration.
|
12 |
*
|
13 |
* Each type is represented as a new bundle of the customer information profile
|
14 |
* entity and will have a corresponding checkout pane defined for it that may be
|
15 |
* used in the checkout form to collect information from the customer like name,
|
16 |
* address, tax information, etc. Each bundle can have a default address field
|
17 |
* added by the Customer module itself with additional fields added as necessary
|
18 |
* through modules defining the types or the UI.
|
19 |
*
|
20 |
* The Customer module defines a single customer information profile type in its
|
21 |
* own implementation of this hook,
|
22 |
* commerce_customer_commerce_customer_profile_type_info():
|
23 |
* - Billing information: used to collect a billing name and address from the
|
24 |
* customer for use in processing payments.
|
25 |
*
|
26 |
* The full list of properties for a profile type is as follows:
|
27 |
* - type: machine-name identifying the profile type using lowercase
|
28 |
* alphanumeric characters, -, and _
|
29 |
* - name: the translatable name of the profile type, used as the title of the
|
30 |
* corresponding checkout pane
|
31 |
* - description: a translatable description of the intended use of data
|
32 |
* contained in this type of customer profile. This description will be
|
33 |
* displayed on the profile types administrative page and on the customer
|
34 |
* profiles add page.
|
35 |
* - help: a translatable help message to be displayed at the top of the
|
36 |
* administrative add / edit form for profiles of this type. The Drupal
|
37 |
* core help module or any module invoking hook_help needs to be enabled
|
38 |
* to take advantage of this help text.
|
39 |
* - addressfield: boolean indicating whether or not the profile type should
|
40 |
* have a default address field; defaults to TRUE
|
41 |
* - label_callback: name of the function to use to determine the label of
|
42 |
* customer profiles of this type; defaults to commerce_customer_profile_default_label
|
43 |
* - module: the name of the module that defined the profile type; should not be
|
44 |
* set by the hook but will be populated automatically when the pane is loaded
|
45 |
*
|
46 |
* @return
|
47 |
* An array of profile type arrays keyed by type.
|
48 |
*/
|
49 |
function hook_commerce_customer_profile_type_info() { |
50 |
$profile_types = array(); |
51 |
|
52 |
$profile_types['billing'] = array( |
53 |
'type' => 'billing', |
54 |
'name' => t('Billing information'), |
55 |
'description' => t('The profile used to collect billing information on the checkout and order forms.'), |
56 |
); |
57 |
|
58 |
return $profile_types; |
59 |
} |
60 |
|
61 |
/**
|
62 |
* Allows modules to alter customer profile types defined by other modules.
|
63 |
*
|
64 |
* @param $profile_types
|
65 |
* The array of customer profile types defined by enabled modules.
|
66 |
*
|
67 |
* @see hook_commerce_customer_profile_type_info()
|
68 |
*/
|
69 |
function hook_commerce_customer_profile_type_info_alter(&$profile_types){ |
70 |
$profile_types['billing']['description'] = t('New description for billing profile type'); |
71 |
} |
72 |
|
73 |
/**
|
74 |
* Allows modules to specify a uri for a customer profile.
|
75 |
*
|
76 |
* When this hook is invoked, the first returned uri will be used for the
|
77 |
* customer profile. Thus to override the default value provided by the Customer
|
78 |
* UI module, you would need to adjust the order of hook invocation via
|
79 |
* hook_module_implements_alter() or your module weight values.
|
80 |
*
|
81 |
* @param $profile
|
82 |
* The customer profile object whose uri is being determined.
|
83 |
*
|
84 |
* @return
|
85 |
* The uri elements of an entity as expected to be returned by entity_uri()
|
86 |
* matching the signature of url().
|
87 |
*
|
88 |
* @see commerce_customer_profile_uri()
|
89 |
* @see hook_module_implements_alter()
|
90 |
* @see entity_uri()
|
91 |
* @see url()
|
92 |
*/
|
93 |
function hook_commerce_customer_profile_uri($profile) { |
94 |
// No example.
|
95 |
} |
96 |
|
97 |
/**
|
98 |
* Allows you to prepare customer profile data before it is saved.
|
99 |
*
|
100 |
* @param $profile
|
101 |
* The customer profile object to be saved.
|
102 |
*
|
103 |
* @see rules_invoke_all()
|
104 |
*/
|
105 |
function hook_commerce_customer_profile_presave($profile) { |
106 |
// No example.
|
107 |
} |
108 |
|
109 |
/**
|
110 |
* Determines whether or not a given customer profile can be deleted.
|
111 |
*
|
112 |
* Customer profiles store essential data for past orders, so they should not be
|
113 |
* easily deletable to prevent critical data loss. This hook lets modules tell
|
114 |
* the Customer module that a given customer profile should not be deletable.
|
115 |
* The Order module uses this hook to prevent the deletion of customer profiles
|
116 |
* attached to orders outside of the context of a single order that references
|
117 |
* the profile.
|
118 |
*
|
119 |
* @param $profile
|
120 |
* The customer profile object to be deleted.
|
121 |
*
|
122 |
* @return
|
123 |
* Implementations of this hook need only return FALSE if the given customer
|
124 |
* profile cannot be deleted for some reason.
|
125 |
*
|
126 |
* @see commerce_order_commerce_customer_profile_can_delete()
|
127 |
*/
|
128 |
function hook_commerce_customer_profile_can_delete($profile) { |
129 |
// No example.
|
130 |
} |
131 |
|
132 |
/**
|
133 |
* Allows modules to add arbitrary AJAX commands to the array returned from the
|
134 |
* customer profile copy checkbox refresh.
|
135 |
*
|
136 |
* When a customer checks or unchecks a box to copy the relevant information
|
137 |
* from one customer profile to another, the associated checkout pane gets an
|
138 |
* AJAX refresh. The form will be rebuilt using the new form state and the AJAX
|
139 |
* callback of the element that was clicked will be called. For this checkbox it
|
140 |
* is commerce_customer_profile_copy_refresh().
|
141 |
*
|
142 |
* Instead of just returning the checkout pane to be rendered, this AJAX refresh
|
143 |
* function returns an array of AJAX commands that includes the necessary form
|
144 |
* element replacement. However, other modules may want to interact with the
|
145 |
* refreshed form. They can use this hook to add additional items to the
|
146 |
* commands array, which is passed to the hook by reference. Note that the form
|
147 |
* array and form state cannot be altered, just the array of commands.
|
148 |
*
|
149 |
* @param &$commands
|
150 |
* The array of AJAX commands used to refresh the customer profile checkout
|
151 |
* pane with updated form elements.
|
152 |
* @param $form
|
153 |
* The rebuilt form array.
|
154 |
* @param $form_state
|
155 |
* The form state array from the form.
|
156 |
*
|
157 |
* @see commerce_customer_profile_copy_refresh()
|
158 |
*/
|
159 |
function hook_commerce_customer_profile_copy_refresh_alter(&$commands, $form, $form_state) { |
160 |
// Display an alert message.
|
161 |
$commands[] = ajax_command_alert(t('The customer profile checkout pane has been updated.')); |
162 |
} |