[Alexandre Magno] jqswfupload – jQuery e swfupload em uma linha

 Logo do jqswfupload
Gostaria de anunciar o lançamento da versão 1.0 beta do plugin que desenvolvi, o jqswfupload. Este plugin atende a uma evolução do plugin que desenvolvi que ajudou muita gente a implementar upload múltiplos utilizando o swfupload. Ele se tornou obsoleto com a versão 10 do flash player, que mudou a forma de como enviar requisicoes ao flash atraves do javascript usando elementos html. Desta vez desenvolvi um plugin usando as versões mais nova do jQuery e do próprio swfupload que corrige este problmea com o flash player 10 e ainda funciona com players após a versão 8. O plugin é totalmente customizável e gera toda a interface de upload em uma só linha. O plugin possui opções próprias além de ter todas as opções do swfupload aptas para serem modificadas.

Houve também muito cuidado para preservar uma ótima experiência do usuário. A interface foi baseada no upload de fotos do Flickr.

O plugin terá novas versões em breve com melhorias contínuas e até a possibilidade de criar extensões para fazer upload de imagens com opção de edição como redimensionar e cortar.

Ver exemplo do jqswfuploadMake the download of the jqswfupload

Documentação

Os requisitos para o funcionamento do plugin estão listado abaixo:

  • jQuery v1.3.2
  • SWFUpload v2.1
  • jQuery UI 1.7 (usando somente o efeito de highlight)

Suporte:

  • IE 7+
  • Chrome 1+
  • Firefox 3+
  • Safari 3+

* Não houve teste no IE6

Utilização

Primeiro, você deve incluir o plugin e suas dependências:

 <link type="text/css" href="jquery.jqswfupload.css" rel="stylesheet" />

<script language="JavaScript" type="text/javascript" src="libs/jquery-1.3.2.min.js"></script>

<script language="JavaScript" type="text/javascript" src="libs/jquery-ui-1.7.1.custom.min.js"></script>

<script language="JavaScript" type="text/javascript" src="libs/swfupload.js"></script>

<script language="JavaScript" type="text/javascript" src="libs/jquery.jqswfupload.js"></script>

Esta ordem é importante para que o plugin possa funcionar corretamente.

jqswfupload usa a biblioteca swfupload em conjunto com o jQuery. Então ele sobrescreve um simples input de arquivo com um sistema de upload múltiplos baseado em flash que possui todo o controle de progresso e tamanho do arquivo.

A marcação mínima para que o plugin possa funcionar está listada abaixo:

 <div id="upload-container">

<form action="upload.php" method="post" enctype="multipart/form-data">

<div id="upload-placeholder">

<input type="file" name="Filedata" />

<input type="submit" value="upload" />

</div>

</form>

</div>

Com esta marcação você pode invocar o plugin com as seguintes opções:

$("#upload-container").jqswfupload({
onFileSuccess: function(file,data,response) {

//execute when happen the upload file success

},

onFileError: function(file,code,message){

//execute when happen the upload file error

}

},

{

upload_url:  './upload.php'

});

O plugin aceita dois objetos como parâmetros, o primeiro são as opções do plugin como um objeto literal e o segundo um objeto de settings do swfupload.

 $('container').jqswfupload(Object plugin_options, Object swfupload_options);

Opções do Plugin

  • container (padrão: #upload-container) : O seletor de contexto de onde o plugin age. Pode ser um id ou classe do formulário onde o input do tipo file está localizado.
  • total_size (padrão: 5 MB) : O tamanho máximo da fila total.
  • message_delay (padrão: 3000) : O tempo em milisegundos que as mensagens de aviso ou sucesso permanece na interface.
  • columns (Padrão: Object) : O objeto com o texto padrão das colunas. As chaves do objeto são file, size and action que referenciam ao arquivo, tamanho e ação (remover arquivo). Quando uma das opções é passada, é obrigatório que você especifique as demais.
  • messages (padrão: Object) : O objeto com mensagens padrões. As chaves atualmente são file_size_limit, file_already_exist, browse_upload e start. Quando uma das opções é passada, é obrigatório que você especifique as demais.
  • onFileSucces(file,data,response) : O callback invocado a cada sucesso do arquivo
    • file: Um objeto que carrega informações do arquivo, como nome, tamanho e um identificador único
    • data: Os dados enviados ao servidor
    • response: A resposta vinda do servidor. Esta é a resposta dada pelo script de upload e você pode retornar json, xml ou pedaços de html para serem tratados.
  • onFileError(file,error,message)
    • file: Um objeto que carrega informações do arquivo, como nome, tamanho e um identificador único
    • error: O código de erro do arquivo
    • message: A mensagem de erro

Opções do swfupload

  • upload_url (padrão: ../upload.php ): A url relativa ao plugin
  • flash_url (padrão: libs/swfupload.swf) : O caminho do arquivo swfupload.swf relativa ao local onde o script é chamado
  • button_placeholder_id (padrão: upload-placeholder): O id do elemento que será substituído pelo upload em flasho, geralmente o input id ou uma div pai do input do tipo file
  • post_params (Objeto) : Dados adicionais para serem enviados junto com o post do arquivo. Neste post você pode enviar dados de formulário, identificadores de sessão etc. Ele segue o seguinte formato:

post_params : { 

   "post_param_name_1" : "post_param_value_1",

   "post_param_name_2" : "post_param_value_2",

   "post_param_name_n" : "post_param_value_n"

},

Para uma completa referência das opções do swfupload, veja a documentação do swfupload

Dúvidas frequentes

Aqui está uma lista das dúvidas frequentes que podem ocorrer ao utilizar o jqswfupload:

Qual a vantagem deste plugin em relação a utilizar o swfupload sozinho?

SWFUpload é uma ótima biblioteca utilizada amplamente em grandes projetos para realizar uploads múltiplos. Ela torna fácil a integração do flash com a interface web que não seja puramente nesta tecnologia. Entretanto, o swfupload tem muitos eventos, callbacks e opções que permite a flexibilidade para o desenvolvedor criar a experiência completa de upload utilizando javascript para criar todo o dom necessário para fazer isto acontecer. Este plugin é baseado na experiência do usuário utilizada no upload de fotos do Flickr. Toda a interface pode ser customizada por CSS. Com algumas vantagens, o jqswfupload estende as funcionalidades do swfupload, como progresso geral de arquivo e limitação de tamanho máximo da fila, não simplesmente limitar o tamanho de um único arquivo. O plugin foi construído para tornar este tipo de upload da “maneira jQuery de ser” que com uma linha você pode ter tudo funcionando e você tem o objeto de opções para ter o poder de mudar de acordo com sua necessidade.

O upload retorna um erro 404, o que pode ser isto?

Provavelmente a opção upload_url do swfupload não está correta. Não se esqueça de tornar o link absoluto ou relativo ao caminho do plugin.

Eu segui todos os passo na documentação, mas aina aparece um input de arquivos normal, o que pode ter acontecido?

Provavelmente você não colocou corretamento o arquivo swf ou não modificou a opção flash_url. Não se esqueça que esta opção é relativa ao template.

Eu posso customizar todas as opções do swfupload?

Sim, mas não é recomendado para esta primeira versão modificar os eventos, por que eles irão sobrescrever os eventos do plugin. Estou realizando o trabalho de estender todos os eventos do swfupload para o plugin para estender as opções existentes sem sobrescrever os eventos atuais. Por enquanto você pode usar os callbacks onFileSuccess e onFileError.

Eu fiz download do plugin e o arquivo upload.php não tem nenhuma lógica de realizar upload, o que aconteceu?

O script upload.php simplesmente prova que a cada upload realizado o script é chamado. O script pode ser escrito em diferentes linguagens de servidor e é assumido que quem esteja utilizando este plugin tem algum conhecimento prévio com envio de upload e o está utilizando para melhorar a experiência do usuário que é prejudicada com o upload de arquivos ormal. Se tiver algum exemplo de implementação do script de upload, por favor, entre em contato