Работа с ресурсами. Управление картинками, документами на сайте

Управление ресурсами

Ресурс - это фото или документ, прикрепленный к некой сущности (по entityCode и itemID).
Компонент дает возможность вывести галерею ресурсов (фото или документы), возможность редактировать их и возможность загрузить новые ресурсы. 
Ресурсы крепятся к некоторым сущностям (entityCode). 

Вывод и функции зависят от 2 режимов: 
isSingle  - определяет будет ли привязываться 1 ресурс для данной сущности (например аватар человека) или целая коллекция ресурсов.
read/write - может ли пользователь управлять коллекцией ресурсов (загружать, редактировать, удалять) или нет.

Как работать с ресурсами

1.Добавляем на страницу сниппет компонента:

<div class="as-resourceManager" data-code="{typeCode}" data-itemid="falcon-space--rabota-s-resursami"></div>

2.Создаем и настраиваем тип ресурса:

   Код - код типа ресурса (используется в сниппете)

   Код объекта - код некоего объекта в системе (не привязан жестко к какой-то таблице).
   Не путайте код сущности (Товар) и код Типа ресурса (настройка как будет работать компонент).
   К одной сущности может быть в итоге привязано несколько типов ресурсов. 

   Роли на чтение - кто может просматривать картинки.

   Роли за загрузку и редактирование - Кто может загружать и редактировать записи. 

   Галка Одиночная картинка - если Да, то работаем только с 1 ресурсом для сущности.

   Галка Показывать настройки загрузки - отображать при Upload дополнительные опции загрузки (для картинок).

   Возможность загрузки - если Да, то можно будет загружать файлы (для ролей на загрузку).

   Показать сразу в полный размер - если Да, то в менеджер грузятся сразу полноразмерные картинки а не thumb.

   Загружать без трансформации (LoadWithoutTransform). Если да - то картинки не меняют размеров при загрузке.  Также эта настройка влияет на обработку имен файлов. Если она стоит Да, то имя файла никак не обрабатывается (через dbo.str_processURL для исключения различных спецзнаков и транслитерации).

   Показать галерею - если да, то можно будет просматривать список ресурсов.

   Максимальный размер файла в МБ - насколько большой файл можно загружать. Внимание! Есть системное ограничение на файлы в 12Мб.

   Фильтр для файлов - регулярное выражение на фильтрацию файлов (Regex). 

   Высота и ширина картинки - задает прямоугольник, в который должно быть вписано изображение.

   Высота и ширина миниатюры - задает прямоугольник, в который должно быть вписано thumb изображения.

   Отношение для обрезки - соотношение сторон для ручного обрезания фото.

   Картинка по умолчанию - путь к фото, которое будет показываться когда нет элементов для отображения в менеджере. 

   Водяной знак - URL путь к картинке водяного знака (будет ставить посередине каждого изображения при Upload).
   Внимание! Не влияет при установке на уже ранее загруженные изображения. 

   Качество сохранения картинок - качество сохранения картинки от 10 до 100. 

   Добавлять поля к картинке (и миниатюре) при загрузке - при несовпадении пропорций и размеров картинка будет дополняться белыми полями. 

   Путь сохранения - указывается некий путь в /uploads к файлу или папке. Если папка, то в нее будет сохраняться файл со своим именем.
   Если файл - то имя файла будет жестко определено этим параметром. Например: если указали /docs, то сохранение файлов будет идти в /uploads/docs/

Дополнительные параметры сниппета ресурсов (as-resourceManager):

• data-title="Товар 1" - задаем внешнюю подпись у картинки. Если не указано, то используется подпись, связанная с ресурсом (по умолчанию это имя файла).
  Это поле также используется в заголовке диалогового окна (при показе полноэкранной картинки). 
• data-hideTitle="1"  - скрываем подпись у картинки (находится под картинкой).
• data-hideLinks = "1" - скрываем ссылки в режиме редактирования.
• data-link="/product/1" - если задана ссылка, то при клике на картинку идет переход по данной ссылке. Если нет ссылки - то показ полной картинки в диалоговом окне. 
• data-carouselEnabled="1" - если указано 1, то при нажатии на картинку будет показываться слайдер из картинок в диалоговом окне. 
• data-bigFirst="1" - если 1, то первая картинка в показе будет большой, а все остальные маленькие (например, для использования на странице товара).
• data-compact="1" - если 1, то галерея картинок (или документов) будет показана в уменьшенном виде.
• data-ultracompact="1" - если 1, то галерея картинок (или документов) будет показана в очень уменьшенном виде. Обычно используется для вывода в таблицах.
• data-emptyText="Нет фото" - Если нет элементов, то будет показана эта надпись. Если пробел - то не выводится сообщение, что нет элементов.
• data-uploadTitle - задает заголовок окна загрузки файлов.
• data-hideEmpty - если равно 1 и совсем нет элементов, то всему компоненту ставится класс hide.
• data-progressStyle - стилизация полоски прогресса - заменяет стилизацию в элементе .progress-bar. Пример: progress-bar-striped bg-success. https://getbootstrap.com/docs/4.0/components/progress/
• data-immediateSelectFile="" - если 1, то при нажатии на кнопку Загрузить появляется модальное окно и автоматически нажимается кнопка Выбор файлов.
• data-downloadArchive="1" - если 1, то будет кнопка скачивания всех файлов через упаковку в zip (обновление сентябрь 22). Аналогичная настройка есть у as-files.

Специальные настройки в /settings

• "resource.blockExtensions", по умолчанию - ".js,.html,.htm,.asp,.php,.aspx" - файлы с какими разрешениями нельзя пропускать (иначе возникает риск атаки XSS - злоумышленник загружает файл со скриптами, а пользователь открывает его)
• "resource.maxFilenameLength", по умолчанию "160", максимальная длина названия файла (у операционной системы сервера может быть ограничение на длину пути к файлу). 
• "resource.disableProcessName", по умолчанию "0" - если 1, то имя файла не будет обрабатываться через dbo.[str_processURL] (по умолчанию имена файлов обрабатываются, чтобы в URL к файлу не было спецсимволов). 

Дополнительные действия после выполнения операции с ресурсами

Вы можете выполнить некоторые действия после загрузки (upload), удаления (delete) или обновления полей ресурса (edit). 
Для этого необходимо реализовать процедуры rs_{entityCode}_{action}_callback (редактировать их можно будет в управлении типами ресурсов). 
action - upload, delete, edit.
на вход принимает: typeCode(тип ресурса), itemID, resourceID (если загрузка нескольких файлов - то первый файл), username.
на выходе: ResultModel(Result, Msg). 
Примечание

1. Файлы хранятся в папке /uploads/rs/{entiyCode}/{itemID}
2. Не путайте entityCode (код сущности, например product) и typeCode (настройки вывода компонента, например manageProdyctImages)
3. Если необходимо проверить права доступа дополнительно (на основе itemID), то необходимо создать хранимую процедуру с именем rs_{entityCode}_hasAccess.
   На входе typeCode, username, itemID, right (read or write). На выходе - модель ResultModel (поля Result bit, Msg nvarchar(256)). Управление процедурой есть на странице управления компонентом.
4. Для не картинок используются типовые иконки типов - pdf, excel, word, text и other. 
5. Вы можете установить по умолчанию картинку для варианта, когда не загружено ресурсов.
   Для этого прописываем путь к картинке в параметре defaultImagePath для ResourceType.
6. Вы можете обрезать картинки. Установите в пикселях для типов ресурсов Width и Height. Картинка в итоге впишется в этот прямоугольник по размерам и сохранится в jpg. 
7. Для картинок также сохраняется thumbUrl. Его размеры управляются через тип ресурса - thumbWidth, thumbHeight.
   Для других типов в роли превью выступает значок типа файла. 
8. Для получения URL картинки в SQL можно использовать функцию [dbo].[rs_resourceLink] (entityCode, itemID, isThumb)

SELECT [dbo].[rs_resourceLink] ('product', 1014, 0)

Файловый менеджер

В системе есть файловый менеджер (/fileManager), который позволяет осуществлять навигацию по папкам, загружать файлы, редактировать текстовые файлы. 

<div class="as-fm" data-code="{code}"></div>

HowTo по ресурсам и картинкам 

Не отображается картинка юзера справа вверху
Проверьте, что у вас установлены 2 процедуры: 

• rs_userPhoto_getFile
• rs_defaultUserPhoto_getFile

<div class="as-resourceManager" data-text="Нет фото"></div>

Как вывести некую картинку или документ через хранимую процедуру (тело картинки, а не просто путь)? 

Для этого используем подгружаемые файлы.

Обработка спецсимволов в названии файлов 

CREATE OR ALTER function [dbo].[str_processURL] (@string nvarchar(max))
returns nvarchar(max) as
begin
declare @res nvarchar(max) = lower(dbo.str_cyrillic2Latin(@string))
set @res = replace(@res, '_','-')
set @res = replace(@res, ' ','-')
set @res = replace(@res, '?','-')
set @res = replace(@res, '%','-')
set @res = replace(@res, '&','-')
set @res = replace(@res, '	','-')
set @res = replace(@res, '=','-')
set @res = replace(@res, ',','-')
set @res = replace(@res, '.','-')
set @res = replace(@res, '@','-')
set @res = replace(@res, '#','-')
set @res = replace(@res, '
,'-')
set @res = replace(@res, '*','-')
set @res = replace(@res, '(','-')
set @res = replace(@res, ')','-')
set @res = replace(@res, '/','-') -- возможно не везде надо будет.
set @res = replace(@res, '+','-')
set @res = replace(@res, ':','-')
set @res = replace(@res, '!','-')
set @res = replace(@res, '~','-')

declare @ind int = 1

while @ind <= 10 begin
	set @ind = @ind + 1
	if(right(@res,1)='-') begin
		set @res = left(@res,len(@res)-1)
	end
	if(left(@res,1)='-') begin
		set @res = right(@res,len(@res)-1)
	end

end

return @res
end

<div class="as-files" data-code="productImages" data-itemid="5" data-disabledeleteconfirm="1" data-successmsg=" "></div>

Кастом разметка компонента as files

<div class="as-files">
	<script type="text/html" class="as-files-makeup hide"></script>
	<script type="text/html" class="as-files-itemMakeup hide"></script>
</div>

as.filescallbacks["code1_getItems"] = function(data, params){}
as.filescallbacks["code1_uploadComplete"] = function(data, evt){}
as.filescallbacks["code1_delete"] = function(data, params){}

IF COL_LENGTH( 'as_rs_resources' , 'size' ) IS NULL
BEGIN
      ALTER TABLE as_rs_resources
      ADD size int NULL
END

ALTER PROCEDURE [dbo].[as_resources_addResource] 
@itemID nvarchar(128),
@typeCode nvarchar(128),
@url nvarchar(512),
@thumbUrl nvarchar(512),
@title nvarchar(128),
@size int,
@username nvarchar(128)
AS
BEGIN

insert into as_rs_resources (url, thumbUrl, itemID, title, entityCode, ord, size) 
values(@url, @thumbUrl, @itemID, @title, 
	(select top 1 entityCode from as_rs_types where lower(code) = lower(@typeCode)),
	(select max(id)+1 from as_rs_resources),
	@size
)

select  Scope_identity() id

END

as.resourceManagercallbacks["{code}_afterCrop"] = function(data,params){
   console.log("xxxx222");
   // as.sys.closeDialog();
   // as.initControls($('.div1'))
}