Upload de arquivos com 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.

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:
[sourcecode language=”html”]

 

 

 

 

[/sourcecode] 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:
[sourcecode language=”html”]

[/sourcecode] Com esta marcação você pode invocar o plugin com as seguintes opções:
[sourcecode language=”javascript”]$(“#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’

});

[/sourcecode] 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.
[sourcecode language=”js”] $(‘container’).jqswfupload(Object plugin_options, Object swfupload_options);

[/sourcecode]

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:

[sourcecode language=”javascript”]

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”

},

[/sourcecode]

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