ddTools

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

Описание

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

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

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

  • Меод «ddTools::createDocument» был обновлён: теперь адрес нового документа собирается правильно, в зависимости от path родителя и его alias'а, либо id, если alias'а нет.

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

Для установки распакуйте архив в корень сайта (файл 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} ''

Метод «sort2dArray»

Сортирует двумерный массив по нескольким колонкам (как в SQL) по методу Хоара. Сортировка устойчивая.
$array * Исходный массив. {array}
$sortBy * Колонки, по которым нужно сортировать (ключи массивов второго уровня) в необходимом порядке. {array}
$sortDir Направление сортировки (1 == ASC; -1 == DESC). {1; -1} 1
$i Счётчик (внутренняя переменная для рекурсии). {integer} 0

Метод «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}

Метод «verifyRenamedParams»

Проверяет наличие устаревших названий параметров и записывает предупреждение в журнал событий MODX. Возвращает ассоциативный массив, где ключ — правильное имя параметра, а значение — значение. Используйте функцию «extract», чтобы извлечь результат в переменные.
$params * Ассоциативный массив параметров, где ключ — имя параметра, значение — значение. В коде любого сниппета можете просто использовать переменную «$params». {array: associative}
$compliance * Массив соответствия старых имён параметров новым, где ключ — новое имя, значение — старое. {array: associative}

Метод «sendMail»

Отправляет e-mail.
$to * Addresses to mail. {array}
$text * E-mail text. {string}
$from Mailer address. {string} 'info@divandesign.biz'
$subject E-mail subject. {string} 'Mail from '.$modx->config['site_url']
$fileInputName “input” tags names from which accepted files are taken. {array}

Метод «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': ''
)

Сортировка двумерного массива по нескольким колонкам

Пусть у нас есть табличка фруктов:

Ключи 'name' 'count'
0 'Груши' 3
1 'Мандарины' 2
2 'Бананы' 3
3 'Яблоки' 1

В виде массива она будет выглядеть так:

$fruits = array(
	0 => array('name' => 'Груши', 'count' => 3),
	1 => array('name' => 'Мандарины', 'count' => 2),
	2 => array('name' => 'Бананы', 'count' => 3),
	3 => array('name' => 'Яблоки', 'count' => 1)
);

Отсортируем по количеству, затем по названию:

$fruits = ddTools::sort2dArray($fruits, array('count', 'name'));

Вернёт:

array(
	0 => array('name' => 'Яблоки', 'count' => 1)
	1 => array('name' => 'Мандарины', 'count' => 2),
	3 => array('name' => 'Бананы', 'count' => 3),
	4 => array('name' => 'Груши', 'count' => 3),
);

У бананов и груш одинаковое количество, так что между собой они отсортированы по названию.

Разделение ассоциативного массива, содержащего значения полей документа и 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);