ddTools

Library
  • Версия: 0.10
  • Выпущено:
  • Метки: General
Скачать108 скачиваний

Описание

Библиотека с различными небольшими инструментами, облегчающими работу. Умеет:

  • Создавать новый документ;
  • Обновлять информацию о существующем документе;
  • Получать необходимые дочерние документы (с TV и пр.);
  • Парсить текст (почти как modx->parseChunk, только принимает текст, а не имя чанка);
  • Парсить ресурс (вызывается $modx->parseDocumentSource и $modx->rewriteUrls);
  • Разбивать строку в ассоциативный массив по двум разделителям;
  • Разбивать ассоциативный массив полей и TV документа на два отдельных массива;
  • Удалять необходимую папку со всеми вложенными папками и файлами;
  • Регистрировать необходимые JavaScript во внутреннем массиве $modx без подключения кода (полезно при ручном подключении скриптов);
  • Генерировать случайную строку нужной длины;
  • И ещё несколько мелочей (см. код).

Список изменений

  • Массив «ddTools::$tables» с элементами для наглядности объявляется непосредственно в классе.
  • Поле «alias_visible» добавляется в массив «ddTools::$documentFields» только если версия MODX > 1.0.11 для совместимости с более ранними версиями.
  • Добавлен метод «ddTools::unfoldArray». Преобразует многомерный массив в одномерный, при этом ключи результирующего массива сливаются через '.' (см. описание и примеры).

Документация

Для установки распакуйте архив в корень сайта (файл modx.ddtools.class.php должен находиться в папке assets/snippets/ddTools/). Вообще говоря, библиотека очень проста, так что, если что, посмотрите в исходный код и вы всё поймёте.

Все методы и поля являются публичными, статичными и объявляются в классе «ddTools».

Описание параметров

Название Описание Допустимые значения Значение по умолчанию

Поле «documentFields»

Содержит массив имён полей документа.

Поле «tables»

Содержит полные имена некоторых таблиц БД (см. код).

Метод «screening»

Экранирует символы в строке (см. код).
str* Строка для обработки. {string}

Метод «explodeAssoc»

Разбивает строку по двум разделителям в ассоциативный массив.
str* Строка для обработки. {separated string}
splY Разделитель между значениями (между парами ключ-значение). {string} '||'
splX Разделитель между ключом и значением. {string} '::'

Метод «unfoldArray»

Преобразует многомерный массив в одномерный, при этом ключи результирующего массива сливаются через '.'. Может быть полезно при необходимости использования «вложенных плэйсхолдеров» ([+size.width+]). См. примеры ниже.
arr* Массив для обработки. {array}
keyPrefix Префикс ключей объекта (внутренняя переменная, но можно и поюзать при необходимости). {string} ''

Метод «parseText»

Аналог модексовского parseChunk, только принимает текст (+ пара плюшек).
chunk* Строка, которую нужно парсить. {string}
chunkArr* Массив значений. Ключ — имя плэйсхолдера, значение — значение. {array: associative}
prefix Префикс плэйсхолдеров. {string} '[+'
suffix Суффикс плэйсхолдеров. {string} '+]'
mergeAll Надо ли делать дополнительно обрабатывать поля документа, настроек, чанков. {boolean} true

Метод «parseSource»

Парсит ресурс (вызывается $modx->parseDocumentSource и $modx->rewriteUrls).
source* Текст для парсинга. {string}

Метод «explodeFieldsArr»

Разбивает ассоциативный массив полей и TV документа на два отдельных массива.
fields* Ассоциативный массив значений полей документа (в таблице `site_content`) и/или TV. {array: associative}

Метод «createDocument»

Создаёт новый документ.
fields* Массив полей или TV документа. Ключ — название поля или TV, значение — значение. Обязательно должен присутствовать заголовок нового документа (элемент 'pagetitle'). {array: associative}
groups Индексированный массив id групп, к которым должен принадлежать документ. {array}

Метод «updateDocument»

Обновляет информацию по документу.
id* ID документа (или массив ID), который необходимо отредактировать. {integer; array} 0
update* Массив значений полей или TV документа. Ключ — название поля или TV, значение — значение. {array: associative}
where SQL условие WHERE. {string: sql}

Метод «getDocuments»

Получает необходимые документы (поля документов).

Отличие от родного метода:
  • Параметр published может принимать false, в этом случае будут получены и опубликованные и неопубликованные документы.
  • Параметр deleted может принимать false, в этом случае будут получены и удалённые и неудалённые документы.
ids* Id документов, которые надо получить. {array}
published Опубликованы ли документы, которые надо получить. При значении === false — без разницы. {false; 0; 1} false
deleted Удалены ли документы, которые надо получить. При значении === false — без разницы. {false; 0; 1} 0
fields Поля документа, которые надо получить. {comma separated string; '*'} '*'
where Условие WHERE SQL-запроса для получения документов. {string}
sort Поле документа, по которому необходимо сортировать результаты. {string} 'menuindex'
dir Направление сортировки результатов. {'ASC'; 'DESC'} 'ASC'
limit SQL LIMIT (слово LIMIT включать не надо). {string}

Метод «getDocument»

Получает данные о необходимом документе (поля документа).

Отличие от родного метода:
  • Параметр published может принимать false, в этом случае без разницы, опубликован ли документ, он всё равно будет получен.
  • Параметр deleted может принимать false, в этом случае без разницы, удалён ли документ, он всё равно будет получен.
id* Id документа, данные которого надо получить. {integer}
fields Поля документа, которые надо получить. {comma separated string; '*'} '*'
published Опубликован ли документ, данные которого надо получить. При значении === false — без разницы. {false; 0; 1} false
deleted Удален ли документ, данные которого надо получить. При значении === false — без разницы. {false; 0; 1} 0

Метод «getTemplateVars»

Получает массив TV и полей заданного документа.

Отличие от родного метода:
  • Параметр published может принимать false, в этом случае будут получены и опубликованные и неопубликованные документы.
idnames* Id или имена TV, или имена полей документа, которые надо получить. {array; '*'}
fields Поля базы данных таблицы TV, которые надо получать. {comma separated string; '*'} '*'
docid Id документа, данные которого надо получить. {integer; ''} Текущий документ
published Опубликован ли документ, данные которого надо получить. При значении === false — без разницы. {false; 0; 1} false
sort Поля базы данных таблицы TV, по которым необходимо сортировать результаты. {comma separated string} 'rank'
dir Направление сортировки результатов. {'ASC'; 'DESC'} 'ASC'

Метод «getTemplateVarOutput»

Получает ассоциативный массив значений TV и полей заданного документа.

Отличие от родного метода:
  • Параметр published может принимать false, в этом случае будут получены и опубликованные и неопубликованные документы.
idnames* Id или имена TV или имена полей документа, которые надо получить. {array; '*'}
docid Id документа, данные которого получить. {integer; ''} Текущий документ
published Опубликован ли документ, данные которого надо получить. При значении === false — без разницы. {false; 0; 1} false
sep Разделитель, используемый при склейке в getTVDisplayFormat(). {string} ''

Метод «getDocumentChildren»

Получает необходимые дочерние документы (значения их полей).

Отличие от родного метода:
  • Параметр published может принимать false, в этом случае будут получены и опубликованные и неопубликованные документы.
  • Параметр deleted может принимать false, в этом случае будут получены и удалённые и неудалённые документы.
parentid Id родителя, дочерние документы которого необходимо получить. {integer} 0
published Опубликованы ли документы, которые надо получить. При значении === false — без разницы. {false; 0; 1} 1
deleted Удалены ли документы, которые надо получить. При значении === false — без разницы. {false; 0; 1} 0
fields Поля документа, которые надо получить. При значении == '*' — все поля. {comma separated string} '*'
where Условие WHERE SQL-запроса для получения документов (в условии могут участвовать только поля документа). {string}
sortBy По какому полю сортировать документы. Для множественной сортировки можно передавать несколько с указанием направления через запятую (как в sql), в этом случае «sortDir» следует передать как пустую строку. {string; comma separated string} 'menuindex'
sortDir Направление сортировки документов. {'ASC'; 'DESC'; ''} 'ASC'
limit SQL LIMIT (слово LIMIT включать не надо). {string}

Метод «getDocumentChildrenTVarOutput»

Получает необходимые дочерние документы (значения их полей и TV).

Отличие от родного метода:
  • Добавлен параметр $where, который позволяет указать условие WHERE SQL-запроса для получения документов (в условии могут участвовать только поля документа).
  • Добавлен параметр $resultKey, который позволяет определить, значение какого поля будет ключами результирующего массива.
  • В $modx->getDocumentChildren получается только id (ибо зачем всё остальное, дальше ведь всё равно получается).
  • Параметр $published может принимать false, в этом случае будут получены и опубликованные и неопубликованные документы.
parentid Id родителя, дочерние документы которого необходимо получить. {integer} 0
fields Массив названий полей документа и/или TV, которые нужно получить. {array} array($resultKey)
published Опубликованны ли документы? {false; 0; 1} 1
sortBy По какому полю сортировать документы. Для множественной сортировки можно передавать несколько с указанием направления через запятую (как в sql), в этом случае «sortDir» следует передать как пустую строку. {string; comma separated string} 'menuindex'
sortDir Направление сортировки документов. {'ASC'; 'DESC'; ''} 'ASC'
where Условие WHERE SQL-запроса для получения документов (в условии могут участвовать только поля документа). {string}
resultKey Значение какого поля должно быть ключами результирующего массива? Если передать false, то ключи будут просто по порядку. {string; boolean} 'id'

Метод «parseFileNameVersion»

Разбирает строку файла, получая из неё его имя версию.
file* Строка пути к файлу или распаршенный при помощи pathinfo() путь к файлу. {string; array}

Метод «regEmptyClientScript»

Добавляет необходимый файл JavaScript в нужный внутренний список MODx в соответствии с его именем и версией. Предназначен для регистрации скриптов, которые уже были подключены в ручную.

Внимание! Метод не добавляет код скрипта, только регистрирует его имя и версию, чтобы дальнейшие вызовы $modx->regClientScript или $modx->regClientStartupScript не приводили к повторному подключению того, что уже было подключено руками. Более того, если скрипт был ранее подключен при помощи $modx->regClientScript или $modx->regClientStartupScript, его код будет очищен, т.к. предполагается, что вы его подключили в ручную.

Параметры передаются в виде ассоциативного массива, где:
name* Имя скрипта. {string}
version Версия скрипта. {string} '0'
startup Подключён ли скрипт в ? {boolean} false

Метод «getDocumentIdByUrl»

Получает id документа по его адресу.
url* Адрес. {string}

Метод «removeDir»

Удаляет папку со всеми вложенными файлами и папками (рекурсивно)
dir* Адрес папки, которую необходимо удалить {string}

Метод «generateRandomString»

Генерирует случайную строку нужной длины.
length Размер строки на выходе. {integer} 8
chars Набор символов для генерации. {string} 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456789'

Примеры

Разбивка строки в ассоциативный массив по двум разделителям

ddTools::explodeAssoc('pagetitle::Test pagetitle||menuindex::2||published::0');

Вернёт:

Array(
	'pagetitle' => 'Test pagetitle',
	'menuindex' => '2',
	'published' => '0'
);

Развёртка ассоциативного массива

$someArray = array(
	'a': '',
	'b': array(
		'b1': '',
		'b2': array(
			'b21': '',
			'b22': ''
		)
	),
	'c': ''
);

$someArray = ddTools::unfoldArray($someArray);

Вернёт:

array(
	'a': '',
	'b.b1': '',
	'b.b2.b21': '',
	'b.b2.b22': '',
	'c': ''
)

Разделение ассоциативного массива, содержащего значения полей документа и TV на два разных

ddTools::explodeFieldsArr(array(
	'pagetitle' => 'Test',
	'some_image' => 'assets/images/some_image.png',
	'another_tv' => 'Test tv'
	'longtitle' => 'Long test',
));

Вернёт:

Array(
	Array(
		'pagetitle' => 'Test',
		'longtitle' => 'Long test'
	),
	Array(
		'some_image' => Array(
			'val' => 'assets/images/some_image.png',
			'id' => 123
		),
		'another_tv' => Array(
			'val' => 'Test tv',
			'id' => 321
		)
	)
);

Парсинг произовльного текста (замена плэйсхолдеров на значения)

ddTools::parseText('<div>[+test1+], [+test2+]</div>', array('test1' => 'Hello', 'test2' => 'world'));

Создание опубликованного документа с шаблоном 36 в корне сайта (+ запомним id созданного документа)

$id = ddTools::createDocument(array('pagetitle' => 'Test document', 'template' => 36, 'published' => 1));

Обновление заголовка документа и заголовка меню у документа

ddTools::udateDocument($id, array('pagetitle' => 'Tested document', 'menutitle' => 'Omg'));

Получение необходимых дочерних документов с фильтрацией по шаблону

ddTools::getDocumentChildrenTVarOutput(15, array('pagetitle', 'someTv'), 1, 'menuindex', 'ASC', 'sc.template = 5');

Получение индексированного массива необходимых дочерних документов с сортировкой по дате публикации в обратном порядке и заголовку

ddTools::getDocumentChildrenTVarOutput(15, array('pagetitle', 'someTv', 'content'), 1, 'pub_date DESC, pagetitle ASC', '', '', false);