• REQUIREMENTS:

    • PHP >= 5.0.0
    • WORDPRESS >= 3.1.x
    • WORDPRESS MultiSite >= 3.1.x
    • MYSQL >= 4.1.2

    INSTALLATION:

    • WordPress: just copy whole cimy-user-extra-fields subdir into your plug-in directory and activate it
    • WordPress MultiSite
      there are two supported ways of using this plug-in under WordPress MultiSite: 

      1. Unique registration
        If you want that ALL Blogs on your MultiSite installation follow the same registration with the same fields this is the case for you.
        Every blog will have shared registration page and only the site administrators (of the whole MultiSite installation) can change it. 

        • unpack the package under ‘wp-content/mu-plugins’ directory (if this directory does not exist, create it);
        • be sure that cimy_user_extra_fields.php is outside Cimy folder (move it if necessary);
        • go to “Super Admin -> Cimy User Extra Fields”, press “Fix the problem” button and confirm.
      2. Per-Blog registration
        If you want that every single Blog can define its own Extra Fields then you should choose this installation.
        Every registration will have Extra Fields defined by single blogs, every user will have anyway WordPress fields shared with ALL Blogs, this how it works
        WordPress MultiSite. 

        • unpack the package under ‘wp-content/plugins’ directory;
        • be sure that cimy_uef_mu_activation.php is installed under ‘wp-content/mu-plugins’ directory (if this directory does not exist, create it);
        • then every single blog will have it under “Plugins” section.

    UPDATE FROM A PREVIOUS VERSION:

    • visit Cimy User Extra Fields admin options, DB upgrade will be performed automatically

    HOW TO ASSIGN A DEFAULT VALUE TO THE EXTRA FIELDS:

    • You can assign a default value using the VALUE textarea in the admin panel.
    • You can use URL (only for registration page), example:

      http://www.exampleofmywebsite.it/wordpress29/wp-login.php?action=register&FIELD_01=test1&FIELD_02=test2 

      FIELD_01 and FIELD_02 are two existing fields that will get default assignment with string “test1″ and “test2″.
      Note 1: Field name should be upper case otherwise won’t be recognized.
      Note 2: These two methods can be used together, but remember that URL has higher priority.

    FUNCTIONS USEFUL FOR YOUR THEMES OR TEMPLATES:

    [Function get_cimyFieldValue]

    NOTE: password fields values will not be returned for security reasons

    USAGE:

    $value = get_cimyFieldValue($user_id, $field_name, [$field_value]);

    In ALL cases if an error is occured or there are no matching results from the call then NULL is returned.

    This function is all you need to retrieve extra fields values, but in order to retrieve all power from it you have to understand all different ways that can be used.

    CASE 1:
    get an extra field value from a specific user

    PARAMETERS: pass user_id as first parameter and field_name as second
    RETURNED VALUE: the function will return a string containing the value

    GENERIC:

    $value = get_cimyFieldValue(user_id, field_name);

    EXAMPLE:

    $value = get_cimyFieldValue(1, 'MY_FIELD');
    echo cimy_uef_sanitize_content($value);

    CASE 2:
    get all extra fields values from a specific user

    PARAMETERS: pass user_id as first parameter and a boolean set to false as second
    RETURNED VALUE: the function will return an associative array containing all extra fields values from that user, this array is ordered by field order

    GENERIC:

    $values = get_cimyFieldValue(user_id, false);

    EXAMPLE:

    $values = get_cimyFieldValue(1, false);

    foreach ($values as $value) {
    echo $value['NAME'];
    echo $value['LABEL'];
    echo cimy_uef_sanitize_content($value['VALUE']);
    }

    CASE 3:
    get value from a specific extra field and from all users

    PARAMETERS: pass a boolean set to false as first parameter and field_name as second
    RETURNED VALUE: the function will return an associative array containing the specific extra field value from all users, this array is ordered by user login

    GENERIC:

    $values = get_cimyFieldValue(false, field_name);

    EXAMPLE:

    $values = get_cimyFieldValue(false, 'MY_FIELD');

    foreach ($values as $value) {
    $user_id = $value['user_id'];
    echo $value['user_login'];
    echo cimy_uef_sanitize_content($value['VALUE']);
    }

    CASE 4a:
    get all users that have a specific value in a specific extra field

    PARAMETERS: pass a boolean set to false as first parameter, field_name as second and field_value as third
    RETURNED VALUE: the function will return an associative array containing all users that has that value in that specific extra field, this array is ordered first by user login

    GENERIC:

    $values = get_cimyFieldValue(false, field_name, field_value);

    EXAMPLE:

    $values = get_cimyFieldValue(false, 'COLOR', 'red');

    foreach ($values as $value) {
    $user_id = $value['user_id'];
    echo $value['user_login'];
    }

    CASE 4b:
    get all users that contains (also partially) a specific value in a specific extra field

    PARAMETERS: pass a boolean set to false as first parameter, field_name as second and a special array as third
    RETURNED VALUE: the function will return an associative array containing all users that contains (also partially) that value in that specific extra field, this array is ordered by user login

    GENERIC:

    $values = get_cimyFieldValue(false, field_name, array);

    EXAMPLE:

    $field_value = array();
    $field_value['value'] = ".com";
    $field_value['like'] = true;

    $values = get_cimyFieldValue(false, 'WEBSITE', $field_value);

    foreach ($values as $value) {
    $user_id = $value['user_id'];
    echo $value['user_login'];
    }

    CASE 5:
    get all users with all values

    PARAMETERS: pass two boolean set to false as first and second parameter
    RETURNED VALUE: the function will return an associative array containing all extra fields values for every user, this array is ordered first by user login and second by field order

    GENERIC:

    $values = get_cimyFieldValue(false, false);

    EXAMPLE:


    $values = get_cimyFieldValue(false, false);
    $old_name = "";

    foreach ($values as $value) {
    $user_id = $value['user_id'];
    $new_name = $value['user_login'];

    if ($old_name != $new_name)
    echo "

    ".$new_name."

    ";

    echo $value['LABEL'].": ";
    echo cimy_uef_sanitize_content($value['VALUE'])."
    ";

    $old_name = $new_name;
    }

    ADDITIONAL EXAMPLES:
    This is an example how to retrieve and display one uploaded image of the current user logged in.

    $user = wp_get_current_user();

    // is there someone logged?
    if ($user->ID) {
    $value = cimy_uef_sanitize_content(get_cimyFieldValue($user->ID, 'IMAGE'));
    echo 'description_here';
    }

    This is an entire example that can be used into your theme for example to retrieve the value from SITE extra field that of course was created.
    If you put the example just inside an existing loop you shouldn’t add it again, just use get_cimyFieldValue call and echo call.

    if (have_posts()) {
    while (have_posts()) {
    the_post();

    $value = get_cimyFieldValue(get_the_author_ID(), 'SITE');

    if ($value != NULL)
    echo cimy_uef_sanitize_content($value);
    }
    }

    If you experience duplicate printing this is due to the loop and where/how it is used; to avoid this you can use this code that has a little workaround.
    REMEMBER: you cannot use get_the_author_ID() outside the loop, this because WordPress doesn’t permit this.

    if (have_posts()) {
    $flag = true;

    while (have_posts()) {
    the_post();

    if ($flag) {
    $value = get_cimyFieldValue(get_the_author_ID(), 'SITE');

    if ($value != NULL)
    echo cimy_uef_sanitize_content($value);

    $flag = false;
    }
    }
    }

    PICTURE AND get_cimyFieldValue FUNCTION:

    If you want to display the image in an HTML page just use IMG object like this:

    description_here

    If you want to get the thumbnail url and you have only the image url you can use this function:

    $thumb_url = cimy_get_thumb_path($image_url);

    REGISTRATION-DATE AND get_cimyFieldValue FUNCTION:

    Remember that the function returns the timestamp so to have the correct date printed you can use this function:

    echo cimy_get_formatted_date($value);

    or

    echo cimy_get_formatted_date($value, $format);

    where $format is the date and time format, more tags details here:
    http://www.php.net/manual/en/function.strftime.php

    [Function set_cimyFieldValue]

    NOTE 1: the user should have permission to write the value: this mean if the function is used when no user is logged in will always fail.
    NOTE 2: for checkbox fields use field_value=true/false to check/uncheck
    NOTE 3: for radio fields use field_value equal to the label you want to select
    NOTE 4: for dropdown fields use field_value equal to the item in the label you want to select
    NOTE 5: for dropdown-multi fields use field_value equal to the items in the label you want to select separated by a comma: ‘,’

    USAGE:

    $result = set_cimyFieldValue($user_id, $field_name, $field_value);

    RETURNED VALUE:
    An array is returned with all user ids where the change has been successful; empty array in case of error or the value is already in the DB.

    CASE 1:
    set an extra field value for a specific user

    PARAMETERS: pass user_id as first parameter, field_name as second and field_value as third
    RETURNED VALUE: the function will return an array containing USER_ID=1 if ‘NEW_VALUE’ has been written into ‘MY_FIELD’

    GENERIC:

    $result = set_cimyFieldValue(user_id, field_name, field_value);

    EXAMPLE:

    $result = set_cimyFieldValue(1, 'MY_FIELD', 'NEW_VALUE');

    CASE 2:
    set an extra field value for all users

    PARAMETERS: pass false as first parameter, field_name as second and field_value as third
    RETURNED VALUE: the function will return an array containing all USER_IDs where ‘NEW_VALUE’ has been written into ‘MY_FIELD’

    GENERIC:

    $result = set_cimyFieldValue(false, field_name, field_value);

    EXAMPLE:

    $result = set_cimyFieldValue(false, 'MY_FIELD', 'NEW_VALUE');

    [Function cimy_uef_sanitize_content]

    This function protects your blog from users trying to add JavaScript or alter your blog doing HTML injection in extra fields. It is very important that you do not remove that function.
    This function filters only some html tags and let other be used, the list of tags that are allowed is present under /wp-includes/kses.php search for $allowedtags array definition.

    It can accepts two parameters:
    $content: the content to be protected against HTML injections
    $override_allowed_tags [array|null, default null]: if you want to override allowed tags you should pass a proper array where all your favourite tags are listed.

    USAGE:

    echo cimy_uef_sanitize_content($content, [$override_allowed_tags]);

    EXAMPLE:

    global $allowedtags;

    // copy the array to not modify the original one
    $my_tags = $allowedtags;

    // add img tag to allowed tags list
    $my_tags["img"] = array(
    "src" => array(),
    "alt => array(),
    );

    // $content is what I want to show, see previous examples for more details
    echo cimy_uef_sanitize_content($content, $my_tags);

    [Function get_cimyFields]

    This function returns an array containing all extra fields defined by the admin ordered by the order defined in the admin page, if there are no fields an empty array is returned.

    It can accepts two parameters:
    $wp_fields [true|false, default false]: if true will return hidden WordPress fields enabled
    $order_by_section [true|false, default false]: if true array returned will be ordered as first key by fieldset and as second key by order; this parameter can be applied only if the first one is set to false.

    USAGE:

    $allFields = get_cimyFields([$wp_fields], [$order_by_section]);

    EXAMPLE:

    $allFields = get_cimyFields();

    if (count($allFields) > 0) {
    foreach ($allFields as $field) {
    echo "ID: ".$field['ID']." \n";
    echo "F_ORDER: ".$field['F_ORDER']." \n";
    echo "NAME: ".cimy_uef_sanitize_content($field['NAME'])." \n";
    echo "TYPE: ".cimy_uef_sanitize_content($field['TYPE'])." \n";
    echo "VALUE: ".cimy_uef_sanitize_content($field['VALUE'])." \n";
    echo "LABEL: ".cimy_uef_sanitize_content($field['LABEL'])." \n";
    echo "DESCRIPTION: ".cimy_uef_sanitize_content($field['DESCRIPTION'])." \n";

    echo "RULES: ";
    print_r($field['RULES']);
    echo "\n\n";
    }
    }

    HOW TO CHANGE REGISTRATION DATE FORMAT:

    You can change the format of the registration date putting your own format in equal to rule using tags from strftime php function:
    http://www.php.net/manual/en/function.strftime.php

    default used if not specified:
    %d %B %Y @%H:%M

    Month and weekday names and other language dependent strings respect the current locale set in your WordPress installation.

    HOW TO USE PICTURE SUPPORT:

    You have two possibilities for user picture support: “picture-url” and “picture”

    [PICTURE-URL]
    User will provide only a link and the image will be linked from that site, it will NOT be copied into the server

    [PICTURE]
    User will upload the image that is stored into his/her computer and the image will be copied into the server

    First of all you need a directory where all pictures will be stored, the directory MUST HAVE this name: ‘Cimy_User_Extra_Fields’ and MUST BE placed under: “wp-content” dir
    example: /wp-content/Cimy_User_Extra_Fields directory and give it 777 permissions if you are under Linux (or 770 and group to “www-data” if you are under Ubuntu Linux).

    HOW TO USE AVATAR SUPPORT:

    Create the same directory needed for PICTURE support, avatars will be stored in a subdirectory and will not interfere with other pictures uploaded by the same plug-in

    ADVANCED OPTIONS:

    Advanced options have been introduced in v2.1.0 to accommodate some extra options per field.
    Multiple options should be comma separated ‘,’

    [AVATAR, PICTURE]
    no-thumb=1 – do not crate the thumbnail (if equalTO rule is set it will resize the original image)
    crop_ratio=4:3 – fix cropping ratio
    crop_x1=0,crop_y1=0,crop_x2=80,crop_y2=90 – pre-select cropping window

    [AVATAR, PICTURE, FILE]
    filename=default.pdf – rename the uploaded file to the given file name

    HOW TO USE WPML SUPPORT:

    Since v2.4.0 field’s label and description can be translated using the WordPress Multilingual plug-in.
    To use it in your code you can get the get_cimyFields example above and change only the following lines:


    echo "LABEL: ".cimy_uef_sanitize_content(cimy_wpml_translate_string($field['NAME']."_label", $field['LABEL']))." \n";
    echo "DESCRIPTION: ".cimy_uef_sanitize_content(cimy_wpml_translate_string($field['NAME']."_desc", $field['DESCRIPTION']))." \n";

    KNOWN ISSUES:

    • if you add too many fields in the “Users Extended” menu they will go out of frame
    • some rules are never applied if you are using PHP 4.x please update to PHP 5.x as stated in the REQUIREMENTS
    • registration date cannot be modified
    • picture and avatar upload is disabled during registration under WordPress MultiSite, will be possible once user is activated
    • if you change order or remove fieldsets you may need to set all extra fields’ fieldset assigment again
    • dropdown issues:
      • custom value is not supported
      • comma is not allowed as it is the delimiter
    • registration confirmation does not work if you use Theme My Login plug-in