Documentación de 'Attachments'
Versión 1.2 - Febrero 20, 2008
- Introducción
- Restricciones de subida
- Ajustes
- Desplegar nombre de archivo
- Estilizando la lista de archivos adjuntos
- Iconos por tipo de archivo
- Advertencias
- Actualizando
- Reconocimientos
Introducción
La extensión de 'Attachments' para Joomla! le permite subir archivos y
adjuntarlos a artículos. 'Attachments' incluye un plugin para
desplegar la lista de archivos adjuntos y un componente para subir
y administrar estos archivos. Existen varias opciones para
controlar quien puede ver y quien puede subir archivos, además de
muchas más opciones para incrementar la flexibilidad y usabilidad
del mismo. Nota: todas las opciones son controladas a través
del administrador de componentes. Esta extensión solo
funciona con Joomla! 1.5 o mas nuevo.
Esta extensión provee capacidades de traducción y soporta
los siguientes lenguajes (además de inglés):
- Chino:
Traducción al tradicional y simplificado por baijianpeng
(http://www.joomlagate.com). (Gracias baijaing!)
- Holandés: Esta traducción fue realizada por Parvus. (Gracias Parvus!)
- Alemán: Esta traducción fue realizada por Michael Scherer. (Gracias Michael!)
- Finlandés: Esta traducción fue realizada por Tapani Lehtonen. (Gracias Tapani!)
- Noruego: Esta traducción fue realizada por Espen Gjelsvik. (Gracias Espen!)
- Portugues/Brazileño: Esta traducción fue realizada por Arnaldo Giacomitti
(www.giacomitti.eng.br) y Cauan Cabral (www.cauancabral.net).
- Español: Esta traducción fue realizada por Carlos Alfaro. (Gracias Carlos!)
Muchas gracias a los traductores! Si deseas ayudar a traducir esta extensión
a cualquier otro lenguaje, por favor contacta al autor.(ver al final).
[Regresar]
Restricciones de subida
No todos los tipos de archivos pueden ser subidos. El componente
de 'Attachments' no permitirá subir archivos que no estén
previamente autorizados por el administrador de medios de
Joomla!
Para ver (o cambiar) que tipo de archivo están permitidos, vaya a
la página de Configuración Global y oprima en la pestaña
de Sistema. En el área de Ajustes de Medios,
existen opciones para controlar que extensiones y tipos mime están
permitidos para subir. 'Attachments' respeta estas
limitaciones, la restricción en 'Extensión de Imagen Legal' es
ignorada. [Regresar]
Ajustes
Todos los ajustes para 'Attachments' son controlados vía el
administrador de componentes. Para accesar estos ajustes, vaya al área de
administrador y seleccione "Archivos Adjuntos" bajo el menú de
"Componentes". Presione en el botón de "Parámetros" el cual se
encuentra en el lado derecho de la barra de herramientas y usted
verá una serie de parámetros para esta extensión. Entre los
parámetros podemos encontrar los siguientes:
- Quien
puede ver los archivos adjuntos: Este
ajuste controla quien podrá ver los vínculos a los archivos.
Actualmente existen 2 opciones:
- 'Todos'
- Si se selecciona esta opción, los vínculos a los archivos
adjuntos serán visibles por todos los que visiten el sitio, sin
importar si están autentificados o no.
- 'Cualquier usuario autentificado'. - Si esta opción
es seleccionada, solo los usuarios que están autentificados en
el sitio podrán ver los vínculos a los archivos adjuntos.
- Quien puede agregar archivos adjuntos: Este
ajuste controla quien puede agregar archivos a los artículos.
Existen dos opciones:
- 'Solo el autor del artículo' - El vínculo para subir archivos solo
será visible por el autor del artículo.
- 'Cualquier
usuario autentificado' - Los vínculos para subir archivos será
visible por cualquier usuario que este autentificado.
- Archivos adjuntos publicados por defecto: Esta
característica de 'auto publicación' controla si los archivos
son publicados por defecto al ser subidos. Si se seleccionamos
'Si', cuando los archivos se adjuntan, serán publicados
inmediatamente y podrán ser vistos por los demás. Si seleccionamos
'No', los nuevos archivos no serán publicados por defecto. Un
administrador tendrá que publicarlos manualmente a través de la
página de administración.
- Advertencia de auto publicación: Si la
opción de auto publicación está deshabilitada (ver la opción
anterior), usted deseará informarle al usuario como puede auto
publicar sus archivos adjuntos. Usted puede insertar un mensaje
apropiado para hacerlo. Si el campo esta vacio, un mensaje general
de sistema será agregado el cual indica que se contacte al
administrador del sistema para publicar cualquier archivo
recientemente agregado.
- Mostrar títulos: Si se
establece como 'Si', se agregara un renglón de títulos sobre la
lista de archivos adjuntos, la cual describe que contiene cada
columna.
- Mostrar descripción del archivo:
Esta opción controla si se debe de mostrar la descripción en la
lista de archivos adjuntos.
- Mostrar tamaño de archivo: Esta
opción controla si el tamaño del archivo será mostrado en la lista
de archivos adjuntos.
- Mostrar fecha de modificación del archivo: Si
esta opción se establece como 'Si', la fecha de modificación
del archivo será agregada al artículo que cuente con archivos
adjuntos. Si se selecciona 'No', no se agregara la fecha a la lista
de archivos adjuntos.
- Formato de la cadena para la fecha de modificación: Usted
puede seleccionar el formato de la fecha de modificación usando el
formato de la función date de PHP. Este ajuste tiene como defecto
el formato "M-j-Y g:ia" el cual muestra algo similar a lo
siguiente: "Sep-29-2007 5:05pm". Si usted prefiere ver solo la
fecha, elimine la parte "g:ia".
- Longitud máxima del nombre de archivo: El
máximo de longitud del nombre de archivo en la lista. Los nombres
más largos que el especificado serán truncados (el truncado solo se
hace para propósitos visuales, el nombre real del archivo no será
modificado). Un valor de 0 significa que no existe límite en la
longitud (el campo de base de datos donde se almacena el nombre de
archivo está limitado a 80 caracteres). Nota: Si al desplegar los
nombres de archivos estos son truncados, el nombre de archivo
truncado será insertado en el campo de "desplegar nombre de
archivo".
- Estilo CSS para las tablas de archivos adjuntos: Para
pasar por alto el estilo CSS de la lista de archivos, especifique
su propio estilo aquí. El nombre por defecto es 'attachmentsList'.
Vea la sección de [Estilizando la lista de archivos
adjuntos] para más información.
- Modo de apertura del archivo: Esta
opción controla como serán mostrados los archivos al oprimir el
vínculo. 'En la misma ventana' significa que el archivo será
abierto en la misma ventana del navegador. 'En una nueva ventana'
significa que el archivo será abierto en una nueva ventana de
navegador. En algunos navegadores, al usar la opción 'En una nueva
ventana' abrirá el archivo en una nueva pestaña.
- Pre agregar al nombre del archivo en el sistema:
Este ajuste controla si el prefijo numérico debe de ser agregado al
inicio del archivo, tal y como está asignado en el servidor.
Existen tres opciones:
- 'ID del artículo' - Si se selecciona esta opción, el
nombre del archivo será pre fijada con el ID del artículo. Esta
selección reducirá la posibilidad de colisión de nombres de archivo y
asegurara que los archivos adjuntos a un artículo se ordenen en las
listas de directorios. Esta opción le permitirá diferentes archivos
con el mismo nombre de archivo, ya que irán adjuntos a diferentes
artículos, note que no debe de ser el mismo artículo ya que causará
una colisión.
- 'ID del archivo adjunto' - Si se selecciona esta opción,
el nombre de archivo será pre fijado con el ID del archivo adjunto.
Esta selección eliminara la posibilidad de colisión de nombre de archivo
ya que cada archivo tendrá un ID único. Los archivos se ordenaran
por el orden de los archivos adjuntos en la lista de
directorios..
- 'Ninguno'- Si se selecciona esta opción, el nombre de archivo
será grabado tal y como el archivo. Esta opción incrementa las oportunidades
de colisión de nombre de archivo, ya que, cada archivo necesitara
tener un nombre único.
- Subdirectorio para grabar archivos:
La extensión de 'Attachments' grabará los archivos en este
subdirectorio del sitio Joomla!. ADVERTENCIA: Si esto es
cambiado, usted deberá de crear el nuevo subdirectorio manualmente
antes de poder subir cualquier archivo. Note que si el
subdirectorio es cambiado, esto solo afectara los archivos
agregados en un futuro. Los archivos previamente grabados se
mantendrán en el subdirectorio anterior y los registros en la base
de datos aún apuntaran a esos archivos.
- Títulos personalizados para la lista de archivos adjuntos:
Por defecto, la extensión de 'Attachments' inserta el título "Archivos
adjuntos:" sobre la lista de archivos de un artículo (si este
cuenta con archivos). En algunos casos, usted puede preferir usar
algun otro termino para artículos específicos. Usted podrá
especificar el término exacto que desea usar en una base de
artículo-por-artículo. Por ejemplo, si desea que el artículo 211
use el título personalizado "Descargas:", entonces agregue lo
siguiente. '211 Descargas' (sin las comillas). Una entrada por
línea.
- Ocultar archivos adjuntos para: Lista de palabras clave separadas por coma or Sección/Categoría de los artículos para los cuales los archivos ocultos serpan ocultados. Se pueden utilizar dos palabras: 'Página frontal' para suprimir el despliegue de los archivos adjuntos en la página frontal, y 'todo_menos_vista_de_artículos' para permitir el despliegue de los archivos en las vistas de artículo. (Omita las comillas cuando ingrese las opciones de palabra clave) Los ids de Sección/Categoría deben de ser ingresados como id´s numericas de sección y categoría separados con una diagonal(/): Sección#/Categoría#, Sección#/Categoría#. Especifique solo la 'Sección#' para cubrir todas las categorías dentro de la selección. Ejemplo: 23/10, 23/11, 24
- Descarga segura de archivos: Por
defecto, la extensión de 'Attachments' graba los archivos en un
directorio públicamente accesible. Si usted selecciona la opción
segura, el directorio en el cual se graben los archivos será
inaccesible públicamente. Los vínculos para los archivos adjuntos
en el front end descargarán los archivos adjuntos pero no serán
vínculos directos al archivo en sí. Esto prevendrá el acceso a
menos que los usuarios tengan los permisos necesarios. Sí las
descargas seguras no son seleccionadas, los vínculos a los
archivos adjuntos serán mostrados como la opción previamente
indicada, pero los archivos serán aún accesibles por cualquiera que
conozca el URL completo, ya que el directorio es considerado como
público. La opción segura prevendrá el acceso a usuarios sin
los permisos adecuados, inclusive cuando el usuario conoce el URL
completo al archivo, ya que esta opción previene el acceso al
directorio de archivos adjuntos. NOTA: En el modo seguro, la
lista de archivos no es desplegada cuando el usuario no está
autentificado en el sistema, ya que no tiene sentido el usar el
modo seguro si el usuario no está autentificado.
- Modo de descarga segura: Esta
opción controla si los archivos deben de ser descargados como
archivos o desplegados por el navegador (si el navegador soporta
este tipo de archivo). Existen dos opciones:
- 'en
línea': En
este modo, los archivos que pueden ser desplegados por el
navegador, serán desplegados en él (tales como archivos de texto e
imágenes).
- 'archivo
adjunto': Con
este modo los archivos siempre serán descargados, nunca mostrados
en el navegador.
Si el archivo no puede ser desplegado por el navegador, será
descargado como archivo [Regresar]
Desplegar nombre de archivo
Normalmente, cuando los archivos son subidos y listados en la
lista de archivos adjuntos, el nombre completo del archivo es mostrado
como un vínculo para descargar el archivo. En algunos casos, el nombre
puede ser muy largo para que funcione correctamente. En la forma
para subir archivos, existe otro campo llamado "Desplegar
nombre de archivo" en el cual la persona que está grabando el
archivo puede insertar un nombre alternativo o etiqueta para
desplegar en lugar del nombre de archivo completo. Por ejemplo,
alguna abreviación del nombre de archivo puede ser utilizada en
este campo. Este campo puede ser editado en el área de
administración de Joomla! Nota: Existe una opción en las
opciones del plugin llamada "Longitud máxima de nombre de archivo".
Esta puede ser establecida a truncar automáticamente; el nombre de
archivo resultante será insertado en el campo de "Desplegar
nombre de archivo". [Regresar]
Estilizando la lista de archivos adjuntos
La lista de archivos adjuntos mostrada en el "Front End" usa un 'div'
especial el cual contiene una tabla para los archivos. La tabla
tiene diferentes clases CSS asociadas, las cuales permiten al
desarrollador del sitio la flexibilidad de personalizar la
apariencia de la tabla. Para ejemplos vea el archivo CSS en el
directorio del plugin (localizado en
plugins/content/attachments.css) . Si desea cambiar el estilo,
considere copiar el estilo original al final del archivo y
renombre 'attachmentsList' al nombre de su elección.
Edite el parámetro de Archivos adjuntos (en el administrador de
componentes) y cambie el parámetro Estilo CSS para las
tablas de archivos adjuntos por el nuevo nombre de la clase.
Después modifique la definición de la clase, de acuerdo a sus
requerimientos. Esto le permitirá fácilmente regresar al estilo
original cambiando el parámetro Estilo CSS para las tablas de
archivos adjuntos a su valor por defecto, 'attachmentList'.
Esto también nos da la opción de copiar los estilos modificados a
un archivo y así fácilmente restaurarla cuando la versión del
plugin sea actualizada. Esto también puede ser realizado usando el
comando de CSS @import. [Regresar]
Iconos por tipo de archivo
La extensión de 'Attachments' agrega un icono al inicio de cada
archivo en la lista de archivos adjuntos. Si desea agregar un nuevo
tipo de icono, siga los siguientes pasos: (1) Agregar el icono
apropiado en el directorio 'media/attachments/icons', si no existe
un icono apropiado; (2) Edite el archivo 'components/com_attachments/file_types.php'
y agregue una línea a el arreglo estático $attachments_icon_from_file_extension el cual
mapea una extensión de archivos a un nombre de archivo (los cuales
están en el directorio media/attachments/icons). Si esto no
funciona, usted necesitara una line al arreglo
$attachments_icon_from_mime_type. (3) No olvide hacer copias de los
iconos y el archivo file_types.php a algún directorio fuera
del sitio, esto lo debe de hacer antes de realizar alguna
actualización al módulo. [Regresar]
Advertencias
- Si tiene archivos con información confidencial o sensible, use la
opción de Modo de descarga segura!
Si usted no utiliza la opción segura, los archivos adjuntos son
grabados en un directorio público y será posible accesarlos por
cualquier que conozca el URL completo. La opción segura
previene el acceso de usuarios que no cuenten con los permisos
adecuados (de acuerdo a lo determinado por la opción previa). Vea
la discusión de Modo de descarga segura para mayor
detalle.
- Cada vez que se graba un archivo, se revisa si el subdirectorio donde
será subido existe y será creado si este no existe. Si la extensión
de 'Attachments' no puede crear el directorio, usted tendrá que
crearlo por su cuenta (y puede que tenga problemas al subir
archivos). Asegúrese de dar los permisos adecuados al directorio.
Si utiliza Unix/Linux, probablemente necesitara permisos del tipo
744.
- Si la extensión no le permite subir cierto tipo de archivo (como archivos
zip), asegúrese que la extensión respeta las restricciones
colocadas en el Administrador de medios. Esto es para prevenir el
grabar archivos dañinos tales como html o php. El administrador
puede actualizar la configuración del Administrador de medios para
agregar tipos de archivo específicos, esto lo lograra dirigiéndose
a la "Configuración Global" bajo el menú del "Sitio", seleccione la
pestaña "Sistema", agregue la extensión y el tipo mime a
la lista bajo la sección "Administrador de medios".
- El segundo plugin, 'add_attachment_btn_plugin' (llamado 'Button -
AddAttachment' en el administrador de plugin) permite agregar
archivos adjuntos a los artículos en el momento de editar
artículos. Este plugin agrega un botón bajo el área de edición de
artículos llamado "Agregar archivo adjunto". Si usted ha instalado
este plugin pero no ve el botón, el plugin del botón de agregar
archivo adjunto posiblemente necesite ser habilitado en el editor
de plugins. Nota: El botón no es desplegado cuando los artículos
están siendo creados, el artículo debe de ser grabado antes de
poder agregarle archivos adjuntos.
- Esta versión parece funcionar correctamente con SEF con Joomla! 1.5
RC3 y RC4. La actualización para 'Archivos adjuntos' del RC3 parece
quebrar el SEF con el RC2.
[Regresar]
Actualizando
Si usted ha agregado archivos adjuntos y desea preservarlos después de
una actualización, use los siguientes pasos:
- Use phpMyAdmin (u otro administrador de SQL) para grabar el contenido
de la tabla jos_attachments table (use la opción 'Exportar', intente usar la opción
inserciones 'Completas' pero no del tipo 'Extendido').
- Desinstale el componente 'Attachments'.
- Desinstale ambos plugins de 'Attachments'.
- Instale la nueva versión del el plugin y ambos componentes.
- Re habilite el plugin de 'Attachments'.
- Finalmente use phpMyAdmin para re alimentar los attachments grabados
previamente, estos deberán de alimentarse en la tabla
jos_attachments.
- Si usted está actualizando una versión anterior a la 1.0 a una más
reciente que la 1.0, y cuenta con attachments antiguos, usted
necesitara agregar los valores apropiados al campo 'icon_filename',
esto lo podrá hacer autentificándose como administrador en él y
dirigiéndose al siguiente URL en su navegador:
/administrator/index.php?option=com_attachments&task=add_icon_filenames
Note que al desinstalar la extensión de 'Attachments' esta no borra los
archivos que usted grabo, solamente elimina los registros de la
base de datos. Así que después de instalar la nueva versión,
solamente es necesario restaurar la tabla anterior para poder ver
los archivos adjuntos.
Si desea no restaurar la base de datos, no olvide borrar los archivos
obsoletos, esto con el propósito de evitar futuros problemas con
nombres de archivos duplicados. [Regresar]
Agradecimientos
Muchas gracias a los siguientes contribuyentes o recursos:
- El libro Learning Joomla! 1.5 Extension Development: Creating
Modules, Components, and Plugins with PHP por Joseph L. LeBlanc
fue de mucha ayuda en la creación de la extensión
de 'Attachments'.
- Los iconos para los tipos de archivos son derivados de las siguientes
fuentes:
Note que la mayoría de los iconos de 'Attachments' fueron
modificados de las versiones originales de los sitios. Si usted
desea las versiones originales, por favor descárguelos de los
sitios originales. [Regresar]
Por favor reporte cualquier errora o sugerencia a jmcameron@jmcameron.net.