Documentación de 'Attachments'

Versión 1.3 - 1 de Junio de 2008

1. Introducción
2. Restricciones de subida
3. Ajustes
4. Desplegar nombre de archivo
5. Estilizando la lista de archivos adjuntos
6. Iconos por tipo de archivo
7. Advertencias
8. Actualizando
9. Reconocimientos

Introducción

• http://jmcameron.net/attachments/email-list.html

Esta extensión provee capacidades de traducción y soporta los siguientes lenguajes (además de inglés):

• Bulgaro: Esta traducción fué realizada por Stefan Ilivanov. (Gracias Stefan!)
• Chino: Traducción al tradicional y simplificado por baijianpeng (http://www.joomlagate.com). (Gracias baijaing!)
• Holandés: Esta traducción fué realizada por Parvus. (Gracias Parvus!)
• Finlandés: Esta traducción fué realizada por Tapani Lehtonen. (Gracias Tapani!)
• Frances: Esta traducción fué realizada por Pascal Adalian. (Gracias Pascal!)
• Alemán: Esta traducción fué realizada por Michael Scherer. (Gracias Michael!)
• Griego: Esta traducción fué realizada por Harry Nakos. (Gracias Harry!)
• Italiano: Esta traducción fué realizada por Lemminkainen. (Gracias Lemminkainen!)
• Noruego: Esta traducción fué realizada por Espen Gjelsvik. ((Gracias Espen!)
• Polaco: Esta traducción fué realizada por Piotr Wójcik. ((Gracias Piotr!)
• Portugues/Brasileño: Esta traducción fué realizada por Arnaldo Giacomitti (www.giacomitti.eng.br) y Cauan Cabral (www.cauancabral.net).
• Español: Esta traducción fué 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:
  1. '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.
  2. '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:
  1. 'Solo el autor del artículo' - El vínculo para subir archivos solo será visible por el autor del artículo.(así como para otros usuarios con permisos de alto nivel como Editores y administradores).
  2. '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 número de descargas: Este ajuste controla si el némero de descargas es mostrado en la lista de archivos adjuntos. ADVERTENCIA: Esta opción solo funciona en el modo seguro! en el modo no seguro, los archivos se mantienen como archivos estáticos y son accesados directamente, sin pasar por el código de Joomla!. Por lo cual es imposible actualizar el número de descargas para un archivo cuando se accesa de esta manera. El despliegue de el número de descargas solo funcionará cuando la opción de modo seguro esté establecida como 'Sí'.
• 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.
• Format de la cadena para la fecha de modificación: Usted puede seleccionar el formato para la fecha de modificación usando el formato de la función PHP strftime(). Busque en la web 'PHP strftime' para ejemplos de uso. El formato por defecto es (%s %H:%M) este genera fechas con tiempo de 24 horas como el siguiente 4/28/2008 14:21. Para remover el tiempo de la parte del día, deje la parte de "%H:%M". Note que las implementaciones de MS Windows y Linux PHP pueden diferir en algunos de los códigos que soporta.
• Nombre para el cambo definido por usuario 1-3: Si usted tiene información adicional acerca de un archivo adjunto y lo desea agregar, la extensión le permite definir hasta tres campos definidos por el usuario. Para crear un nuevo campo, inserte el nombre en una de las tres entradas. Limpie el nombre para deshabilitar el despliegue y edición de este campo. Los campos definidos por el usuario serán mostrados en este orden. La longitud máxima de cada campo definido por el ususario es de 40 caracteres. Los datos en estos campos pueden ser de hasta 100 caracteres de longitud.
• Orden de la lista de archivos adjuntos: Esta opción permite especificar el orden en la cual la lista de archivos adjuntos sera mostrada. La mayoría de las opciones son explicadas por el nombre:
  1. 'Nombre de archivo' - Si se selecciona esta opción, la lista de archivos adjuntos será odenada alfabéticamente por el nombre de archivo.
  2. 'Tamaño de archivo(más pequeño al inicio)'
  3. 'Tamaño de archivo(más grande al inicio)'
  4. 'Descripción'
  5. 'Fecha de creación (el más antiguo primero)'
  6. 'Fecha de creación (el más nuevo primero)'
  7. 'Fecha de modificación (el más antiguo primero)'
  8. 'Fecha de modificación (el más nuevo primero)'
  9. 'ID de archivo adjunto' - Si se selecciona esta opción, los archivos adjuntos seran ordenados por el ID del mismo. Esto tendrá el efecto de ordenarlos en el órden en que fueron creados.
• 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:
  1. '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.
  2. '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..
  3. '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 subir archivos: El código de la extensión pondra los archivos dentro de este subdirectorio, bajo el directorio principal de Joomla. El directorio por defecto es 'attachments'. Note que si el subdirectorio es cambiado, este solo afectara archivos subidos en el futuro. Los archivos previamente subidos se quedaran en el subdirectorio anterior y los registros en la base de datos aún apuntarán al directorio anterios.Si desea mover los archivos del subdirectorio antiguo al nuevo, usted necesitara mover los archivos y luego actualizar sus registros en la base da datos manualmente.
• 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.
  
  Nota: Si desea cambiar los títulos utilizados para el listado de archivos adjuntos globalmente, usted puede editar el archivo de traducción en la entrada 'ATTACHMENTS TITLE':

      administrator/language/qq-QQ/qq-QQ.plg_frontend_attachments.ini
  

  Donde qq-QQ se refiere al designador de lenguaje tal como en-GB for English. (Si usted no está familiarizado con los archivos de traducción de Joomla!, busque la linea que contiene 'ATTACHMENTS TITLE' en el lado izquierdo del signo de '='. Edite lo que se encuentra a la derecha del signo de '='. No cambie nada en el lado izquierdo del signo '='.)
• 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.
• Si usted no puede ver el módulo de attachments en el front end, existen varias razones posibles:
  • El plugin de 'Content - Attachments' no está habilitado. Use el administrador de plugin para habilitarlo.
  • La opción 'Quien puede ver los archivos adjuntos' está establecido en 'Usuario autentificado' y usted no está autentificado. Esto se puede cambiar via el editor de parametros en el administrador de componentes.
  • En 'Content - Attachments' (via el administrador de plugins), El nivel de acceso no está establecido en 'Publico'.
  • El modo seguro está habilitado y usted no está autentificado. Usted debe de estar autentificado para poder descargar archivos en modo seguro, estos nunca serán desplegados sin importar lo que otros parametros indiquen, solo hasta que este autentificado.
• Si usted encuentra limites en el tamaño de los archivos que usted intenta subir, trate de agregar las siguienres lineas a su archivo de .htaccess en la raiz de su sitio Joomla!:

    php_value upload_max_filesize 32M
    php_value post_max_size 32M
  

  aquí usted podra cambiar el valor de 32M (megabytes) al valor que usted desee como tamaño maximo de subida.
• Existe un foro de ayuda y preguntas frecuentes para esta extensión, este esta alojado en el sitio de Joomlacode. Si usted en cuentra un problema que no esta cubierto en este archivo de ayuda, por favor consulte los foros:
  • Attachments Forums at Joomlacode.org

[Regresar]

Actualizando

Si usted ha agregado archivos adjuntos y desea preservarlos después de una actualización, use los siguientes pasos:

1. [Este paso es opcional pero recomendado, esto le permitira estar seguro con un respaldo de la base de datos del módulo en caso de que algo salga mal.]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'). Usted también debe de respaldar el directorio a donde fueron subidos los archivos (usualmente el directorio 'attachments' )
2. Vaya al adminsitrador de archivos adjuntos en el back end y de click en el objeto nombtado "Administrador" al lado derecho de la barra de herramientas. De click en el comando 'Deshabilitar la desinstalación de la tabla MySQL de archivos adjuntos'. Esto deshabilitará la eliminación de la tabla durante la desinstalación del componente.
3. Desinstale el componente 'Attachments'.
4. Desinstale ambos plugins de 'Attachments'.
5. Instale la nueva versión descomprimiendo el archivo e instalando el plugin y el componente del programa. Durante la instalación del componente, la base de datos de archivos adjuntos sera actualizada automaticamente.
6. Re habilite el plugin de 'Attachments'.
7. Sus archivos adjuntos deben de estar disponibles ahora. Vaya al administrador de archivos adjuntos en el back end administrativo para verificar que sus archivos estén correctos.

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:
  • The Silk icons by Mark James (http://www.famfamfam.com/lab/icons/silk/)
  • File-Type Icons 1.2 by John Zaitseff (http://www.zap.org.au/documents/icons/file-icons/sample.html)
  • Doctype Icons 2 by Timothy Groves (http://www.brandspankingnew.net/archive/2006/06/doctype_icons_2.html)
  • OpenDocument icons proposed by Pete Harlow (http://www.catnip.co.uk/opendocument/icons/)
  • Sweeties Base Pack by Joseph North (http://sweetie.sublink.ca)

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 error o sugerencia a jmcameron@jmcameron.net.