1 2=head1 NAME 3 4Text::Xslate::Manual::FAQ - Frequently asked questions and answers 5 6=head1 DESCRIPTION 7 8This manual page lists FAQs, which we've heard for now. 9 10=head1 QUESTIONS 11 12=head2 General 13 14=head3 How do you pronounce 'Xslate'? 15 16We read it C</eks-leit/>. 17 18=head3 What 'Xslate' stands for? 19 20It stands for I<XS template>, a template engine written in XS, although 21pure Perl implementations are also provided. 22 23=head3 What are 'Kolon', 'Metakolon', and 'TTerse' ? 24 25Xslate supports multiple template syntaxes. Kolon is the default syntax, 26Metakolon is suitable to output Kolon templates, and TTerse is compatible 27with Template-Toolkit 2. You can specify the template syntax by passing 28C<syntax> option to the Text::Xslate constructor. 29 30 my $tx = Text::Xslate->new( 31 syntax => 'TTerse', # by moniker 32 ); 33 34 my $tx = Text::Xslate->new( 35 syntax => 'Text::Xslate::Syntax::TTerse', # by fully qualified name 36 ); 37 38=head3 What version of perl does Xslate require? 39 40Xslate is tested on perl v5.8.1. No special settings should be required. 41 42=head3 How can I install the pure-Perl version of Xslate? 43 44Pass C<< PUREPERL_ONLY=1 >> to F<Makefile.PL>, which requests 45the Xslate build system not to make XS parts. 46 47Note that C<< cpanm 1.7 >> supports C<--pp> option to install pure-Perl 48alternatives, so you can type C<< cpanm --pp Text::Xslate >>. 49 50=head3 What optimizations does Xslate employs? 51 52Here are some optimizations worth noting that makes Text::Xslate run so fast, 53in no particular order: 54 55=over 56 57=item Pre-compiled templates 58 59Text::Xslate is among the template engines that pre-compile the templates. 60This is similar to, say, Template::Toolkit, but Text::Xslate compiles the 61templates to C structures and stores them as binary data. 62 63=item Built on top of a virtual machine 64 65Text::Xslate is built on top of virtual machine that executes bytecode, and 66this virtual machine is fine-tuned I<specifically> for template processing. 67 68The virtual machine also employs optimizations such as direct-threading 69style coding to shave off any extra milliseconds that the engine might take 70otherwise 71 72=item Custom byte codes for oft-used operations 73 74Some operations which are used very often are optimized into its own 75byte code. For example (as described elsewhere) Text::Xslate automatically 76escapes HTML unless you tell it not to. Text::Xslate implements this process 77which involves escaping the string I<while> appending the result to the 78output buffer in C, as a custom byte code. This lets you avoid the penalties 79usually involved in such operations. 80 81=item Pre-allocation of output buffers 82 83One of the main things to consider to reduce performance degradation 84while processing a template is to avoid the number of calls to C<malloc()>. 85One of the tricks that Text::Xslate employs to reduce the number of calls to 86C<malloc()> is to pre-allocate the output buffer in an intelligent manner: 87For example, Text::Xslate assumes that most templates will be rendered to be 88about the same as the previous run, so when a template is rendered it uses 89the size allocated for the previous rendering as an approximation of how much 90space the current rendering will require. This allows you to greatly reduce the 91number of C<malloc()> calls required to render a template. 92 93=back 94 95=head3 How can I throw errors in functions and/or methods? 96 97Handle warnings by C<warn_handler> and raises exceptions if needed. 98 99That's because Xslate catches exceptions in templates and emits them as warnings. 100 101=head2 Configuration 102 103=head3 When I create the Xslate instance? 104 105Xslate instances are reusable and creating the instance costs somewhat 106so you're recommended to reuse them as much as possible. 107That is, you should make the instance global. 108 109Consider a PSGI application: 110 111 # create Xslate here, not in psgi_app(); 112 my $xslate = Text::Xslate->new(...); 113 114 sub psgi_app { 115 my($env) = @_; 116 # use $xslate and create $response 117 return $response; 118 } 119 return \&psgi_app; # as a PSGI app 120 121Don't create the instance in each request. It's less efficient. 122 123=head3 How can I change instance attributes dynamically? 124 125Instance attributes, e.g. C<include_path>, C<function>, or C<syntax>, 126are immutable, so you cannot change them dynamically. 127 128Instead, you can create multiple instances by different options. 129instance in order to avoid conflicts with cache directories. 130 131For example: 132 133 my %common_config = ( cache_dir => $dir, module => \@module ); 134 my %xslate = ( 135 ja => Text::Xslate->new( path => [ $template_ja ], %common_config ), 136 en => Text::Xslate->new( path => [ $template_en ], %common_config ), 137 ro => Text::Xslate->new( path => [ $template_ro ], %common_config ), 138 ); 139 $xslate{$lang}->render(...); 140 141=head2 Templates 142 143=head3 How can I changes template tags? 144 145Use C<start_tag>, C<end_tag>, and C<line_start> options to C<new> method, 146which can be joined together with C<syntax> option: 147 148 my $tx = Text::Xslate->new( 149 syntax => 'TTerse', 150 tag_start => '{{', 151 tag_end => '}}', 152 line_start => undef, 153 ); 154 print $tx->render_string('Hello, {{lang}} world!', { lang => 'Xslate' }); 155 156Note that you'd better to avoid symbols which can be used for operators. 157 158=head3 How can I iterate over HASH references? 159 160Convert HASH references into ARRAY references because C<for> methods can 161deal with just ARRAY references. 162 163 : # in Kolon 164 : # iterate $hash by keys 165 : for $hash.keys() -> $key { 166 <: $key :> 167 : } 168 : # by values 169 : for $hash.values() -> $value { 170 <: $value :> 171 : } 172 : # by key-value pairs 173 : for $hash.kv() -> $pair { 174 <: $pair.key :>=<: $pair.value :> 175 : } 176 177Note that the above methods return ARRAY references sorted by the keys. 178 179=head3 How can I use Template-Toolkit virtual methods and filters? 180 181Xslate itself does not support these methods and filters, but there 182are modules on CPAN that implement them. 183 184L<Text::Xslate::Bridge::TT2> provides almost all the TT methods and filters, 185but it requires Template-Toolkit installed. 186 187L<Text::Xslate::Bridge::TT2Like> provides the same features as 188C<T::X::Bridge::TT2>, and it does not require the Template-Toolkit runtime. 189 190These bridge modules are useful not only for TTerse users, but 191also for Kolon users. 192 193=head3 How can I (write|get) plugins? 194 195It is unlikely to need to write plugins for Xslate, because Xslate allows 196you to export any functions to templates. Any function-based modules 197are available by the C<module> option. 198 199Xslate also allows you to call methods for object instances, so you can 200use any object-oriented modules, except for classes which only provide 201class methods (they need wrappers). 202 203If you want to add methods to builtin data types (nil, scalars, arrays and 204hashes), you can write bridge modules. See L<Text::Xslate::Bridge> for details. 205 206=head3 How to limit while-loop like Template-Toolkit? 207 208While Template-Toolkit has a loop counter to prevent runaway C<WHILE> loop, 209Xslate has no arbitrary limitation. 210 211Instead, you can use C<alarm()> to limit B<any> runaway code: 212 213 eval { 214 local $SIG{ALRM} = sub { die @_ }; 215 alarm(1); # set timeout 216 $tx->render('<: while true { } :>', \%vars); 217 }; 218 if($@ =~ /\b ALRM \b/xms) { 219 # timeout! 220 } 221 222=head3 Does Xslate process text strings, or binary strings? 223X<utf8> X<UTF-8> X<utf8 flagged string> X<unicode> 224 225(The meaning of I<text string> and I<binary string> is that of Perl, 226see L<perlunifaq>.) 227 228Xslate assumes template files to be encoded in C<UTF-8> by default, so the 229output is a text string and template parameters, including values which 230registered functions return, B<must> be text strings. 231 232However, if you want to process binary strings, you can do so by passing 233C<:bytes> to C<input_layer>, although it's not recommended. 234 235=head3 Why doesn't I cannot access $object.attr like TT2? 236 237Template-Toolkit allows objects (i.e. blessed references) to access its element if the object has no accessor methods, i.e. C<< [% object.attr %] >> might mean C<< $object->{attr} >>. This behavior breaks encapsulation and hides typos, so Xslate doesn't allow such fallbacks. 238 239If you want to access object attributes, define the accessors of them, 240or prepare values as a non-object before calling C<render()>. 241 242=head3 Can I load macros in other template files? 243 244Not yet. Currently Xslate doesn't support external macros. 245 246=head2 Functions, filters and macros 247 248=head3 Where are the list of builtin functions? 249 250See L<Text::Xslate::Manual::Builtin>. 251 252=head3 How can I use macros as a callback to high-level functions? 253 254Macros are objects that overload C<&{}>, the CODE dereference operator, so 255all you have to do is to call them simply, but don't check their types because 256they are not a I<real> CODE reference. 257 258 my $tx = Text::Xslate->new( 259 function => { 260 count => sub { 261 my($a, $cb) = @_; 262 # Don't check the type of $cb! 263 return scalar grep { $cb->($_) } @{$a}; 264 }, 265 }, 266 ); 267 268 print $tx->render_string('<: count($a, -> $x { $x >= 50 }) :>', 269 { a => [ 0 .. 100 ] }, 270 ); # => 50 271 272 273=head2 Web Application Frameworks 274 275=head3 How can I use Xslate in $my_favorite_WAF? 276 277There are bridges that integrate Xslate into WAFs: 278 279=over 280 281=item * 282 283L<Catalyst::View::Xslate> for L<Catalyst> 284 285=item * 286 287L<MojoX::Renderer::Xslate> for L<Mojolicious> 288 289=item * 290 291L<Tiffany> for general usage 292 293=back 294 295There are WAFs which adopt Xslate as the default template engine: 296 297=over 298 299=item * 300 301L<Amon2> 302 303=item * 304 305L<Pickles> 306 307=back 308 309=head3 Where are examples which use Xslate in Catalyst? 310 311There is a real-world project that uses Xslate with Catalyst. 312 313L<https://github.com/duckduckgo/community-platform> 314 315Initializing Xslate: L<https://github.com/duckduckgo/community-platform/blob/master/lib/DDGC.pm#L268> 316 317Working on: L<https://dukgo.com/> 318 319Enjoy! 320 321=head2 Development and support 322 323=head3 How can I colorize Xslate templates? 324 325For C<vim> user, there is F<xslate.vim> for Kolon: 326 327L<https://github.com/motemen/xslate-vim> 328 329For C<emacs> user, there are plugins: 330 331L<https://github.com/samvtran/kolon-mode> 332 333L<https://github.com/yoshiki/tx-mode> 334 335=head3 Where can I ask questions? 336 337The mailing list is recommended to ask questions. 338 339L<http://groups.google.com/group/xslate> 340 341If you find a bug or have a request, creating github issues is better 342because those tickets are less likely to disappear than the ports in the 343mailing list. 344 345L<https://github.com/xslate/p5-Text-Xslate/issues> 346 347=head3 I found a bug! What can I do for you? 348 349Please make a minimal test case to show the problem clearly. 350The code is the common language both I and you speak fluently ;) 351 352=head1 SEE ALSO 353 354L<Text::Xslate> 355 356L<Text::Xslate::Manual> 357 358L<Text::Xslate::Manual::Cookbook> 359 360=cut 361