Documentação do Anexos
Versão 1.2 - Fevereiro 20, 2008
- Introdução
- Restrições de Envio
- Configurações
- Exibir nome de arquivos
- Estilizando a Lista de Anexos
- Ícones dos Tipos de Arquivos
- Avisos
- Atualizando
- Agradecimentos
Introdução
A extensão 'Anexos' para o Joomla! permite enviar arquivos
e anexa-los ao conteúdo dos artigos. 'Anexos' inclui um plugin
para mostrar os anexos e um componente para enviar e administrar os anexos.
Há opções para controlar quem pode ver e quem pode baixar os anexos, juntamente
com várias outras opções para aumentar a flexibilidade e recursos. Nota: todas
as opções são controlado na administração do componente. Esta extesão funciona
apenas com Joomla! 1.5 ou posterior.
Esta estensão pode ser traduzida e suporta as seguintes linguagens ( além do Português ):
- Chinês: Tradução para o chinês Tradicional e Simplificado realizada por
baijianpeng (http://www.joomlagate.com). (Obrigado baijaing!)
- Holandês: Tradução realizada por Parvus. (Obrigado Parvus!)
- Alemão: Tradução realizada por Michael Scherer. (Obrigado Michael!)
- Finlandês: Tradução realizada por Tapani Lehtonen. (Obrigado Tapani!)
- Norueguês: Tradução realizada por Espen Gjelsvik. (Obrigado Espen!)
- Inglês: Ajuda original, feita por Jonatham (veja como contactar o autor ao final)
- Espanhol: Tradução realizada por Carlos Alfaro. (Obrigado Carlos!)
Muito obrigadod aos tradutores! Se você possui interesse em traduzir a extensão
para qualquer outra linguagem, entre em contato com o autor (veja como no final).
[Voltar ao Início]
Restrições de Envio
Nem todos os tipos de arquivos podem ser enviados. A extensão 'Anexos'
não permitirá envio de arquivos que não são autorizados pela Administração de Mídia do Joomla!.
Para ver ( ou alterar ) quais tipos de arquivos são permitidos, vá até página das
Configuração Global e clique na aba Sistema. Na área Configurações de Mídia,
estão as opções para controlar quais extensões de arquivos e tipos mime são permitidos para envio.
A extensão 'Anexos' respeita estas limitações. Contudo, as restrições em
'Extensões de Imagens Permitidas (Tipos de Arquivo)’ são ignoradas.
[Voltar ao Início]
Configurações dos Anexos
Todas as configurações da extensão 'Anexos' são
controlados pela administração do componente. Para acessar estas configurações,
vá para área administrativa e selecione "Anexos de Artigos" no menu "Componente".
Clique no botão "Parâmetros" no canto direito da barra de ferramentas e você verá
uma séride de parâmetros para está extensão. Estes parâmetros incluem o seguinte:
- Quem pode ver os anexos: Esta configuração controla
quem está habilitado a ver os links para os anexos. Existem atualmente
duas opções:
- ’Qualquer um’ - Se está opção é selecionada, os links para
os anexos serão vistos por qualquer um que visite seu site, estando logado
ou não.
- ’Todo usuários logados’. - Se está opção é selecionada, apenas
usuários que estão logado no seu site poderão ver os links para os anexos.
- Quem pode adicionar anexos: Esta configuração controla
quem está habilitado a adicionar anexos nos artigos. Existem duas opções:
- ’Apenas o Autor do artigo’ - O link para enviar anexos ao artigo
será visível apenas para o autor do artigo.
- ’Todo usuário logado’ - O link para enviar anexos ao artigo será
visível para qualquer usuário logado.
- Publicar anexos por padrão: A 'publicação automática'
controla se os anexos serão publicados logo após serem inseridos. Se 'Sim'
estiver selecionado, quando um artigo for inserido, ele será publicado imediatamente
e estará visível aos usuários. Se 'No' estiver selecionado, o novo artigo
não será publicado imediatamente. Um administrador terá de publica-lo pela área
administrativa do site para que fique disponível.
- Aviso de Auto Publicação: Se a publicação imediata estiver
desativada ( veja a opção anterior ), você pode querer informar como proceder
para ter o anexo publicado. Você pode inserir uma mensagem apropriada aqui.
Se este campo estiver vazio, uma mensagem do sistema será adicionada sugerindo
que o usuário entre em contato com o administrador do sistema para que publique
os novos anexos.
- Mostrar titulos: Se marcar 'Sim', uma linha de titulos será
adicionada acima da lista de anexos explicando o que é cada coluna.
- Mostrar descrição do anexo: Esta opção controla
a exibição da descrição do anexo na lista de anexos.
- Mostrar tamanho do arquivo: Esta opção controla
a exibição do tamanho do arquivo na lista de anexos.
- Mostrar quando o arquivo foi alterado: Se marcar esta
opção como 'Sim’, a data de quando o arquivo foi alterado será
adicionada a lista de anexos nos artigos que possuirem anexos. Se 'Não' estiver
marcado, nenhuma data será mostrada na lista de anexos.
- Formato da string para a data de alteração do arquivo: Você deve
selecionar o formato para a data de alterção do arquivo usando o formado
da função date do PHP. Esta configuração padrão "M-j-Y g:ia" nos mostra
algo parecido com isto: "Sep-29-2007 5:05pm". Se você prefere que seja mostrada
apenas a data, remova a parte "g:ia" da string.
- Tamanho máximo do nome de arquivo:
O tamanho máximo do nome de arquivo para a lista de anexos. Nomes de arquivos
maiores que este serão truncados e mostrados na tela ( apenas para apresentação,
o nome atual do arquivo não será alterado ). Use o valor 0 para ter nomes de arquivos
de tamanho ilimitado. Nota: Se o nome do arquivo for trucado por esta opção,
o nome truncado será inserido no campo "Nome do arquivo exibido".
- Estilo CSS para tabela de anexos: Para sobrescrever o estilo
CSS da lista de anexos, especifique o nome do seu estilo. O nome do estilo padrão
é 'attachmentsList'. Veja a seção [Estilizando a Lista de Anexos]
para maiores informações.
- Modo de abertura do arquivo:
Esta opção define como os links de anexos serão abertos. 'Na mesma janela' faz
com que seja aberto na mesma janela do navegador. 'Em nova janela' faz com que
seja aberto em uma nova janela. Em alguns navegadores, usando a opção
'Na mesma janela' o anexo será aberto em uma nova aba.
- Prefixo para o nome do arquivo no sistema: Esta configuração
controla se um prefixo numérico deverá ser adicionado ao nome do arquivo quando
ele for salvo no servidor. Existem três opções:
- ’ID do Artigo’ - Se esta opção é selecionada, o nome do arquivo
será precedido com o numéro id do artigo. Esta escolha reduzirá a chande de colisões
entre os nomes de arquivos e garante que um arquivo de anexo de um determinado artigo
fique ordenado junto na listagem do diretório. Note também que esta opção permite que
diferentes arquivos com o mesmo nome sejam anexados a artigos diferentes, mas não
no mesmo artigo.
- ’ID do Anexo’ - Se está opção for selecionada, o nome do arquivo
será precedico com o numéro id do anexo. Esta escolha eliminará a possibilidade de
colisões entre nomes de arquivos, já que cada anexo tem um número id único.
Os arquivos de anexo serão ordenados pela ordem dos anexos na listagem de diretório.
- ’Nada’ - Quano esta opção é selecionada, o nome do arquivo
será salvo como enviado, e não será precedido por nada. Esta opção aumenta a chance
de colisões entre os nomes de arquivos, já que todo arquivo enviado deverá ter
um nome único.
- Subdiretório para Envio: A extensão 'Anexos'
colocará os arqvuios neste subdiretório, usando como base o diretório
raiz do site Joomla!. AVISO: Se isto for altertado, você deve criar um
novo subdiretório manualmente antes de enviar qualquer arquivo.
Note que se o diretório for alterado, ele só será utilizado para futuros
envios. Arquivos enviados anteriormente continuarão gravados no subdiretório
antigo, tendo seu local mantido no banco de dados dos anexos.
- Titulos personalizados para lista de anexos: Por padrão,
a extensão 'Anexos' insere o titulo 'Anexos:' acima da lista
de anexos para um artigo ( se ele possuir anexos ). Em alguns casos, você
pode querer usar outro termo para um artigo especifico. Você deve especificar
exatamente o termo que gostaria de usar artigo-por-artigo. Por exemplo, se
você quer que o artigo 211 use um titulo personalizado 'Baixar:', adicione
isto a esta opção: '211 Downloads' ( sem aspas ). Use uma
entrada por linha.
- Esconder Anexos de:
Lista de valores separados por vírgula de palavras-chave ou Seções/Categorias de
artigos em que os anexos devam ser escondidos. Duas palavras-chave podem ser
utilizadas: 'frontpage' para não mostrar anexos na capa e 'all_but_article_views'
para permitir a exibição de anexos apenas ao visualizar artigos. (Omita as aspas
quando inserir as palavras-chave). O id da Seção/Categoria devem ser inseridos
como seus números IDs, separados por barra(/): Seção#/Categoria#, Seção#/Categoria#.
Use apenas 'Seção#' para atingir todas as categorias da seção.
Exemplo: 23/10, 23/11, 24
- Proteção para baixar anexos: Por padrão, a extensão 'Anexos'
salva os arquivos de anexo em um subdiretório de acesso público. Se você escolher
a opção seguro, o diretório em que o anexo será salvo ficará publicamente inacessível.
O link para baixar o arquivo na página estará disponível, mas não será um link direto. Isto
previne acesso de pessoas que não possuirem os privilégios adequados. Se seguro estiver
desmarcado, os links estarão acessíveis a qualquer um que souber a URL completa, desde que o
subdiretório seja público. A opção seguro previne acesso de usuários sem permissões
mesmo que ele saiba a URL completa, já que está opção previne acesso ao subdiretório de
anexos. NOTA: No modo 'seguro', a lista de anexos não será mostrada quando o usuário estiver
deslogado, porque não faz sentido usar modo seguro a menos que o usuário esteja logado.
- Forma de baixar o arquivo em modo seguro:
Esta opção controla se os arquivos serão baixados como arquivos independentes ou mostrados
no navegador ( se o navegador puder moostrar o tipo de arquivo ). Existem duas opções:
- Aninhado: Neste modo, arquivos que podem ser mostrados pelo navegador serão
mostrados no navegador ( arquivos de texto e de imagem, por exemplo ).
- Anexo: Com o modo 'anexo", os arquivos serão sempre baixados, separada da página.
Em ambos os casos, arquivos que não podem ser mostrados no navegador, serão baixados separada
da página.
[Voltar ao Inicio]
Mostrar nome de arquivo
Normalmente, quando um arquivo é enviado e listado na lista de anexos, o
nome de arquivo completo é exibido como um link para baixar o anexo. Em alguns
casos, o nome do arquivo pode ser muito grande para que isto funcione bem. No
formulário de envio, há um outro campo chamado "Mostrar nome de arquivo" onde
a pessoa que está enviando o arquivo pode inserir um nome alternativo ou uma
legenda para ser exibida no lugar do nome do arquivo inteiro. Por exemplo,
uma abreviação do nome do arquivo pode ser inserida neste campo. O campo poderá
ser editado na parte administrativa do site quando o anexo está sendo editado.
Nota: Há uma opção chamada "Tamanho Máximo do nome de arquivo" nas opções do
plugin. Ele poderá ser usado para truncar automaticamente o nome do arquivo enviado
para mostrar; o nome de arquivo truncado será inserido no campo "Mostar nome de arquivo".
[Voltar ao Inicio]
Estilizando a Lista de Anexos
A lista de anexos exibida na página utiliza um 'div' que
contem a tabela de anexos. A tabela está associada a algumas classes CSS
que permitem ao desenvolvedor do site personalizar a aparência da tabela.
Vá ao arquivo CSS na pasta do plugin anexos ( em plugins/content/attachments.css )
para alguns exemplos. Se você desejar alterar o estilo, considere copiar o
estilo original e cola-lo ao final do arquivo, e então alterar o nome
'attachmentList' na seção copiada, para outro de sua escolha. Na Admintradação
do componente Anexos, altere o parâmetro estilo da tabela de anexos
do plugin para o novo nome da classe. Então modifique apropriadamente as
definições da classe na seção copiada. Esta abordagem permitirá que você
volte rapidamente ao estilo original alterando o parâmetro estilo da tabela
de anexos do plugin de volta para o padrão ' attachmentList’.
Isto também tem como vantagem que a seção modificada poderá ser copiada para um
arquivo separado e reutilizada quando o Anexos for atualizado. Isto também pode
ser feito via o comando CSS @import.
[Voltar ao Início]
Ícones dos Tipos de Arquivos
A extensão 'Anexos' adiciona um ícone na lista de anexo, a frente de cada anexo.
Se você desejar adicionar um novo tipo de ícone, siga os seguintes passos:
(1) Adicione um ícone apropriado no diretório 'media/attachments/icons', se
um ícone apropriado ainda não existir aqui; (2) Edite o arquivo
'component/com_attachments/file_types.php' e adicione uma linha apropriada
no array estático $attachments_icon_from_file_extension associando a extensão
do arquivo ao nome do ícone ( qualquer um no diretório media/attachments/icons ).
Se isto não funcionar, você talvez precise adicionar uma linha apropriada no
array $attachments_icon_from_mime_type. (3) Não se esqueça de fazer uma cópia
dos ícones e do arquivo file_types.php atualizado em algum diretório fora dos
diretórios do site, antes de fazer uma atualização para uma nova versão do Anexos.
[Voltar ao Inicio]
Avisos
- Se você possui arquivos de anexo que são sigilosos ou privados,
use a opção Proteção para baixar anexos!
Se você não utilizar está
opção de segurança, os arquivos de anexo serão salvos em um subdiretório
público e estarão acessivies a qulquer um que souber a URL completa. A opção
seguro previne acesso por qualquer pessoa que não possua as permissões
adequadas ( como determinado pelas opções acima ). Veja a descrição de
Proteção para baixar anexos acima para mais detalhes.
- Toda vez que um arquivo é enviado, a existência de um subdiretório de
envio é verificada, criando o diretório caso o mesmo não exista. Se a
extensão 'Anexos' estiver inabilitada para criar um subdiretório
para envio, você deverá criar manualmente (e você poderá ter problemas
para enviar arquivos). Tenha certeza de alterar as permissões do subdiretório
para enviar arquivos. No mundo Unix/Linux, será algo como 744.
- Se esta extensão não permitir o envio de alguns tipos especificos de arquivos
(como arquivos zip), esteja ciente que a extensão respeita as restrições
impostas pelo Administrador de Mídia sobre os tipos de arquivos permitidos para envio.
Isto tem como objetivo previnir o envio de alguns tipos de arquivos potencialmente
perigosos como html ou php. O administrador pode atualizar as configurações do
Administrador de Mídia para adicionar tipos de arquivos especificos indo em
"Configurações Globais" e selecionando a aba "Sistema", depois adicionando
a extensão de arquivos apropriada e o tipo Mime à lista da seção "Administrador de Mídia".
- O segundo plugin, 'add_attachment_btn_plugin' ( chamado 'Button - AddAttachment'
no administrador de plugin ) permite que anexos sejam adicionados aos artigos
enquanto eles estão sendo editados no editor de artigos. Este plugin insere
um botão abaixo da área de edição do artigo intitulado "Adicionar Anexo". Se você
instalou este plugin mas não vê este botão, o plugin que adiciona o botão para anexos
provávelmente deverá ser habilitado no editor do plugin.
- Está versão aparenta trabalhar corretamente com SEF no Joomla! 1.5 RC3 e RC4. As atualizações
para o 'Anexos' do RC3 parecem parar o SEF with RC2.
[Voltar ao Início]
Atualizando
Se você tiver anexos adionados e quiser preservalos após a atualização,
siga os seguintes passos:
- Use o phpMyAdmin (ou qualquer outra ferramente de manipulação SQL) para
salvar o conteudo da tabela jos_attachments (usando a opção 'Export', use
inserções 'Complete' e não 'Extended' para dados)
- Desinstale o componente 'Anexos' . Se o Joomla! acusar que
não pode deletar o arquivos de mídia, você terá de deletar o diretório
/media/attachments manualmente.
- Desisntale o plugin 'Anexos’
- Agora instale a nova versão descompactando o arquivo da versão e
instalando o novo plugin e componente.
- Habilite novamente o plugin 'Anexos’.
- Finalmente, use o phpMyAdmin para recarregar as informações dos anexos
previamente salvas na nova tabela jos_attachments.
- Se você estiver atualizando de uma versão anterior a 1.0 para uma pós 1.0 e
você tiver anexos antigos, você terá de inserir os valores apropriados para
o novo campo 'icon_filename' se logando como administrador e
inserindo a URL abaixo no navegador:
/administrator/index.php?option=com_attachments&task=add_icon_filenames
Note que a desinstalação da extensão 'Anexos' não deletará arquivos
enviados anteriormente, mas os removerá da tabela de anexos no bando de dados. Então
ao reinstalar uma nova versão do 'Anexos’, você terá apenas de restaurar
a tabela de anexos para restaurar os antigos anexos.
Se você decidir não restaurar o banco de dados dos anexos, não esqueça de excluir
qualquer arquivo antigo enviado no subdiretório de anexos para eliminar complitos
com os nomes de arquivos no futuro.
[Voltar ao Inicio]
Agradecimentos
Muito obrigado para os contribuidores e recursos abaixo
- O Livro Learning Joomla! 1.5 Extension Development: Creating Modules,
Components, and Plugins with PHP de Joseph L. LeBlanc foi de grande ajuda
na criação da extensão 'Anexos'.
- Os icones dos tipos de arquivos foram retirados de várias fontes, incluindo:
Note que vários dos ícones do 'Anexos' foram modificados em relação ao
original destes sites. Se você gostaria de ter as versões originais,
baixe-os dos próprios sites.
[Voltar ao Inicio]
Por favor, reporte bugs e sugestões para jmcameron@jmcameron.net ( em inglês ).