Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
87 / 87
100.00%
6 / 6
 CRAP
100.00%
1 / 1
NameFormatHelp
100.00%
87 / 87
100.00%
6 / 6
 9
100.00%
1 / 1
 markupOptions
100.00%
7 / 7
100.00%
1 / 1
 1
 tokenHelp
100.00%
19 / 19
100.00%
1 / 1
 4
 tokenHelpPlain
100.00%
1 / 1
100.00%
1 / 1
 1
 tokenDefinitions
100.00%
45 / 45
100.00%
1 / 1
 1
 renderableTokenReference
100.00%
4 / 4
100.00%
1 / 1
 1
 renderableTokenHelp
100.00%
11 / 11
100.00%
1 / 1
 1
1<?php
2
3declare(strict_types=1);
4
5namespace Drupal\name\Utility;
6
7use Drupal\Core\StringTranslation\TranslatableMarkup;
8
9/**
10 * Provides translated labels and render arrays for the format-string UI.
11 *
12 * All strings are returned as TranslatableMarkup instances so no Drupal
13 * service container is required; translation is deferred to render time.
14 *
15 * @internal
16 */
17final class NameFormatHelp {
18
19  /**
20   * Returns the supported markup mode labels keyed by machine name.
21   *
22   * @return array<string, \Drupal\Core\StringTranslation\TranslatableMarkup>
23   *   Markup option labels.
24   */
25  public static function markupOptions(): array {
26    return [
27      'none'      => new TranslatableMarkup('No markup'),
28      'raw'       => new TranslatableMarkup('Raw, unescaped text'),
29      'simple'    => new TranslatableMarkup('Component classes'),
30      'microdata' => new TranslatableMarkup('Microdata itemprop components'),
31      'rdfa'      => new TranslatableMarkup('RDFa property components'),
32    ];
33  }
34
35  /**
36   * Returns format token descriptions keyed by token letter.
37   *
38   * @return array<string, \Drupal\Core\StringTranslation\TranslatableMarkup>
39   *   Token descriptions keyed by format letter.
40   */
41  public static function tokenHelp(): array {
42    $tokens = self::tokenDefinitions();
43
44    foreach ($tokens as $letter => $description) {
45      if (preg_match('/^[a-z]+$/', $letter)) {
46        $tokens[$letter] = new TranslatableMarkup(
47          '@description<br><small>(lowercase @letter)</small>',
48          [
49            '@description' => $description,
50            '@letter'      => mb_strtoupper($letter),
51          ],
52        );
53      }
54      elseif (preg_match('/^[A-Z]+$/', $letter)) {
55        $tokens[$letter] = new TranslatableMarkup(
56          '@description<br><small>(uppercase @letter)</small>',
57          [
58            '@description' => $description,
59            '@letter'      => mb_strtoupper($letter),
60          ],
61        );
62      }
63    }
64
65    return $tokens;
66  }
67
68  /**
69   * Returns plain format token descriptions keyed by token letter.
70   *
71   * @return array<string, \Drupal\Core\StringTranslation\TranslatableMarkup>
72   *   Token descriptions keyed by format letter.
73   */
74  public static function tokenHelpPlain(): array {
75    return self::tokenDefinitions();
76  }
77
78  /**
79   * Returns plain token definitions keyed by token letter.
80   *
81   * @return array<string, \Drupal\Core\StringTranslation\TranslatableMarkup>
82   *   Token descriptions keyed by format letter.
83   */
84  private static function tokenDefinitions(): array {
85    return [
86      't' => new TranslatableMarkup('Title.'),
87      'p' => new TranslatableMarkup('Preferred name, use given name if not set.'),
88      'q' => new TranslatableMarkup('Preferred name.'),
89      'g' => new TranslatableMarkup('Given name.'),
90      'm' => new TranslatableMarkup('Middle name(s).'),
91      'f' => new TranslatableMarkup('Family name.'),
92      'c' => new TranslatableMarkup('Credentials.'),
93      's' => new TranslatableMarkup('Generational suffix.'),
94      'a' => new TranslatableMarkup('Alternative value.'),
95      'v' => new TranslatableMarkup('First letter preferred name.'),
96      'w' => new TranslatableMarkup('First letter preferred or given name.'),
97      'x' => new TranslatableMarkup('First letter given.'),
98      'y' => new TranslatableMarkup('First letter middle.'),
99      'z' => new TranslatableMarkup('First letter family.'),
100      'A' => new TranslatableMarkup('First letter of alternative value.'),
101      'I' => new TranslatableMarkup('Initials (all) from given and family.'),
102      'J' => new TranslatableMarkup('Initials (all) from given, middle and family.'),
103      'K' => new TranslatableMarkup('Initials (all) from given.'),
104      'M' => new TranslatableMarkup('Initials (all) from given and middle.'),
105      'd' => new TranslatableMarkup('Conditional: Either the preferred given or family name. Preferred name is given preference over given or family names.'),
106      'D' => new TranslatableMarkup('Conditional: Either the preferred given or family name. Family name is given preference over preferred or given names.'),
107      'e' => new TranslatableMarkup('Conditional: Either the given or family name. Given name is given preference.'),
108      'E' => new TranslatableMarkup('Conditional: Either the given or family name. Family name is given preference.'),
109      'i' => new TranslatableMarkup('Separator 1.'),
110      'j' => new TranslatableMarkup('Separator 2.'),
111      'k' => new TranslatableMarkup('Separator 3.'),
112      '\\' => new TranslatableMarkup('You can prevent a character in the format string from being expanded by escaping it with a preceding backslash.'),
113      'L' => new TranslatableMarkup('Modifier: Converts the next token to all lowercase.'),
114      'U' => new TranslatableMarkup('Modifier: Converts the next token to all uppercase.'),
115      'F' => new TranslatableMarkup('Modifier: Converts the first letter to uppercase.'),
116      'G' => new TranslatableMarkup('Modifier: Converts the first letter of ALL words to uppercase.'),
117      'T' => new TranslatableMarkup('Modifier: Trims whitespace around the next token.'),
118      'S' => new TranslatableMarkup('Modifier: Ensures that the next token is safe for the display.'),
119      'B' => new TranslatableMarkup('Modifier: Use the first word of the next token.'),
120      'b' => new TranslatableMarkup('Modifier: Use the last word of the next token.'),
121      '+' => new TranslatableMarkup('Conditional: Insert the token if both the surrounding tokens are not empty.'),
122      '-' => new TranslatableMarkup('Conditional: Insert the token if the previous token is not empty.'),
123      '~' => new TranslatableMarkup('Conditional: Insert the token if the previous token is empty.'),
124      '=' => new TranslatableMarkup('Conditional: Insert the token if the next token is not empty.'),
125      '^' => new TranslatableMarkup('Conditional: Insert the token if the next token is empty.'),
126      '|' => new TranslatableMarkup('Conditional: Uses the previous token unless empty, otherwise it uses this token.'),
127      '(' => new TranslatableMarkup('Group: Start of token grouping.'),
128      ')' => new TranslatableMarkup('Group: End of token grouping.'),
129    ];
130  }
131
132  /**
133   * Returns a bare theme render array for the format token reference.
134   *
135   * Unlike renderableTokenHelp(), this method omits the collapsible
136   * #details wrapper and is intended for contexts where the list should
137   * always be visible, such as help topics.
138   *
139   * @return array<string, mixed>
140   *   A Drupal render array.
141   */
142  public static function renderableTokenReference(): array {
143    return [
144      '#theme'  => 'name_format_parameter_help',
145      '#tokens' => self::tokenHelp(),
146    ];
147  }
148
149  /**
150   * Returns a renderable details array containing format token help.
151   *
152   * @return array<string, mixed>
153   *   A Drupal render array.
154   */
155  public static function renderableTokenHelp(): array {
156    return [
157      '#type'        => 'details',
158      '#title'       => new TranslatableMarkup('Format string help'),
159      '#collapsible' => TRUE,
160      '#collapsed'   => TRUE,
161      '#parents'     => [],
162      'format_parameters' => [
163        '#theme'  => 'name_format_parameter_help',
164        '#tokens' => self::tokenHelp(),
165      ],
166    ];
167  }
168
169}