Документация расширения 'Attachments' (Вложения)

Версия 1.3.4 - Август 2008

Введение
Ограничения на загрузку
Настройки
Отображение имен файлов
CSS стили списка вложений
Иконки типов файлов
Предупреждения
Обновление
Благодарности

Введение

Расширение 'Вложения' ('Attachments') для CMS Joomla позволяет загрузить файлы на сервер и прикрепить их к содержимому любой статьи. 'Вложения' включают в себя плагин для отображения вложений и компонент для загрузки и управления вложениями. Наряду с разными опциями увеличения гибкости и полезности в расширении присутсвуют опции контроля того, кто может видеть вложения и кто может их загружать.
Замечание: все опции управляются через менеджер компонент. Это расширение работает только в системе Joomla! версии 1.5 или старше.

Если вы хотите подписаться на рассылку обновлений этого расширения, пожалуйста воспользуйтесь этой страницей:

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

Это расширение обеспечивает возможности для перевода и поддерживает следующие языки (помимо Английского):

Болгарский: Этот перевод был выполнен Stefan Ilivanov. (Спасибо Stefan!)
Китайский: Традиционный и упрощенный китайские переводы baijianpeng (http://www.joomlagate.com). (Спасибо baijaing!)
Dutch: Этот перевод был выполнен Parvus. (Спасибо Parvus!)
Finnish: Этот перевод был выполнен Tapani Lehtonen. (Спасибо Tapani!)
French: Этот перевод был выполнен Pascal Adalian. (Спасибо Pascal!)
German: Этот перевод был выполнен Michael Scherer. (Спасибо Michael!)
Greek: Этот перевод был выполнен Harry Nakos. (Спасибо Harry!)
Italian: Этот перевод был выполнен Lemminkainen. (Спасибо Lemminkainen!)
Norwegian: Этот перевод был выполнен Espen Gjelsvik. (Спасибо Espen!)
Persian: Этот перевод был выполнен Hossein Moradgholi из проекта Parsjoomla. (Спасибо Hossein!)
Polish: Этот перевод был выполнен Piotr WСjcik. (Спасибо Piotr!)
Португальский/Бразильский: Этот перевод был выполнен Arnaldo Giacomitti (www.giacomitti.eng.br) а также Cauan Cabral (www.cauancabral.net).
Испанский: Этот перевод был выполнен Carlos Alfaro. (Спасибо Carlos!)
Русский: Этот перевод был выполнен Шаройко Ярославом. (И мне спасибо! :)

Большое спасибо переводчикам! Если вы хотите помочь с переводом расширения на другие языки, пожалуйста свяжитесь с автором (см. в конце). [Наверх]

Ограничения на загрузку

Не все типы файлов могут быть загружены. Расширение 'Вложения' ('Attachments') не разрешит загрузить файлы, которые запрещены в Joomla! Медиа Менеджере. Чтобы посмотреть (изменить) какие файлы разрешены - войдите на страницу Общие настройки и выберите вкладку Система. В разделе Установки Медиа менеджера указано какие типы файлов и какие mime типы разрешены для загрузки. Расширение 'Вложения' ('Attachments') соблюдает эти ограничения. Однако запрет на 'Допустимые расширения для картинок (типы файлов)' игнорируется. [Наверх]

Настройки

Все настройки для расширения управляются через менеджер компонент. Чтобы изменить настройки, откройте администротивный раздел (http://yousiteaddress/administrator) и выберите пункт меню "Компоненты"->"Вложения". Нажмите кнопку "Параметры" справа наверху и вы увидите список параметров для этого расширения. В него входят следующие пункты:

Кто может видеть вложения: Этот параметр управляет тем, кто сможет видеть ссылки на прикрепленные файлы. Существует два режима:
1. 'все' - если выбран этот режим, ссылки на вложения будут видны любому посетителю сайта, несмотря на то, зарегистрировался он или нет.
2. 'любой зарегистрированный пользователь'. - если выбран этот режим, только зарегистрированные пользователи увидят ссылки на прикрепленные файлы.
Кто может добавлять вложения: Этот параметр управляет тем, кто сможет добавлять вложения к статьям. Существует два варианта:
1. 'Только автор статьи' - ссылки для прикрепления файлов будут видны только авторам статьи (а также пользователям с более высокими правами, например Редактору или Администратору).
2. 'Любому зарегистрированному пользователю' - ссылки для прикрепления файлов будут видны любому зарегистрированному пользователю.
Публикация вложений по умолчанию: Эта возможность 'автоматической публикации' определяет будут ли новые вложения сразу же опубликованы на сайте при их добавлении или нет. Если выбрано 'Да', то когда статья с вложением будет добавлена, то она сразу же будут видна на сайте. Если же выбрано 'Нет', то для публикации нужно будет зайти в административную часть и установить там флажок опубликовано, что бы вложение появилось на сайте.
Предупреждение авто публикации Если отключена предыдущая опция (авто публикация), возможно вы захотите проинформировать пользователей как им опубликовать свои вложения. Здесь вы можете вставить соответствующий текст. Если это поле не заполнить, то будет отображаться стандартное системное сообщение предлагающее пользователю связаться с администратором для того что бы его новое вложение было опуликовано.
Показывать загаловки: Если установлено 'Да', то ряд заголовков будет показан над списком вложений, описывая что находится в каждой из колонок.
Показывать описание вложений: Эта опция определяет отображать или нет описание для каждого вложения в списке вложений.
Отображать размер файла: Эта опция определяет отображать или нет размер файла в списке вложений.
Отображать количество загрузок: Эта опция определяет отображать или нет количество загрузок в списке вложений
Предупреждение: Эта опция работает только в безопасном режиме! В противном случае файлы обрабатываются как статические файлы и доступ к ним осуществляется напрямую без прохождения через код Joomla! Поэтому невозможно подсчитать количество обращений к файлу в таком режиме. Таким образом эта опция будет работь только если выставлено значение 'Да' здесь, и также в разделе "безопасный режим".
Время модификации файла: Если эта опция установлена в значение 'Да', тогда в списке вложений появится время модификации каждого файла. Если 'Нет', то времени модификации не будет отображено.
Формат отображения строки время модификации: Вы можете указать формат отображения времени модификации используя тот же формат, что и в функции PHP strftime(). Примеры могут буть найдены в интернете по запросу 'PHP strftime' По умолчанию формат установлен (%x %H:%M), что дает 24 часовой формат вида: 4/28/2008 14:21. Чтобы избавиться от времени суток удалите часть содержащую "%H:%M". Учтите что реализации PHP под Windows и Linux системами могут отличаться.
Имя для определенных пользователем полей 1-3 Если у вас есть дополнительная информация о каждом из вложений и вы хотите её опубликовать, то расширение позволяет вам определить до 3-х полей с такой информацией. Чтобы создать такое новое дополнительное поле ввдете его имя в одной из трех областей ввода. Очистите область ввода чтобы отключить редактирование и отображение этого поля. Поля определенные пользователем будут отображаться в том же порядке, что и здесь. Максимальная длинна каждого поля ограничена 40 символами. Общая же длина не должна превышать 100 символов.
Порядок отображения вложений: Эта опция позволяет указать порядок в котором будут отображены файлы внутри вложения в списке вложений. Большинство названий говорят сами за себя:
1. 'Сортировать по имени файла' - Если выбран этот режим, то прикрепленные файлы будут отсортированы в алфавитном порядке по своим именам.
2. 'Сортировать по размеру файла (сперва меньшие)'
3. 'Сортировать по размеру файла (сперва большие)'
4. 'Сортировать по описанию'
5. 'Сортировать по дате создания (сперва старые)'
6. 'Сортировать по дате создания (сперва новые)'
7. 'Сортировать по дате модификации (сперва старые)'
8. 'Сортировать по дате модификации (сперва новые)'
9. 'Сортировать по идентификатору вложения' - Если выбран этот режим, то прикрепленные файлы будут отсортированны по идентификатору вложения. Это равнозначно сортировке в порядке их создания.
10. 'Определенное пользователем поле 1'
11. 'Определенное пользователем поле 2'
12. 'Определенное пользователем поле 3'
Максимальная длина имени файла: Максимальная длина имени файла в списке вложений. Имена файлов чья длина больше этого значения будут обрезаны и перенесены в поле "Отображать имя файла как" (Это только для отображения, настоящее имя файла не измениться) Значение 0 означает отсутсвие ограничений на длину файла, за исключением ограничения бызы данных. Оно состовляет 80 символов.
Замечание: Если имя файла обрезано этой опцией (не базой данных), то обрезанное имя автоматически переноситься в поле "Отображать имя файла как"
CSS стиль для таблиц вложений: Чтобы перезаписать CSS стили списков (таблиц) вложения укажите здесь имя вашего стиля. По умолчанию имя стиля - 'attachmentsList'. Смотрите раздел [CSS стили списка вложений] для более подробной информации.
Режим открытия файлов: Этот режим опредляет как ссылки на прикрепленные файлы будут открываться.
'В том же окне' означает что файл будет открыт в том же самом окне браузера
'В новом окне' означает что файл будет открыт в новом окне.
В некоторых браузерах опция 'В новом окне' на самом деле открывает файл в новой вкладке браузера. Это зависит от настроек самого браузера.
Добавлять к системному имени файла что-либо? Эта опция определяет следует или нет добавлять к системному имени файла на сервере числовой префикс. Существует три варианта:
1. 'Идентификатор статьи' - Если выбран этот режим, то к имени файла будет добавлен идентификатор статьи к которой он прикреплен. Этот режим уменьшает шансы появления одинаковых файлов и позволяет быть уверенным что файлы одной статьи будут отсортированны рядом внутри каталога вложений. Учтите, что эта опция позволяет файлам с одинкавыми именами быть добавлеными к разным статьям, но не к одной и той же статье.
2. 'Идентификатор вложения' - Если выбран этот режим, то к имени файла будет добавлен идентификатор вложения. Этот режим исключает возможность появления одинаковых файлов на сервере, так как идетификатор вложения уникален для каждого файла. Файлы вложения в этом случае будут осортированны в каталоге в порядке прикрепления.
3. 'Ничего' - Если выбран этот режим, то файлы будут сохраняться без изменения. Этот режим увеличивает шансы появления файлов с одинаковыми именами.
Каталог для загружаемых файлов: Код расширения 'Вложения' складывает прикрепляемые файлы в каталог сайта. По умолчанию это каталог 'attachments'. Помните, что если вы изменили этот каталог, то это повлияет только на вновь загружаемые файлы. Ранее загруженные файлы останутся в старом каталоге и записи в таблице будут попрежнему указывть в старый каталог. Если вы хотите переместить эти файлы из старого каталога в новый, вам необходимо сделать это самому, а затем изменить записи в таблице вложений вручную.
Дополнительные заголовки в списке вложений: По умолчанию расширение "Вложения" вставляет заголовок "Вложения:" поверх спсика вложений статьи (если та имеет прикрепленные файлы). В некоторых случаях вам возможно захочется использовать особый заголовок для некотоых статей. Вы можетет указать особый заголовок для кокретной статьи. Например, если вы хотите чтобы статья 211 имела заголовок "Загрузки:", тогда добавьте такие опции: '211 Загрузки' (без кавычек). Используйте по одному заголовку на строчку.

Замечание: Если вы хотите изменить заголовок для всех статей вы можете отредактировать вхождения 'ATTACHMENTS TITLE' в файлах перевода:
```
    administrator/language/qq-QQ/qq-QQ.plg_frontend_attachments.ini
```
где qq-QQ является инфобозначением кода языка, например en-GB для английского или ru-RU для русского языка. (Если вы не знакомы с файлами перевода Joomla!, то просто найдите строку, содержащую 'ATTACHMENTS TITLE' в левой своей части перед знаком '=' Напишите то что вы считаете нужным для отображения в правой части после знака '=' и ничего не меняйте в левой.)
Скрывать вложения для: Разделеный запятой список ключевых слов или Разделов/Категорий тех статей для которых список вложений будет не виден. Могут применяться два ключевых слова: 'frontpage' чтобы спрятать вложения на главной странице и 'all_but_article_views' чтобы разрешить видеть вложения только при просмотре статьи. (ключевое слово вводится без кавычек.) Идентификаторы Разделов/Категорий должны вводится как соответствующие числа разделенные знаком '/': Раздел#/Категория#, Раздел#/Категория#. Чтобы указать все категрии внутри одного раздела пишите внутри одной Категории только номер раздела. Примеры: 23/10, 23/11, 24
Безопасная загрузка прикрепленных файлов По умолчанию расширение 'Вложения' сохраняет загружаемые файлы в общедоступный каталог. Если вы укажите значение этой опции Да, то каталог в который загружаются файлы перестанет быть общедоступным. Ссылки на прикрепленные файлы будут работать, но они перестанут быть прямыми. Это позволит исключить доступ пользователей без определенных прав. Есди выбрано значение 'нет', то файлы будут доступны по полному URL адресу всем. Таким образом эта опция предотвращает доступ к файлам посторонних лиц, даже если они знают полный URL адрес файла.
Режим скачивания для безопасных загрузок: Эта опция определяет должны ли прикрепленные файлы при скачивании открываться как отдельные файлы или же браузер должен пытаться сам отобразить их внутри страницы. (если он может обрабатывать такой тип файлов). Существует два варианта:
- 'inline': в этом режиме, файлы которые могут быть отображены браузером будут им отображаться (так же как текст или кратинки).
- 'вложением': в этом режиме файлы всегда будут скачиваться на сторону клиента как отдельные файлы.
В любом случае файлы которые не могут быть отображены в браузере будут скачиваться как внешние файлы.

[Наверх]

Отображать имя файла как

Обычно, когда файлы скачены и отображаются в спсике вложений, полное имя файла используется как ссылка для скачивания. В некоторых случаях имена файлов могут быть слишком длинными. В форме загрузки прикрепляемого файла есть специальное поле 'Отображать имя файла как' в котором человек прикрепляющий файл может указать имя отличное от системного имени файла. Например здесь может быть указана аббревиатура имени файла. Это поле может быть также изменено через административную панель.
Замечание: Серди опций плагина есть "Максимальная длина файла". Она может автоматически образать имя файла и записывать его в поле "отображать имя файла как" [Наверх]

CSS стили списка вложений

Список вложений строиться при помощи специального тега 'div', который содержит таблицы вложений. Таблица имеет несколько разных CSS классов, связанных с ней, чтобы дать разработчику сайта возможность изменить внешний вид таблицы. Посмотрите CSS файл в плагине вложения (plugins/content/attachments.css) для примера. Если вы хотите сменить стиль, скопируйте оригинальные стили в конец файла и переименуйте 'attachmentsList' во что-нибудь другое, например 'originalList'. Откройте параметры компонента 'Вложения' (Компоненты => Вложения) и измените параметр CSS стиля на своё новое название класса. Далeе соответсвтующим образом измените определения класса в той секции файла стилей где у вас осталось название 'attachmentsList'. Такой подход позволит вам легко вернуться к первоначальному стилю, просто изменив параметр CSS стиля на сохраненное значение 'originalList'. Кроме того секция с изменненым стилем может быть легко скопирована в отдельный файл и затем легко добавлена заново, когда вы перейдете на новую версию расширения. Это можно сделать командой CSS @import [Наверх]

Иконки типов файлов

Расширение 'Вложения' (The 'Attachments') отображает иконку перед каждым вложением в списке вложений. Если вы хотите добавить новый тип иконки следуйте указаным шагам:

Добавьте соответствующую иконку в каталог 'media/attachments/icons', если её там нет.
Отредактируйте файл 'components/com_attachments/file_types.php' и добавьте соответствующую строку в статический массив $attachments_icon_from_file_extension, который связывает расширение файла с именем файла иконки (в каталоге media/attachments/icons ). Если это не сработало - значит вам еще нужно добавить соответствующую строку в массив $attachments_icon_from_mime_type.
Не забудьте сохранить ваши файлы иконок и измененный файл file_types.php, перед тем как обновлять версию расширения.

[Наверх]

Предупреждения

Если у вас есть вложения личного характера, то используйте опцию 'Безопасная загрузка прикрепленных файлов'
Если вы её не используете, то файлы вложений сохраняются в общедоступном каталоге и доступны для всех. Опция безопасной загрузки предотвращает доступ без определенных прав. Смотрите обсуждение этой опции для большего понимания.
Каждый раз когда файл загружается на сервер, проверяется существование каталога и если он отсутствует, то будет создан. По умолчанию кталог для загрузки это 'attachments' в корневом каталоге вашего веб сайта. Это имя можно изменить через опцию 'каталог для загружаемых файлов'. Если расширению не удается создать этот каталог вы должны сделать его сами, иначе могут возникнуть проблемы с загрузкой файлов. Убедитесь что вы указали необходимые права. В мире Unix/Linux это скорее всего 775. Внимание, процесс создания каталога для загрузки может не удасться, если настройки вашего сервера (или PHP) запрещают создавать подкаталоги. Возможно вам прийдется времено убрать эти ограничения.
Если вам не удается загружать файлы определенного типа (например zip архивы), помните что раширение использует ограничения накладываемое медиа менеджером. Это сделано, чтобы не загрузить потенциально опасные файлы такие как *.php или *.html. Администратор может изменить настройки медиа менеджера, чтобы добавить требуемый тип файлов.
Второй плагин, 'add_attachment_btn_plugin' (так называемая 'Кнопка - Прикрепить' в управлении плагином) позволяет прикреплять файлы к статье во время её редактирования. Этот плагин добавляет кнопку "Прикрепить файл" прямо под областью редактирования статьи. Если вы установили этот плагин, но не видите кнопки, скорее всего вам необходимо включить этот плагин в менеджере плагинов.
Замечание: Несмотря на то что кнопка прикрепить файл отображается всегда, если статья не была ни разу сохранена, то прикрепить файл не возможно.
Если вы не видите вложений, этому может быть несколько причин:
- Плагин 'Content - Attachments' не включен. Воспользуйтесь менеджером плагинов, чтобы его включить.
- Опция 'Кому разрешено видеть вложения' установлена в 'любой зарегистрированный пользователь' а вы не зарегистрировались.
  Это может быть изменено через настройки параметров в менеджере компонентов
- В плагине 'Content - Attachments' (через менеджер плагинов), параметр доступ не установлен в значение 'всем'.
Если вы столкнулись с ограничением на размер загружаемого файла попробуйте добавить следующие строчки в файл .htaccess в корне вашего сайта:
```
  php_value upload_max_filesize 32M
  php_value post_max_size 32M
```
где значение 32M (мегабайта) вы можете заменить на любое какое захотите в качестве ограничения максимального размера загружаемых файлов.
Существует форум помощи и форум Часто Задаваемых Вопросов на сайте Joomlacode, Если вы обнаружили проблему, не раскрытую на данной странице, пожалуйста проконсультируйтеся на форумах:
- Форум вложений на Joomlacode.org

[Наверх]

Обновление

Если у вас есть прикрепленные файлы, которые вы хотите сохранить после проведение процедуры обновления воспользуйтеся следующим алгоритмом:

[Этот шаг не обязателен, но лучше его выполнить, чтобы точно иметь копию базы данных вложений, в случае если что-то пойдет не так.]
Воспользуйтесь phpMyAdmin (или другим инструментом редакторивония SQL) чтобы сохранить содержимое таблицы jos_attachments (Воспользуйтесь опцией 'Экспорт' ['Export'] с 'Полными' ['Complete'] вставками данных, (не 'Расширенными' ['Extended'] вставками)
Вам также нужно сохранить загруженные файлы (обычно в каталоге 'attachments' )
Войдите в управление вложениями через административную панель (Компоненты => Вложения) и щелкните на кнопке 'Админ' справа в конце на панеле. Щелкните на команде 'Отключить деинсталяцию таблицы вложений MySQL'. Это отключает удаление таблицы вложений во время деинсталяции компонента "вложения".
Деинсталируйте компонент 'Вложения' ('Attachments').
Деинсталируйте все плагины расширения 'Вложения' ('Attachments').
Теперь установите новый вупуск расширения, распаковав дистрибутивные файлы и установив все новые плагины, а затем компонент. Во время установки компонента, таблица вложений будет автоматически обновлена.
Включите все плагины расширения 'Вложения' ('Attachments')
Ваши вложения должны быть снова доступны. Войдите в управление вложениями через административную панель (Компоненты => Вложения) и убедитесь что всё в порядке..

Помните что деинсталяция расширения 'Attachments' не удаляет ранее загруженные файлы, но она удаляет таблицу вложений в базе данных. Поэтому после переустановки расширения, чтобы восстановить все старые вложения, необходимо лишь восстановить таблицу.

Если вы решили не восстанавливать базу вложений, не забудьте удалить любые устаревшие файлы в подкаталоге attachments, чтобы не появилось конфиликта имен файлов. [Наверх]

Благодарности

Большое спасибо людям и ресурсам внесшим больщой вклад в проект:

Книга Джозефа Л. ЛеБланк Изучение разработки расширений Joomla! 1.5: Создание Модулей, Компонент, и Плагинов на PHP
[ Learning Joomla! 1.5 Extension Development: Creating Modules, Components, and Plugins with PHP by Joseph L. LeBlanc ]
была очень полезна при написании расширения 'Вложения' ('Attachments').
Болшое спасибо Paul McDermott за щедрую помощь в плагине поиска! Это очень полезное дополнение!
Иконки для типов файлов были получены из нескольких источников, включая:
Замечание: большинство иконок 'Вложения' ['Attachments'] отличаются от аналогичных на этих сайтах. Если вы хотите получить оригинальные версии, пожалуйста загрузите их с этих веб сайтов.

[Наверх]

Пожалуйста сообщайте об ошибках и предложениях по адресу jmcameron@jmcameron.net.