1	<?php
2	/**
3	*
4	* This file is part of the phpBB Forum Software package.
5	*
6	* @copyright (c) phpBB Limited <https://www.phpbb.com>
7	* @license GNU General Public License, version 2 (GPL-2.0)
8	*
9	* For full copyright and license information, please see
10	* the docs/CREDITS.txt file.
11	*
12	*/
13
14	namespace phpbb\profilefields\type;
15
16	interface type_interface
17	{
18	/**
19	* Get the translated name of the type
20	*
21	* @return string Translated name of the field type
22	*/
23	public function get_name();
24
25	/**
26	* Get the short name of the type, used for error messages and template loops
27	*
28	* @return string lowercase version of the fields type
29	*/
30	public function get_name_short();
31
32	/**
33	* Get the name of service representing the type
34	*
35	* @return string lowercase version of the fields type
36	*/
37	public function get_service_name();
38
39	/**
40	* Get the name of template file for this type
41	*
42	* @return string Returns the name of the template file
43	*/
44	public function get_template_filename();
45
46	/**
47	* Get dropdown options for second step in ACP
48	*
49	* @param string    $default_lang_id    ID of the default language
50	* @param array    $field_data            Array with data for this field
51	* @return array    with the acp options
52	*/
53	public function get_options($default_lang_id, $field_data);
54
55	/**
56	* Get default values for the options of this type
57	*
58	* @return array with values like default field size and more
59	*/
60	public function get_default_option_values();
61
62	/**
63	* Get default value for this type
64	*
65	* @param array    $field_data            Array with data for this field
66	* @return mixed default value for new users when no value is given
67	*/
68	public function get_default_field_value($field_data);
69
70	/**
71	* Get profile field value on submit
72	*
73	* @param array    $profile_row            Array with data for this field
74	* @return mixed        Submitted value of the profile field
75	*/
76	public function get_profile_field($profile_row);
77
78	/**
79	* Validate entered profile field data
80	*
81	* @param mixed    $field_value        Field value to validate
82	* @param array    $field_data            Array with requirements of the field
83	* @return mixed        String with the error message
84	*/
85	public function validate_profile_field(&$field_value, $field_data);
86
87	/**
88	* Get Profile Value for display
89	*
90	* @param mixed    $field_value        Field value as stored in the database
91	* @param array    $field_data            Array with requirements of the field
92	* @return mixed        Field value to display
93	*/
94	public function get_profile_value($field_value, $field_data);
95
96	/**
97	* Get Profile Value ID for display (the raw, unprocessed user data)
98	*
99	* @param mixed    $field_value        Field value as stored in the database
100	* @param array    $field_data            Array with requirements of the field
101	* @return mixed        Field value ID to display
102	*/
103	public function get_profile_value_raw($field_value, $field_data);
104
105	/**
106	* Get Profile Value for display
107	*
108	* When displaying a contact field, we don't want to have links already parsed and more
109	*
110	* @param mixed    $field_value        Field value as stored in the database
111	* @param array    $field_data            Array with requirements of the field
112	* @return mixed        Field value to display
113	*/
114	public function get_profile_contact_value($field_value, $field_data);
115
116	/**
117	* Generate the input field for display
118	*
119	* @param array    $profile_row        Array with data for this field
120	* @param mixed    $preview_options    When previewing we use different data
121	* @return null
122	*/
123	public function generate_field($profile_row, $preview_options = false);
124
125	/**
126	* Get the ident of the field
127	*
128	* Some types are multivalue, we can't give them a field_id
129	* as we would not know which to pick.
130	*
131	* @param array    $field_data        Array with data for this field
132	* @return string ident of the field
133	*/
134	public function get_field_ident($field_data);
135
136	/**
137	* Get the localized name of the field
138	*
139	* @param string $field_name        Unlocalized name of this field
140	* @return string     Localized name of the field
141	*/
142	public function get_field_name($field_name);
143
144	/**
145	* Get the column type for the database
146	*
147	* @return string    Returns the database column type
148	*/
149	public function get_database_column_type();
150
151	/**
152	* Get the options we need to display for the language input fields in the ACP
153	*
154	* @param array    $field_data        Array with data for this field
155	* @return array        Returns the language options we need to generate
156	*/
157	public function get_language_options($field_data);
158
159	/**
160	* Get the input for the supplied language options
161	*
162	* @param array    $field_data        Array with data for this field
163	* @return array        Returns the language options we need to generate
164	*/
165	public function get_language_options_input($field_data);
166
167	/**
168	* Allows exclusion of options in single steps of the creation process
169	*
170	* @param array    $exclude_options        Array with options that should be excluded in the steps
171	* @param array    $visibility_options        Array with options responsible for the fields visibility
172	* @return mixed        Returns the provided language options
173	*/
174	public function prepare_options_form(&$exclude_options, &$visibility_options);
175
176	/**
177	* Allows exclusion of options in single steps of the creation process
178	*
179	* @param array    $error                    Array with error messages
180	* @param array    $field_data        Array with data for this field
181	* @return array        Array with error messages
182	*/
183	public function validate_options_on_submit($error, $field_data);
184
185	/**
186	* Allows manipulating the intended variables if needed
187	*
188	* @param string    $key            Name of the option
189	* @param string    $action            Currently performed action (create|edit)
190	* @param mixed    $current_value    Currently value of the option
191	* @param array    $field_data        Array with data for this field
192	* @param int    $step            Step on which the option is excluded
193	* @return mixed        Final value of the option
194	*/
195	public function get_excluded_options($key, $action, $current_value, &$field_data, $step);
196
197	/**
198	* Allows manipulating the intended variables if needed
199	*
200	* @param int    $step            Step on which the option is hidden
201	* @param string    $key            Name of the option
202	* @param string    $action            Currently performed action (create|edit)
203	* @param array    $field_data        Array with data for this field
204	* @return mixed        Final value of the option
205	*/
206	public function prepare_hidden_fields($step, $key, $action, &$field_data);
207
208	/**
209	* Allows assigning of additional template variables
210	*
211	* @param array    $template_vars    Template variables we are going to assign
212	* @param array    $field_data        Array with data for this field
213	* @return null
214	*/
215	public function display_options(&$template_vars, &$field_data);
216
217	/**
218	* Return templated value/field. Possible values for $mode are:
219	* change == user is able to set/enter profile values; preview == just show the value
220	*
221	* @param string    $mode            Mode for displaying the field (preview|change)
222	* @param array    $profile_row    Array with data for this field
223	* @return string
224	*/
225	public function process_field_row($mode, $profile_row);
226	}