ae Soluciones Web
Presentación y descarga

Custom Input File Jquery Plugin

Custom Input File es un potente plugin JQuery que te permite transformar cualquier input file de tu formulario en un amistoso selector de archivos totalmente personalizable. Desarrollado en javascript y HTML5, permite arrastrar y soltar (drag & drop) múltiples archivos a la vez, validar archivos, previsualizar imágenes, subirlos al servidor, entre otras muchas opciones. También, Custom Input File incorpora el plugin Jcrop para que recortes tus imágenes o crees thumbnails a partir de ellas.

Custom Input File hará todo el trabajo por ti. En las hojas de estilo CSS encontrarás el modo de personalizar su apariencia y, a través de sus variadas opciones de configuración, podrás adaptarlo con facilidad a todos tus proyectos. Si quieres dar estilo a tus inputs file, dar mayor usabilidad a tus formularios o subir sin dificultad tus archivos, este asombroso plugin simplificará todas tus tareas.

Descargar

Instalación

Incluye la librería JQuery y los archivos js y css de la aplicación en el código HTML. Lo puedes hacer dentro de la etiqueta <head> o previamente a la etiqueta de cierre </body>.

<!--JQuery-->
<script src="js/jquery-1.11.0.min.js"></script> 

<!--JCrop (Jquery plugin for cropping images)-->
<script src="/path/js/jquery.Jcrop.min.js"></script> 
<link rel="stylesheet" href="/path/css/jquery.Jcrop.min.css" type="text/css" /> 

<!--Custom Input File-->
<script src="/path/js/custominputfile.min.js"></script> 
<link rel="stylesheet" href="/path/css/custominputfile.min.css"  type="text/css" />

Para la inicialización de la aplicación, el documento debe estar listo y debe existir un marcado HTML básico: un formulario y un input anidado. Es recomendable definir el action del formulario y un id para el input, aunque esto no sea necesario. También es opcional type="file"

<form action="process-form.php">
    <input name="input-file-1" id="input-file-1"> 
</form>
$(document).ready(function(e){
  $('#input-file-1').customFile();
});

Configuración

Tipos de selectores: imágenes vs. todo tipo de archivos. Permitir o prohibir extensiones.

Existen dos tipos de selectores: el selector de imágenes y el selector de todo tipo de archivos. El selector de imágenes permite previsualizar las imágenes añadidas, recortarlas, y definir opciones propias de las imágenes.

$(document).ready(function(e){
  $('#input-file-1').customFile({
    type : 'image' // set 'all' or just leave default settings for all-type file selector
  });
});

La opción type determina el tipo de selector y, a la vez, realiza un primer recorte sobre las extensiones admitidas por la aplicación. Para excluir un conjunto de extensiones o definir un conjunto limitado de extensiones permitidas, utiliza las opciones allowed y notAllowed. Por ejemplo,

$('#input-file-1').customFile({
  type : 'all',
  notAllowed: [“exe”, “js”] // Use allowed for admitting specific ones.
});

El selector de imágenes. Validación de tamaño y recorte de imágenes

El tipo de selector de imágenes permite definir los anchos y altos máximos y mínimos de las imágenes, si así lo quisieras.

type: 'image',
image : {
    minSize : [400,300] // width, height. Default: [0,0], ie, no restrictions.
    maxSize : [1080,300] // width, height. Default: [0,0], ie, no restrictions.
}

Este selector también te permitirá realizar recortes de las imágenes (se incorpora el plugin Jcrop). Activa la aplicación de recorte crop, define el tamaño del área de recorte cropSize y activa o desactiva el previsualizador de recorte preview.

type: 'image',
image : {
    crop    : true, // Default: false
    cropSize: [320,225], // [width, height]}
    preview : {
        display: true, // Default: true
        maxWidth: 300  // if cropSize were wider than maxWidth, only preview would be redimensioned (real crop area would not)
    }
},

Desde el servidor podrás los datos para recortar las imagenes o crear los thumbnails. Estos datos se encuentran en los inputs ocultos input name="your-input-file-name-x[]", input name="your-input-file-name-y[]", input name="your-input-file-name-w[]" y input name="your-input-file-name-h[]". Puedes leer los tutoriales para mayor información.

Cuando activas el recorte de imágenes, cropSize ayudará a Custom Input File a definir el tamaño mínimo de las imágenes junto a los estipulados en minSize: tendrán validez sólo los valores mayores. Si el ancho de minSize fuese menor al de cropSize, la aplicación tomará en cuenta el ancho de cropSize como ancho mínimo de las imágenes.

Múltiples archivos o uno por vez

Configura multiple: false para desactivar la selección de múltiples archivos simultáneos. En el modo desactivado de selecciones múltiples cada nuevo archivo sustituye al archivo seleccionado previamente, al igual que lo hace un input file tradicional.

Validación de Archivos (cantidad, peso, etc.)

Antes de ser cargados, los archivos pasan por diferentes validaciones, entre las que se encuentran las antes mencionadas (tamaño de imagen y extensiones de archivos). Las validaciones que puedes definir son:

allowed     : 'all',// or array of allowed extensions. E.g. ["exe", "jpeg", "jpg"]
notAllowed  : [],   //E.g. ["exe", "jpeg", "jpg"] 
maxFiles    : 4,    // Maximum number of files. Set 0 for no limits. Default 5
maxMB       : 0,    // Maximum MB for the sum of weight of files. Set 0 for no limits. Default 0
maxKBperFile: 800,  // Maximum weight (in KB) for every single file. Set 0 for no limits. Default 2048
image : {           // only for type: 'image'
    cropSize : [320,225],
    minSize  : [0,0],
    maxSize  : [0,0] 
}

Personalización de mensajes de error

Para cada validación fallida, Custom Input File devuelve un mensaje de error. Puedes personalizarlos, si gustas. El listado de errores personalizables son: errorType, errorType, errorMaxMB , errorFileKB, errorMaxFiles , errorBigImage, errorSmallImage. También puedes personalizar el mensajes de error devuelto cuando la aplicación se encuentra ocupada ( errorOnReading ) y el mensaje devuelto al arrastrar y soltar múltiples archivos en un input inhabilitado para ello ( errorMultipleDisable ).

messages : {
    errorType : 'You can’t upload this type of file',
    // other messages
}

Por defecto, los mensajes son comunicados al usuario a través de popups fácilmente personalizables (busca en las hojas de estilo las reglas que comienzan con #cif-msg-wr). Para desactivar el envío de mensajes de error o configurar el cerrado automático, configura:

popup : {
    active : true, // false if you don’t like popup messages
    autoclose : true, // or false
    delay : 10000 // delay for close (in miliseconds), of course, if autoclose is set true
},

Como veremos en el punto destinado al manejo de eventos, los mensajes de error podrán ser manejados a través del callback onError.

Marcado HTML para cada item e inputs dinámicos complementarios

Custom Input File te permite definir un marcado específico para cada nuevo ítem de archivo. Si agregas inputs adicionales dentro del marcado, éstos serán repetidos en cada nuevo ítem. Así, puedes enviar información adicional sobre el archivo al servidor. Asegúrate de definir el atributo name en cada uno de ellos.

La información del archivo (la imagen o el nombre de archivo) será añadida dentro de .cif-parent. Asegúrate de incluir dicho elemento en el marcado. De no ser incluido, la aplicación generará automáticamente dicho elemento en el lugar más conveniente.

fileWrapper : '<div class="cif-parent"></div><input type="text" name="photo_title">',

En vez de marcado, también puede elegir un elemento del DOM a través del objeto JQuery para ser repetido cíclicamente en cada nuevo ítem de archivo.

fileWrapper : $('.my_custom_file_wrapper')

Por último, el contenedor de todos los ítems de archivos por defecto es añadido luego del input file (ahora sustituido por el selector). Si prefieres especificar otro lugar en el DOM, puedes hacerlo definiendo en las opciones addContainerAfter.

addContainerAfter : $('#element_before_container')

Personalización del botón selector de archivos

Puedes personalizar la apariencia y el marcado del botón selector de archivos. Para el marcado, utiliza la opción de configuración filePicker.

filePicker : "<h3>Custom Text</h3><div>Write what you want</div>"

En los CSS, puedes editar la clase .cif-file-picker para personalizar la apariencia del selector.

También puedes modificar las clases .cif-file-picker:hover, .cif-file-picker.inactive, .cif-file-picker.dragover:not(.inactive) y .cif-file-picker.inactive.dragover

Eventos. Callbacks

Custom Input File añade opciones de configuración para el manejo de los eventos disparados en el proceso de lectura de los archivos. Esto resulta sumamente útil para quienes necesitan adaptar la aplicación a proyectos específicos. Por ejemplo, a través del evento onSuccess, podrás establecer el envío automático e inmediato de cada archivo tras su carga exitosa, o definir nuevas validaciones para los archivos.

callbacks : {

    onComplete : function(app){
        // Function fires when all files have already read;
        // You can access to app public properties like app.itemFileList or app.name
        console.log('process completed. You have selected  '+app.itemFileList.length+' files')
    },

    beforeRead : function(file){
        // Function fires every time a file is about to be read. Object File is ready but it has not been validated yet, neither image has been loaded.
        // Return false if you want app to stop reading this file and to continue reading next one
        console.log('start to read ' + file.name);
    },

    onSuccess : function(item, callback){
        // Function fires every time a file has been successfuly read;
        // Return false if you want app to stop reading next file.
        // Reading next file is callback. So, you can handle callback and fire it whenever you like (e.g., when file is already uploaded)
        // item is the current ItemFile instance. You can access to its public methods and public properties.
        setTimeout( callback , 2000 );
        return false;
    },

    onError : function(file, msg){
        // Function fires every time a file has been not successfuly read;
        // You can handle msg error and file.
        console.log(file.name + ' ERROR: '+ msg) 
    },

    beforeRemove : function(item){
        // Function fires every time an item file is just to be removed;
        // You can handle item before removing it.
        console.log('You are removing ' + file.name) 
    },
}

Métodos públicos

La aplicación cuenta con un gran número de propiedades y métodos públicos. Para más detalles, puedes acceder al código de desarrollo. A continuación seleccionaremos los más relevantes.

Métodos y propiedades de ItemFile

Las instancias de ItemFile generadas por la aplicación contienen toda la información relacionada con cada archivo. Exite un objeto ItemFile por archivo. Dentro de sus propiedades y métodos, te resultarán útiles:

item.file // store the File Object.
item.img // Property stores the Image Object
item.node // Property stores the entire node of this item in a JQuery object
item.serialize() // Method return a DataFile object to be send by ajax request
item.destroy()  // Method destroy current item

Como hemos visto anteriormente, a través de los eventos beforeRemove y onSuccess puedes acceder a cada itemFile. A continuación un ejemplo de lo que puedes hacer:

type : 'image',
callbacks : {
    onSuccess : function(item){
        // New validation rule is set for images:
        // app displays error message if image is wider than higher and destroy current itemFile
        if( item.img.width / item.img.height < 1 ){
            $.customFile.popup.add('Image proportions are not allowed'); // read next about this static public function 
            item.destroy();
        }
    }
}

Serialización y envío de formularios y/o de archivos

$.customFile.serialize(elements);

Serializa formularios, inputs o pseudo-inputs file. Regresa un objeto DataFile para ser enviado al servidor. Acepta como único argumento una cadena con selectores css separados por coma (al igual que lo hace el objeto JQuery) que refieran a formularios e inputs del DOM, y a pseudo-inputs file (a través del valor del atributo name). Véase los siguientes ejemplos:

var dataForm_1 = $.customFile.serialize('#my-form'); // Serialize form, including inputs and files.
var dataForm_2 = $.customFile.serialize('.some-input-text, input-file-1'); // Atention: 'input-file-1' is the name attribute of original input file. No dots, no hash, nothing before, just the name for selecting it.
//
//Now, you could send dataForm_1 and dataForm_2 as you want. Also, you can simplify your work submiting form with app's public method $.customFile.ajax().

$.customFile.ajax(element, options);

Envía un formulario completo (con todos sus archivos e inputs), o envía un input o archivo particular al servidor mediante ajax.

Acepta como primer argumento una cadena con un selector css (al igual que lo hace el objeto JQuery) que seleccione un formulario o input del DOM, o un pseudo-input file (a través de su nombre definido en el atributo name). También acepta como primer argumento una instancia de ItemFile

Como segundo argumento, acepta todas las opciones del método JQuery $.ajax, a los que se agregan las siguientes opciones referidas a la configuración de la barra de progreso:

progressBar : {
    active : true, // Set false if you do not want a progress bar at all
    appendTo : $('body'),  // which node you want to append current progressBar to
    removeAfterComplete : true, 
}

El método $.customFile.ajax() no necesita que especifiques una url de destino (siempre que hayas definido el action de los formularios).

Algunos ejemplos:

// Submit entire form. If there are pseudo inputs files, send these too. If success, do something…
$.customFile.ajax('#my-form', {
    success: function(response) {
        console.log(response);
    } 
}); 

// Submit a specific input and hide progressbar
$.customFile.ajax('#some-input-no-file', {
    progressBar : {
        active: false
    }
});

// Send all files attached to pseudo-input file (Rememeber! no dots, no hash, just the name for selecting it)
$.customFile.ajax('input-file-1'); 

// You can upload files one by one:
// When user selects files, each one is automatically uploaded. Once uploading is finished, it continues with next attached file.
// Also, progressbar is appended to each item node.
$('#input-file-2').customFile({
    callbacks : {
        onSuccess : function(item, callback){
            $.customFile.ajax(item, {
                url : ‘process_file.php’,
                progressBar : {
                    appendTo: item.node,
                    closeAfterComplete: false
                },
                complete : function(){
                    callback();
                }
             }); 
             return false; // Required for callback only fires once (when uploading is finished)
        }
    }
});

Popups

Puedes utilizar el popup de Custom Input File para enviar tus propios mensajes. Es muy sencillo de utilizar

Añadir popup

$.customFile.popup.add( msg, autoclose, delay, type )

La aplicación añade una nueva línea de mensaje a un popup abierto o a uno nuevo (si no existiese).

Argumentos:

msg es la cadena de texto que será enviada.

autoclose es un valor booleano para el cierre automático del popup.

delay es un valor numérico que determina el tiempo de cierre en milisegundos.

type el ícono de acompañamiento del mensaje. Opcional. Los valores aceptados son: ‘error’, ‘ok’.

Cerrar popup

$.customFile.popup.close()

La aplicación cierra toda instancia previa del popup. No acepta argumentos

Ejemplos:

$.customFile.popup.close() // Close popup if it were open
$.customFile.popup.add( “hello world” , false,  0 , 'ok')  // add first line
$.customFile.popup.add( “Second msg” , true,  5000 , 'error')  // add second line

Demos

All type file Picker

<form action='process-form.php'>
  <input name="input-file-1" id="input-file-1">
</form>
$(document).ready(function(e){
  $('#input-file-1').customFile();
});

Image file type Picker

$('#input-file-2').customFile({
  type : 'image'
});

Picking and cropping images

$('#input-file-3').customFile({
  type : 'image',
  image : {
     crop : true
  },
  filePicker : '<h3>Drag & drop your images here</h3>'
               +'<p>or click here</p>'
});

Some options

$('#input-file-4').customFile({
  type : 'all',
  allowed : ["pdf", "doc", "docx", "jpg"],  
  maxMB : 1,
  maxKBperFile : 500,
  maxFiles : 3,
  fileWrapper : '<div class="my_custom_wr">'
                  +'<div class="cif-parent"></div>' // File name or image will be append here
                  +'<input name="my_dynamic_input" placeholder="info for the file">'
                +'</div>',
  callbacks: {
      onSuccess : function(item){
          alert(item.file.name+" OK");
      }
  }
});

Contacto

Error. Complete los campos requeridos.
Error al enviar el mensaje. Vuelva a intentarlo o comuníquese telefónicamente.