[Summary view] [Print] [Text view]

   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 null
 224      */
 225  	public function process_field_row($mode, $profile_row);
 226  }