TypoScript синтаксис

Avatar of admin admin - 20.08.2017 04:59 - CMS, TYPO3, Настройка, TypoScript

TypoScript синтаксис

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

[Путь к объекту] [Оператор] [Значение]

Например:

myObject.myProperty = 2

Путь к объекту

Путь к объекту (в нашем примере myObject.myProperty) похож на имя переменной в языке программирования. Это первый блок символов в строке, не содержащий пробелов, до одного из символов =<>{( или пробела при наличии. Точка (.) используется как разделитель объектов и свойств друг от друга, образуя иерархию. В примере у нас обозначен объект myObject со свойством myProperty. Для пути к объекту допустимо использовать только символы из набора A-Z,a-z,0-9,"-","_" и точку (.). (Ну то есть никаких русских букаф - прим. перев.)
Точки, используемые как часть имени, должны быть экранированы обратным слэшем (\).

Например:

my\.escaped\.key = test

В результате мы имеем объект my.escaped.key со значением test. В данном случае это не три составные части my, escaped и key, а единый объект. (Лучше такой вариант не применять, во избежание путаницы - прим. перев.)

Оператор

Оператор (в нашем случае =) может быть одним из символов =<>{( Различные операторы описаны ниже.

Значение

Значение (в нашем примере 2), это символы, следующие за оператором до конца строки, все пробелы до и после будут игнорированы. Обратите внимание, что значения не заключены в кавычки! Значение начинается после оператора и заканчивается концом строки.

Комментарии

Строки, начинающиеся с / или # считаются комментарием и не обрабатываются.

Пример:

// This is a comment
/ This also is a comment (only ONE slash is needed)
myObject = TEXT
myObject.value = <strong>Some HTML code</strong>
# This line also is a comment.


Многострочные комментарии

Строки, начинающиеся с /* и */ определяют начало и конец комментария соответственно. Все внутри такой секции игнорируется.

Правила:

  • /* и */ должны быть самыми первыми символами в строке (пробелы в начале не допускаются).
  • Многострочные комментарии не допускаются внутри многострочных блоков значений (см. описание оператора "(" ниже).

Пример:

/* Это комментарий
 .. и эта строка тоже комментарий
  блок заканчивается здесь:
*/  ... это тоже не обрабатывается - вся строка внутри комментария
myObject = TEXT
myObject.value (
   Здесь расположены значения
   /*
    Это не комментарий, так как находится внутри многострочного блока значений
   */
)


Присвоение значений: оператор "="

Просто присваивает значение объекту или его свойству.

Правила:

Все после символа "=" и до конца строки интерпретируется как значение. Другими словами, вам не нужно ничего заключать в кавычки.

Имейте в виду, что значение будет очищено от пробелов вокруг него.

Изменение значения: оператор ":="

Оператор присваивает значение объекту или его свойству с использованием предопределенной функции, которая модифицирует существующее значение различным образом.
Это очень полезно, когда нужно изменить значение без полного его переопределения.

Правила:

Часть строки после оператора ":=" и до конца строки делится на две части: функция и значение. Функция определяется прямо за оператором (пробелы удаляются) и содержит значение в круглых скобках (пробелы будут сохранены).

Список предопределенных функций:

  • prependString - добавляет строку в начало существующего значения;
  • appendString -  добавляет строку в конец существующего значения;
  • removeString -  удаляет строку из существующего значения;
  • replaceString - замена существующей строки на новую. Отделяйте их символом "|";
  • addToList - добавляет список значений, отделенных друг от друга запятой, в конец строки. Никаких проверок на дублирование значений не производится и список не сортируется никоим образом;
  • removeFromList - удаляет разделяемый запятыми список значений из существующего списка;
  • uniqueList - удаляет дублирующиеся значения из списка значений;
  • reverseList - меняет порядок следования значений в списке на обратный;
  • sortList - сортирует список значений.

    Дополнительные необязательные параметры:

    • ascending - сортировка в порядке возрастания, от меньших значений к большим, для нецифровых символов - в алфавитном порядке. Это метод по умолчанию;
    • descending - сортировка в порядке убывания - сперва символы в убывающем порядке, затем числа от большего к меньшему;
    • numeric - числовая сортировка: числа от меньшего к большему, символы после "0".


Множественные параметры разделяются запятыми.

Есть хук (hook - в данном случае механизм для включения сторонних функций - прим. перев.) внутри класса \TYPO3\CMS\Core\TypoScript\Parser\TypoScriptParser который может быть использован для определения большего количества подобных функций.

Пример:

myObject = TEXT
myObject.value = 1,2,3
myObject.value := addToList(4,5)
myObject.value := removeFromList(2,1)


дает тот же результат, что и:

myObject = TEXT
myObject.value = 3,4,5

Блоки кода: символы "{}"

Открывающая и закрывающая фигурные скобки используются для упрощения доступа к свойствам объекта. Это называется "вложенные свойства".

Правила:

  • все после символа "{" в этой же строке игнорируется;
  • "}" символ должен иметь самую первую позицию в строке (пробелы не допускаются). Все после символа в этой же строке игнорируется;
  • блоки могут быть вложенными. Это рекомендовано для лучшего восприятия.

Важно!
Нельзя использовать условия "[ ]" внутри блоков кода (за исключением [GLOBAL], которая будет обнаружена и сбросит уровень вложенности в 0)

Примечание
Излишние закрывающие скобки игнорируются, но обработчиком TypoScript будет сгенерирована ошибка.

Пример:
myObject = TEXT
myObject.stdWrap.field = title
myObject.stdWrap.ifEmpty.data = leveltitle:0


может быть также записано таким образом:
myObject = TEXT
myObject {
        stdWrap {
                field = title
                ifEmpty {
                        data = leveltitle:0
                }
        }
}


Многострочные значения: символы "()"

Открывающая и закрывающая круглые скобки используются для присвоения многострочных значений. С помощью этого метода можно определять значения, которые расположены в нескольких строках и содержат символы перевода строки.

Правила:
Закрывающие скобки очень важны. Если они не будут обнаружены, парсер будет считать последующие строки частью многострочного значения и не вернется к обработке TypoScript. Это относится и к условию [GLOBAL], которое не спасет в данной ситуации. Так что не забывайте об этом!

Пример:
myObject = TEXT
   myObject.value (
   <p class="warning">
      This is HTML code.
   </p>
)

Копирование объекта: символ "<"

Символ "<" используется для копирования одного объекта в другой. Копируется весь объект, со свойствами и значениями, все существующие свойства и значения (если есть) перезаписываются новыми.

Пример:
myObject = TEXT
myObject.value = <p class="warning">This is HTML code.</p>

myOtherObject < myObject


В результате получаем два независимых объекта, которые полность идентичны. Это не ссылка нового объекта на существующий, это реально две независимых копии.

Еще один пример копирования, но внутри блока кода:

pageObj {
        10 = TEXT
        10.value = <p class="warning">This is HTML code.</p>
        20 < pageObj.10
}

Здесь также производится копирование, внутри объекта pageObj. Заметьте, что использован полный путь к объекту (pageObj.10). В случае копирования на одном и том же уровне, можно использовать сокращенную форму. Следующий код даст тот же результат, что и в предыдущем примере:

pageObj {
        10 = TEXT
        10.value = <p class="warning">This is HTML code.</p>
        20 < .10
}

Важно!
Если оригинальный объект будет изменен после копирования, копия не изменится! Взгляните на следующий код:

someObject = TEXT
someObject {
        value = Hello world!
        stdWrap.wrap = <p>|<p>
}
anotherObject < someObject
someObject.stdWrap.wrap = <h1>|<h1>


Значением свойства stdWrap.wrap объекта anotherObject является <p>|</p>. Это не <h1>|<h1> потому, что изменения произошли после копирования. Этот пример, возможно, кажется слишком простым, но в больших фрагментах TypoScript можно легко допустить недосмотр.

Ссылки: оператор "=<"

В контексте шаблонов TypoScript возможно создавать ссылки одного объекта на другой. Ссылки означают, что реально копия объекта не создается, новый объект просто ссылается на исходный.
Изменение кода исходного объекта отображается на всех объектах, которые на него ссылаются. Это позволяет избежать рисков, описанных для предыдущего оператора, когда можно упустить из вида факт, что изменение исходного объекта не отражается на копиях. Но с другой стороны существует обратный риск - очень просто забыть, что изменение оригинального объекта затронет все ссылающиеся. Ссылки очень удобны, но должны быть использованы с осторожностью.

Пример:
someObject = TEXT
someObject {
        value = Hello world!
        stdWrap.wrap = <p>|<p>
}
anotherObject =< someObject
someObject.stdWrap.wrap = <h1>|<h1>


В этом случае свойство stdWrap.wrap объекта anotherObject будет на самом деле <h1>|<h1>. При отображении структуры объектов свойства объекта по ссылке не отображаются. Будет показан только сам объект.

Помните:
Ссылки доступны только в шаблонах TypoScript, но не в TSconfig (User TSconfig или Page TSconfig);
Ссылки разрешены только для Content Objects, другие ссылки не разрешены. Например, вы не можете использовать ссылку < plugin.tx_example.settings.foo чтобы найти значение foo. Значение может быть получено только с использованием < plugin.tx_example.settings.foo вместо этого.

Удаление объекта: оператор ">"

Используется для удаления объекта и всех его свойств.

Пример:
myObject = TEXT
myObject.value = <strong> HTML - code </strong>

myObject >


В последней строке объект myObject полностью удален.

Условия: строки, начинающиеся с  "["

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

Правила:
Условия применяются только за пределами блоков кода (т.е. за пределами любых фигурных скобок).

Пример:
[dayofmonth = 9]
page.10.value = Это 9-й день месяца!
[ELSE]
page.10.value = Это НЕ 9-й день месяца!
[END]


Пожалуйста, войдите в систему для комментирования.

0 комментариев