| <!DOCTYPE html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <html lang="en"> |
| <head> |
| <title>Apache Velocity Engine - User Guide</title> |
| |
| <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> |
| <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" /> |
| |
| <link rel="stylesheet" type="text/css" href="/css/site.css"> |
| |
| |
| |
| |
| |
| </head> |
| |
| <body> |
| <div id="page"> |
| <div id="header"> |
| |
| <div id="logo2"><img src="/engine/devel/images/velocity-logo.png"/></div> |
| |
| <a href="/"> |
| <svg height="60" width="50%" viewBox="20 20 800 110" preserveAspectRatio="xMinYMin"> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1395.619" x2="-4570.1162" y1="697.55487" x1="-5167.0962" gradientUnits="userSpaceOnUse" id="SVGID_1_"> |
| <stop id="stop3521" style="stop-color:#F69923" offset="0" /> |
| <stop id="stop3523" style="stop-color:#F79A23" offset="0.3123" /> |
| <stop id="stop3525" style="stop-color:#E97826" offset="0.8383" /> |
| </linearGradient> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="620.50482" x2="-5326.209" y1="620.50482" x1="-9585.3418" gradientUnits="userSpaceOnUse" id="SVGID_2_"> |
| <stop id="stop3546" style="stop-color:#9E2064" offset="0.3233" /> |
| <stop id="stop3548" style="stop-color:#C92037" offset="0.6302" /> |
| <stop id="stop3550" style="stop-color:#CD2335" offset="0.7514" /> |
| <stop id="stop3552" style="stop-color:#E97826" offset="1" /> |
| </linearGradient> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1047.6898" x2="-6533.1782" y1="1047.6898" x1="-9071.207" gradientUnits="userSpaceOnUse" id="SVGID_3_"> |
| <stop id="stop3557" style="stop-color:#282662" offset="0" /> |
| <stop id="stop3559" style="stop-color:#662E8D" offset="9.548390e-02" /> |
| <stop id="stop3561" style="stop-color:#9F2064" 1 offset="0.7882" /> |
| <stop id="stop3563" style="stop-color:#CD2032" offset="0.9487" /> |
| </linearGradient> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="580.81702" x2="-5086.9941" y1="580.81702" x1="-9346.126" gradientUnits="userSpaceOnUse" id="SVGID_4_"> |
| <stop id="stop3568" style="stop-color:#9E2064" offset="0.3233" /> |
| <stop id="stop3570" style="stop-color:#C92037" offset="0.6302" /> |
| <stop id="stop3572" style="stop-color:#CD2335" offset="0.7514" /> |
| <stop id="stop3574" style="stop-color:#E97826" offset="1" /> |
| </linearGradient> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="638.4408" x2="-6797.2012" y1="638.4408" x1="-9035.5029" gradientUnits="userSpaceOnUse" id="SVGID_5_"> |
| <stop id="stop3579" style="stop-color:#282662" offset="0" /> |
| <stop id="stop3581" style="stop-color:#662E8D" offset="9.548390e-02" /> |
| <stop id="stop3583" style="stop-color:#9F2064" offset="0.7882" /> |
| <stop id="stop3585" style="stop-color:#CD2032" offset="0.9487" /> |
| </linearGradient> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1021.6218" x2="-5086.9941" y1="1021.6218" x1="-9346.126" gradientUnits="userSpaceOnUse" id="SVGID_6_"> |
| <stop id="stop3590" style="stop-color:#9E2064" offset="0.3233" /> |
| <stop id="stop3592" style="stop-color:#C92037" offset="0.6302" /> |
| <stop id="stop3594" style="stop-color:#CD2335" offset="0.7514" /> |
| <stop id="stop3596" style="stop-color:#E97826" offset="1" /> |
| </linearGradient> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="999.73297" x2="-5351.2017" y1="999.73297" x1="-9610.334" gradientUnits="userSpaceOnUse" id="SVGID_7_"> |
| <stop id="stop3601" style="stop-color:#9E2064" offset="0.3233" /> |
| <stop id="stop3603" style="stop-color:#C92037" offset="0.6302" /> |
| <stop id="stop3605" style="stop-color:#CD2335" offset="0.7514" /> |
| <stop id="stop3607" style="stop-color:#E97826" offset="1" /> |
| </linearGradient> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1152.7261" x2="-5086.9941" y1="1152.7261" x1="-9346.126" gradientUnits="userSpaceOnUse" id="SVGID_8_"> |
| <stop id="stop3616" style="stop-color:#9E2064" offset="0.3233" /> |
| <stop id="stop3618" style="stop-color:#C92037" offset="0.6302" /> |
| <stop id="stop3620" style="stop-color:#CD2335" offset="0.7514" /> |
| <stop id="stop3622" style="stop-color:#E97826" offset="1" /> |
| </linearGradient> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1137.7247" x2="-5086.9941" y1="1137.7247" x1="-9346.126" gradientUnits="userSpaceOnUse" id="SVGID_9_"> |
| <stop id="stop3631" style="stop-color:#9E2064" offset="0.3233" /> |
| <stop id="stop3633" style="stop-color:#C92037" offset="0.6302" /> |
| <stop id="stop3635" style="stop-color:#CD2335" offset="0.7514" /> |
| <stop id="stop3637" style="stop-color:#E97826" offset="1" /> |
| </linearGradient> |
| <linearGradient gradientTransform="matrix(0.07810935,0.01915457,0.02093045,-0.07148201,452.38809,497.7395)" y2="1134.7161" x2="-6011.9995" y1="1134.7161" x1="-6953.4072" gradientUnits="userSpaceOnUse" id="SVGID_10_"> |
| <stop id="stop3646" style="stop-color:#9E2064" offset="0.3233" /> |
| <stop id="stop3648" style="stop-color:#C92037" offset="0.6302" /> |
| <stop id="stop3650" style="stop-color:#CD2335" offset="0.7514" /> |
| <stop id="stop3652" style="stop-color:#E97826" offset="1" /> |
| </linearGradient> |
| <g transform="translate(275,-230)" id="g3735"> |
| <path d="m 95.030525,353.34688 c -5.868388,1.89866 -18.455097,2.86966 -35.232972,2.68962 l -7.844759,-17.69411 c 11.922072,0.96277 23.155947,1.27149 33.446456,0.7785 0.806681,-0.0278 1.205437,-0.0597 1.205437,-0.0597 -0.39975,0.0215 -0.805689,0.0382 -1.205437,0.0597 -3.380984,0.11837 -13.97859,0.22097 -32.909158,-1.88263 6.824373,-6.72909 18.288583,-16.31958 28.008861,-23.85834 18.433387,9.69185 21.017957,20.51606 21.017957,20.51606 0,0 5.61321,15.54576 -6.486385,19.4509 z" id="path3527" style="fill:url(#SVGID_1_)" /> |
| <path d="m 3.8322454,303.07135 c 0.059217,-0.0415 0.1120778,-0.0878 0.1712971,-0.12929 l -1.0221478,0.89604 c -0.088131,0.0386 -0.1658908,0.0658 -0.2478563,0.10915 0.3676459,-0.29732 0.7362578,-0.58424 1.098707,-0.8759 z" id="path3529" style="fill:none" /> |
| <path d="m -27.876072,290.63399 c -0.650899,0.45658 -1.281214,0.94828 -1.904317,1.45519 0.623103,-0.50691 1.259608,-0.99386 1.904317,-1.45519 z" id="path3531" style="fill:none" /> |
| <path d="m -128.18492,294.56272 c 0.27819,0.088 0.55639,0.17608 0.82938,0.26978 5.73136,1.8314 11.32321,3.58465 16.79937,5.26839 6.14427,1.88764 12.119072,3.68379 17.941982,5.39228 6.136306,1.80423 12.096924,3.5122 17.888098,5.1287 6.074555,1.69886 11.961044,3.29193 17.65531,4.79537 4.634037,1.22062 9.141965,2.38304 13.528979,3.48159 1.458542,0.36649 2.910894,0.72823 4.350865,1.08046 2.85092,0.70149 5.659501,1.38013 8.402938,2.03773 2.537553,0.60576 5.026574,1.18393 7.479394,1.74394 0.816212,0.19205 1.625242,0.36892 2.435266,0.55621 0.129295,0.0317 0.263817,0.0577 0.393113,0.0893 l -0.868431,0.76291 0.823816,1.77257 c -0.199639,-0.047 -0.398312,-0.0837 -0.603148,-0.12504 -3.709945,-0.80082 -7.434286,-1.63202 -11.17299,-2.49357 -2.160061,-0.49944 -4.326285,-1.00361 -6.493528,-1.51823 -6.008289,-1.42577 -12.02773,-2.90842 -18.046963,-4.44886 -6.083384,-1.55106 -12.155172,-3.16085 -18.201961,-4.8094 -5.94027,-1.61506 -11.850346,-3.27456 -17.722022,-4.95287 -5.860317,-1.67925 -11.671838,-3.38866 -17.421218,-5.10831 -6.00377,-1.79907 -11.9226,-3.61019 -17.74509,-5.43429 -1.31344,-0.40964 -2.62686,-0.81925 -3.9351,-1.23456 -4.69313,-1.47853 -9.30551,-2.95301 -13.84851,-4.42253 l -1.30665,-2.80027 0.97437,-0.85544 c 0.1365,0.0469 0.27298,0.0937 0.4033,0.1358 5.95137,1.97137 11.76945,3.86936 17.45943,5.68831 z" id="path3533" style="fill:none" /> |
| <path d="m -30.254972,292.46861 0,0 c 0.0052,-0.006 0.01127,-0.001 0.01647,-0.007 0,0 -0.0052,0.006 -0.01647,0.007 z" id="path3535" style="fill:none" /> |
| <path d="m -44.667842,285.26517 c -0.973928,0.73986 -1.967656,1.51281 -2.988395,2.30367 -0.0052,0.006 -0.01647,0.007 -0.02166,0.0123 0.500572,-0.40778 0.995948,-0.80989 1.498505,-1.19683 0.50256,-0.38694 1.00094,-0.75776 1.511673,-1.1191 z" id="path3537" style="fill:#be202e" /> |
| <path d="m -44.667842,285.26517 c -0.973928,0.73986 -1.967656,1.51281 -2.988395,2.30367 -0.0052,0.006 -0.01647,0.007 -0.02166,0.0123 0.500572,-0.40778 0.995948,-0.80989 1.498505,-1.19683 0.50256,-0.38694 1.00094,-0.75776 1.511673,-1.1191 z" id="path3539" style="opacity:0.35;fill:#be202e" /> |
| <path d="m -30.2218,292.45544 c 0,0 -0.0052,0.006 -0.01127,10e-4 -0.0052,0.006 -0.01127,9.9e-4 -0.01647,0.007 0.153662,-0.13318 0.314646,-0.25108 0.463195,-0.37852 0.628302,-0.51257 1.264807,-0.99953 1.904289,-1.45521 -0.763241,0.60216 -1.549259,1.20616 -2.339509,1.82623 l 0,0 0,0 z" id="path3541" style="fill:#be202e" /> |
| <path d="m -30.2218,292.45544 c 0,0 -0.0052,0.006 -0.01127,10e-4 -0.0052,0.006 -0.01127,9.9e-4 -0.01647,0.007 0.153662,-0.13318 0.314646,-0.25108 0.463195,-0.37852 0.628302,-0.51257 1.264807,-0.99953 1.904289,-1.45521 -0.763241,0.60216 -1.549259,1.20616 -2.339509,1.82623 l 0,0 0,0 z" id="path3543" style="opacity:0.35;fill:#be202e" /> |
| <path d="m -3.0502818,330.5069 c 6.1572269,1.1827 12.247534,2.26571 18.2471238,3.24041 6.227231,1.01426 12.356561,1.90504 18.357978,2.65895 0.348762,0.0456 0.708911,0.0903 1.063863,0.1407 5.913525,0.73472 11.699134,1.33257 17.339307,1.78976 l 7.844762,17.69411 c -1.160612,-0.0121 -2.333632,-0.0338 -3.529455,-0.0536 -4.497401,-0.0917 -9.271992,-0.26093 -14.266831,-0.51239 -5.629411,-0.28469 -11.556567,-0.6821 -17.699796,-1.1778 -5.67533,-0.46487 -11.549098,-1.02415 -17.5529729,-1.68334 -5.1106845,-0.5626 -10.3308648,-1.18997 -15.622198,-1.90096 -0.197654,-0.0262 -0.3953057,-0.0524 -0.5929873,-0.0786 L -20.52484,326.94198 c 5.866009,1.25856 11.69707,2.45163 17.4745582,3.56492 z" id="path3554" style="fill:url(#SVGID_2_)" /> |
| <path d="m -148.64432,287.87492 c -4.62455,-1.5418 -9.31626,-3.12551 -14.09367,-4.76537 -0.0714,-0.0258 -0.13651,-0.0469 -0.20787,-0.0727 -0.67629,-0.2295 -1.34737,-0.46467 -2.02369,-0.69419 -3.21697,-1.10818 -6.09263,-2.12815 -12.63913,-4.44059 1.0996,-3.6285 -0.41103,-8.38228 -2.49019,-13.37944 3.85283,3.31605 6.24773,7.77315 6.52364,12.94094 11.22895,-13.43253 25.02773,-21.83891 40.65304,-19.66506 1.39603,0.1929 2.79384,0.46445 4.21819,0.83367 -6.03156,-0.16844 -10.5525,1.89547 -15.78323,8.30262 -0.0165,0.007 -0.0384,0.0188 -0.0549,0.0255 0.0165,-0.007 0.0384,-0.0188 0.0549,-0.0255 12.65883,-5.62036 21.02643,-6.89439 31.69203,-5.50534 2.52825,0.32813 5.18536,0.80351 8.06151,1.40845 -16.05366,1.09099 -26.93227,8.28126 -33.83488,19.35554 l -7.46769,6.54422 c -0.87076,-0.28223 -1.73631,-0.57012 -2.60806,-0.86277 z" id="path3565" style="fill:url(#SVGID_3_)" /> |
| <path d="m -127.92557,298.05617 c 5.82769,1.81842 11.74652,3.62955 17.74512,5.43431 5.74415,1.7253 11.554681,3.42428 17.421188,5.10828 5.866507,1.68401 11.775562,3.33306 17.722022,4.95287 6.046789,1.64856 12.123776,3.25267 18.201961,4.8094 6.013043,1.53569 12.038702,3.02311 18.046963,4.44886 2.167243,0.51462 4.333467,1.0188 6.493528,1.51824 3.738705,0.86155 7.463045,1.69274 11.172991,2.49357 0.199636,0.047 0.398312,0.0837 0.603147,0.12503 l 11.0633797,23.68219 c -0.3953333,-0.0524 -0.7854697,-0.11047 -1.1807777,-0.16285 -5.606921,-0.76978 -11.295338,-1.6118 -17.027898,-2.55534 -5.790549,-0.94943 -11.619023,-1.99561 -17.461681,-3.12996 -4.930086,-0.95526 -9.854792,-1.97402 -14.768868,-3.06189 -0.99728,-0.22482 -1.97698,-0.44581 -2.962873,-0.67154 -6.150175,-1.40914 -11.974938,-2.89686 -17.487932,-4.42532 -6.244233,-1.73255 -12.086525,-3.52355 -17.517683,-5.33696 -3.574927,-1.18983 -6.978977,-2.39336 -10.215327,-3.58405 -2.73994,-1.04133 -5.46008,-2.11577 -8.13662,-3.21469 -6.31977,-2.58273 -12.45563,-5.34303 -18.38577,-8.29314 l -11.10848,-23.79411 c 4.54303,1.46954 9.15538,2.94401 13.84853,4.42255 1.30203,0.41054 2.62167,0.82493 3.93508,1.23455 z" id="path3576" style="fill:url(#SVGID_4_)" /> |
| <path d="m -135.39748,315.78421 c -7.2115,-3.62494 -14.10198,-7.55402 -20.5914,-11.85137 -0.2272,-0.15514 -0.45863,-0.29422 -0.68582,-0.44936 2.3312,6.55285 0.24599,17.70369 0.21823,17.65338 -3.57467,-11.87432 -8.27251,-22.40852 -15.98628,-29.36565 -3.27442,2.37386 -5.94744,7.01608 -8.28358,12.96033 -0.41103,-8.38228 1.53485,-12.94527 2.45003,-14.5997 -4.28418,4.11989 -11.70198,6.14259 -19.64656,7.81875 9.09151,-4.3892 15.21177,-8.8767 17.7976,-13.46995 -24.55723,-8.42409 -51.09999,-18.3439 -78.93127,-29.25317 2.33282,-1.41596 4.74343,-1.47765 7.19121,-0.67033 5.0236,1.99314 38.05928,14.98608 83.16344,30.23283 1.28124,0.43321 2.57389,0.86552 3.8727,1.30257 0.36193,0.12335 0.72908,0.24106 1.08481,0.35966 4.73826,1.59047 9.59244,3.19267 14.55737,4.81229 1.13136,0.36642 2.26272,0.73284 3.40026,1.10401 0.0237,0.009 0.0476,0.0172 0.0652,0.021 l 11.11272,23.77804 c -0.25321,-0.12682 -0.52301,-0.24705 -0.7886,-0.38338 z" id="path3587" style="fill:url(#SVGID_5_)" /> |
| <path d="m -20.879529,324.31241 c -0.803833,-0.18253 -1.613855,-0.36983 -2.435266,-0.5562 -2.447621,-0.56569 -4.936644,-1.14385 -7.479421,-1.74397 -2.748608,-0.6519 -5.5458,-1.33146 -8.402911,-2.03771 -1.439971,-0.35222 -2.880933,-0.71488 -4.350864,-1.08045 -4.387015,-1.09855 -8.894942,-2.26097 -13.528979,-3.48159 -5.694267,-1.50344 -11.580756,-3.09652 -17.65531,-4.79538 -5.791175,-1.61649 -11.75182,-3.32448 -17.888098,-5.1287 -5.82291,-1.70849 -11.803902,-3.50939 -17.941982,-5.39227 -5.47616,-1.68374 -11.06801,-3.43699 -16.79937,-5.26839 -0.27821,-0.088 -0.55639,-0.17608 -0.82938,-0.26978 -5.68998,-1.81895 -11.50806,-3.71694 -17.44804,-5.68923 -0.13651,-0.0469 -0.27299,-0.0937 -0.40331,-0.1358 l 7.4677,-6.54423 c -0.099,0.16552 -0.21555,0.32718 -0.31452,0.4927 9.07173,-7.71799 26.60886,-13.7657 42.082402,-14.50031 7.130974,-0.33982 14.689435,0.18964 22.840099,1.56994 6.067741,1.02703 12.461933,2.52695 19.257152,4.49905 5.938834,1.72022 12.180797,3.78914 18.773426,6.22395 -2.953943,1.10323 -5.869407,2.7287 -8.744022,4.78162 -0.499373,0.3604 -1.009112,0.73216 -1.511672,1.1191 -0.502585,0.38691 -1.004151,0.78427 -1.498505,1.19683 l 0,0 0,0 c 0.0052,-0.006 0.01647,-0.007 0.02166,-0.0123 10.741665,-5.44059 21.911677,-5.49972 33.275347,-3.05294 -3.512293,0.90633 -8.725108,2.75774 -13.490013,6.1124 -0.650869,0.45659 -1.281184,0.9483 -1.904287,1.4552 -0.160021,0.1283 -0.314677,0.25106 -0.463195,0.37852 l 0,0 0,0 c 0.0052,-0.006 0.01127,-9.9e-4 0.01647,-0.007 0,0 0.0052,-0.006 0.01127,-9.9e-4 l 0,0 c 3.833524,-1.80927 7.415482,-3.06785 10.971709,-3.81484 0.75953,-0.16062 1.521076,-0.30038 2.285595,-0.40887 1.160272,-0.17169 2.320337,-0.28559 3.490588,-0.35301 0.747698,-0.0441 1.497407,-0.0674 2.255322,-0.065 1.7736055,-1.9e-4 3.5809872,0.11249 5.4459147,0.34666 0.5691898,0.07 1.1394009,0.1504 1.7219926,0.24033 0.8080111,0.16642 1.5932437,0.33468 2.3670894,0.50385 3.4947139,0.7708 6.5151055,1.56378 9.1028098,2.33365 1.2938545,0.38493 2.4717831,0.75813 3.5461715,1.12911 0.427069,0.1444 0.842778,0.28973 1.24088,0.4312 1.189109,0.43009 2.22612,0.83033 3.11722,1.20547 1.333581,0.56035 2.345383,1.05716 3.054216,1.4469 l 0,0 0,0 c -0.484902,0.0914 -1.006187,0.22239 -1.55767,0.39787 -3.810562,1.20862 -9.0630554,4.26613 -12.8155016,7.10372 l 6.8589836,-6.00695 -6.8589836,6.00695 c -0.059219,0.0415 -0.1120802,0.0878 -0.1712972,0.1293 -0.3686395,0.2869 -0.73626,0.58424 -1.1100962,0.87681 0.088156,-0.0386 0.1659184,-0.0658 0.2478563,-0.10915 l -23.4688293,20.55321 c -0.123105,-0.0269 -0.246211,-0.0538 -0.380705,-0.0798 z" id="path3598" style="fill:url(#SVGID_6_)" /> |
| <path d="m 52.489098,337.22784 c -5.221409,-0.58001 -11.072737,-1.32494 -17.582802,-2.29555 -0.337345,-0.0465 -0.687098,-0.10255 -1.030661,-0.15384 -5.631475,-0.8466 -11.74798,-1.84346 -18.359704,-3.03705 -5.7115598,-1.02402 -11.780866,-2.1875 -18.2388704,-3.51423 -5.6261705,-1.15166 -11.5511356,-2.4265 -17.7644676,-3.83584 L 2.9813947,303.8381 c 9.3594193,-4.04821 15.0606363,-4.69376 22.0219053,-4.22681 1.892116,0.15844 3.845172,0.35401 5.836389,0.58854 6.095793,0.72012 12.552647,1.79478 18.766426,3.08853 5.997499,1.25326 11.744739,2.71043 16.714058,4.25614 3.159483,0.98674 6.000949,2.00943 8.377522,3.03258 2.095388,0.90383 4.020884,1.83177 5.804442,2.7763 -9.724453,7.55488 -21.194854,17.14061 -28.013039,23.87446 z" id="path3609" style="fill:url(#SVGID_7_)" /> |
| <path d="m -46.179514,286.38427 c -0.502558,0.38693 -1.004124,0.78429 -1.498506,1.19682 l 0,0 c 0.494382,-0.41253 0.995948,-0.80989 1.498506,-1.19682 z" id="path3611" style="fill:#be202e" /> |
| <path d="m -46.179514,286.38427 c -0.502558,0.38693 -1.004124,0.78429 -1.498506,1.19682 l 0,0 c 0.494382,-0.41253 0.995948,-0.80989 1.498506,-1.19682 z" id="path3613" style="opacity:0.35;fill:#be202e" /> |
| <path d="m -46.179514,286.38427 c -0.502558,0.38693 -1.004124,0.78429 -1.498506,1.19682 l 0,0 c 0.494382,-0.41253 0.995948,-0.80989 1.498506,-1.19682 z" id="path3624" style="fill:url(#SVGID_8_)" /> |
| <path d="m -30.254972,292.46861 c 0.153663,-0.13318 0.314647,-0.25107 0.463193,-0.37852 -0.148463,0.12751 -0.303257,0.25016 -0.463193,0.37852 l 0,0 z" id="path3626" style="fill:#be202e" /> |
| <path d="m -30.254972,292.46861 c 0.153663,-0.13318 0.314647,-0.25107 0.463193,-0.37852 -0.148463,0.12751 -0.303257,0.25016 -0.463193,0.37852 l 0,0 z" id="path3628" style="opacity:0.35;fill:#be202e" /> |
| <path d="m -30.254972,292.46861 c 0.153663,-0.13318 0.314647,-0.25107 0.463193,-0.37852 -0.148463,0.12751 -0.303257,0.25016 -0.463193,0.37852 l 0,0 z" id="path3639" style="fill:url(#SVGID_9_)" /> |
| <path d="m -30.233189,292.45636 c 0,0 0.0052,-0.006 0.01127,-0.001 l 0,0 0,0 0,0 c 0,0 -0.0052,0.006 -0.01127,0.001 z" id="path3641" style="fill:#be202e" /> |
| <path d="m -30.233189,292.45636 c 0,0 0.0052,-0.006 0.01127,-0.001 l 0,0 0,0 0,0 c 0,0 -0.0052,0.006 -0.01127,0.001 z" id="path3643" style="opacity:0.35;fill:#be202e" /> |
| <path d="m -30.233189,292.45636 c 0,0 0.0052,-0.006 0.01127,-0.001 l 0,0 0,0 0,0 c 0,0 -0.0052,0.006 -0.01127,0.001 z" id="path3654" style="fill:url(#SVGID_10_)" /> |
| </g> |
| <text id="text3761" y="61.094482" x="290" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:40px;line-height:125%;font-family:Oswald;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" xml:space="preserve"> |
| <tspan y="61.094482" x="290" id="tspan3763">The</tspan> |
| </text> |
| <text id="text3416" y="72.094482" x="356" style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:57.5px;line-height:125%;font-family:Oswald;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" xml:space="preserve"> |
| <tspan y="72.094482" x="356" id="tspan3418">Apache Velocity Project</tspan> |
| </text> |
| <path id="path3557" d="m 897.15,23.54449 0,1.58889 3.72099,0 0,10.51111 1.72469,0 0,-10.51111 3.74815,0 0,-1.58889 -9.19383,0 z m 21.49753,0 -4.15555,8.44691 -4.18272,-8.44691 -2.07778,0 0,12.1 1.58889,0 0,-9.60123 4.11482,8.32469 1.1,0 4.11481,-8.32469 0,9.60123 1.58889,0 0,-12.1 -2.09136,0 z" style="fill:#6d6e71" /> |
| <text id="text3599" y="114.09448" x="400" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:35px;line-height:125%;font-family:Arial;text-align:start;letter-spacing:0.03em;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" xml:space="preserve"> |
| <tspan y="114.09448" x="400" id="tspan3601">http://velocity.apache.org/</tspan> |
| </text> |
| </svg> |
| </a> |
| |
| </div> |
| <div id="breadcrumb"> |
| <ul><li><a href="http://www.apache.org">apache</a></li><li><a href="/">velocity</a></li><li><a href="/engine/">engine</a></li><li><a href="/engine/devel/">devel</a></li><li><a href="#">user guide</a></li></ul> |
| </div> |
| <div id="middle"> |
| <div id="leftnav"> |
| |
| <style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <h2 id="velocity-engine">Velocity Engine<a class="headerlink" href="#velocity-engine" title="Permanent link">¶</a></h2> |
| <ul> |
| <li><a href="index.html">Welcome</a></li> |
| <li><a href="overview.html">Overview</a></li> |
| <li><a href="getting-started.html">Getting Started</a></li> |
| <li><a href="webapps.html">Web Applications</a></li> |
| <li><a href="/download.cgi#engine">Downloads</a></li> |
| <li><a href="http://wiki.apache.org/velocity/VelocityFAQ">FAQ</a></li> |
| </ul> |
| <h2 id="docs">Docs<a class="headerlink" href="#docs" title="Permanent link">¶</a></h2> |
| <ul> |
| <li><a href="user-guide.html">User Guide</a></li> |
| <li><a href="developer-guide.html">Developer Guide</a></li> |
| <li><a href="vtl-reference.html">VTL Reference</a></li> |
| <li><a href="configuration.html">Configuration</a></li> |
| <li><a href="glossary.html">Glossary</a></li> |
| <li><a href="apidocs/index.html">Javadoc</a></li> |
| <li><a href="upgrading.html">Upgrading</a></li> |
| </ul> |
| <h2 id="developers">Developers<a class="headerlink" href="#developers" title="Permanent link">¶</a></h2> |
| <ul> |
| <li><a href="license.html">License</a></li> |
| <li><a href="changes.html">Changes</a></li> |
| <li><a href="dependencies.html">Dependencies</a></li> |
| <li><a href="source-repository.html">Sources</a></li> |
| <li><a href="build.html">Building</a></li> |
| <li><a href="https://issues.apache.org/jira/browse/VELOCITY">Issues</a></li> |
| <li><a href="http://wiki.apache.org/velocity/RoadMap">Road Map</a></li> |
| <li><a href="http://wiki.apache.org/velocity/CodeStandards">Coding Standards</a></li> |
| <li><a href="http://wiki.apache.org/velocity/DocumentationGuidelines">Doc Guidelines</a></li> |
| </ul> |
| <h2 id="community">Community<a class="headerlink" href="#community" title="Permanent link">¶</a></h2> |
| <ul> |
| <li><a href="http://wiki.apache.org/velocity/">Wiki</a></li> |
| <li><a href="/news.html">News</a></li> |
| <li><a href="http://wiki.apache.org/velocity/PoweredByVelocity">Powered by Velocity</a></li> |
| <li><a href="http://wiki.apache.org/velocity/VelocityEditors">IDE/Editor Plugins</a></li> |
| <li><a href="http://wiki.apache.org/velocity/PublishedArticlesAndBooks">Articles and Books</a></li> |
| <li><a href="/contact.html">Mailing Lists</a></li> |
| </ul> |
| <h2 id="translations-outdated">Translations (outdated)<a class="headerlink" href="#translations-outdated" title="Permanent link">¶</a></h2> |
| <ul> |
| <li><a href="http://www.jajakarta.org/velocity/">Site (Japanese)</a></li> |
| <li><a href="translations/user-guide_fi.html">User's Guide (Finnish)</a></li> |
| <li><a href="translations/user-guide_fr.html">User's Guide (French)</a></li> |
| <li><a href="translations/user-guide_es.html">User's Guide (Spanish)</a></li> |
| </ul> |
| |
| <div id="bottom-nav"> |
| <img src="/images/pbv90x30.png"/> |
| <div id="rss"> |
| <a class="poweredBy" href="/rss/news.rss" title="Velocity News Feed"><img class="poweredBy" alt="Velocity News Feed" src="/images/feed-icon-24x24.jpg"></a> |
| </div> |
| <iframe src="http://www.apache.org/ads/buttonbar.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="265"></iframe> |
| </div> |
| </div> |
| <div id="content"><div class="section-content"><style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <h2 id="user-guide-contents">User Guide - Contents<a class="headerlink" href="#user-guide-contents" title="Permanent link">¶</a></h2> |
| <div class="toc"> |
| <ul> |
| <li><a href="#user-guide-contents">User Guide - Contents</a></li> |
| <li><a href="#about-this-guide">About this Guide</a></li> |
| <li><a href="#what-is-velocity">What is Velocity?</a></li> |
| <li><a href="#what-can-velocity-do-for-me">What can Velocity do for me?</a><ul> |
| <li><a href="#the-mud-store-example">The Mud Store Example</a></li> |
| </ul> |
| </li> |
| <li><a href="#velocity-template-language-vtl-an-introduction">Velocity Template Language (VTL): An Introduction</a></li> |
| <li><a href="#hello-velocity-world">Hello Velocity World!</a></li> |
| <li><a href="#comments">Comments</a></li> |
| <li><a href="#references">References</a><ul> |
| <li><a href="#variables">Variables</a></li> |
| <li><a href="#properties">Properties</a></li> |
| <li><a href="#methods">Methods</a></li> |
| <li><a href="#property-lookup-rules">Property Lookup Rules</a></li> |
| <li><a href="#rendering">Rendering</a></li> |
| <li><a href="#index-notation">Index Notation</a></li> |
| </ul> |
| </li> |
| <li><a href="#formal-reference-notation">Formal Reference Notation</a></li> |
| <li><a href="#alternate-values">Alternate values</a></li> |
| <li><a href="#quiet-reference-notation">Quiet Reference Notation</a></li> |
| <li><a href="#strict-rendering-mode">Strict Rendering Mode</a></li> |
| <li><a href="#case-substitution">Case Substitution</a></li> |
| <li><a href="#directives">Directives</a><ul> |
| <li><a href="#set">Set</a><ul> |
| <li><a href="#literals">Literals</a></li> |
| </ul> |
| </li> |
| <li><a href="#conditionals">Conditionals</a><ul> |
| <li><a href="#if-elseif-else">If / ElseIf / Else</a></li> |
| <li><a href="#relational-and-logical-operators">Relational and Logical Operators</a></li> |
| </ul> |
| </li> |
| <li><a href="#loops">Loops</a><ul> |
| <li><a href="#foreach-loop">Foreach Loop</a></li> |
| </ul> |
| </li> |
| <li><a href="#include">Include</a></li> |
| <li><a href="#parse">Parse</a></li> |
| <li><a href="#break">Break</a></li> |
| <li><a href="#stop">Stop</a></li> |
| <li><a href="#evaluate">Evaluate</a></li> |
| <li><a href="#define">Define</a></li> |
| <li><a href="#velocimacros">Velocimacros</a><ul> |
| <li><a href="#velocimacro-arguments">Velocimacro Arguments</a></li> |
| <li><a href="#velocimacro-properties">Velocimacro Properties</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#getting-literal">Getting Literal</a><ul> |
| <li><a href="#currency">Currency</a></li> |
| <li><a href="#escaping-valid-vtl-references">Escaping Valid VTL References</a></li> |
| <li><a href="#escaping-invalid-vtl-references">Escaping Invalid VTL References</a></li> |
| <li><a href="#escaping-vtl-directives">Escaping VTL Directives</a></li> |
| </ul> |
| </li> |
| <li><a href="#vtl-formatting-issues">VTL: Formatting Issues</a></li> |
| <li><a href="#other-features-and-miscellany">Other Features and Miscellany</a><ul> |
| <li><a href="#math">Math</a></li> |
| <li><a href="#range-operator">Range Operator</a></li> |
| <li><a href="#advanced-issues-escaping-and">Advanced Issues: Escaping and !</a></li> |
| <li><a href="#velocimacro-miscellany">Velocimacro Miscellany</a><ul> |
| <li><a href="#can-i-use-a-directive-or-another-vm-as-an-argument-to-a-vm">Can I use a directive or another VM as an argument to a VM?</a></li> |
| <li><a href="#can-i-register-velocimacros-via-parse">Can I register Velocimacros via #parse() ?</a></li> |
| <li><a href="#what-is-velocimacro-autoreloading">What is Velocimacro Autoreloading?</a></li> |
| </ul> |
| </li> |
| <li><a href="#string-concatenation">String Concatenation</a></li> |
| </ul> |
| </li> |
| <li><a href="#feedback">Feedback</a></li> |
| </ul> |
| </div> |
| <h2 id="about-this-guide">About this Guide<a class="headerlink" href="#about-this-guide" title="Permanent link">¶</a></h2> |
| <p>The Velocity User Guide is intended to help page designers and content providers get acquainted with Velocity and the syntax of its simple yet powerful scripting language, the Velocity Template Language (VTL). Many of the examples in this guide deal with using Velocity to embed dynamic content in web sites, but all VTL examples are equally applicable to other pages and templates.</p> |
| <p>Thanks for choosing Velocity!</p> |
| <h2 id="what-is-velocity">What is Velocity?<a class="headerlink" href="#what-is-velocity" title="Permanent link">¶</a></h2> |
| <p>Velocity is a Java-based template engine. It permits web page designers to reference methods defined in Java code. Web designers can work in parallel with Java programmers to develop web sites according to the Model-View-Controller (MVC) model, meaning that web page designers can focus solely on creating a well-designed site, and programmers can focus solely on writing top-notch code. Velocity separates Java code from the web pages, making the web site more maintainable over the long run and providing a viable alternative to <a href="http://java.sun.com/products/jsp/">Java Server Pages</a> (JSPs) or <a href="http://www.php.net/">PHP</a>.</p> |
| <p>Velocity can be used to generate web pages, SQL, PostScript and other output from templates. It can be used either as a standalone utility for generating source code and reports, or as an integrated component of other systems. When complete, Velocity will provide template services for the <a href="http://java.apache.org/turbine/">Turbine</a> web application framework. Velocity+Turbine will provide a template service that will allow web applications to be developed according to a true MVC model.</p> |
| <h2 id="what-can-velocity-do-for-me">What can Velocity do for me?<a class="headerlink" href="#what-can-velocity-do-for-me" title="Permanent link">¶</a></h2> |
| <h3 id="the-mud-store-example">The Mud Store Example<a class="headerlink" href="#the-mud-store-example" title="Permanent link">¶</a></h3> |
| <p>Suppose you are a page designer for an online store that specializes in selling mud. Let's call it "The Online Mud Store". Business is thriving. Customers place orders for various types and quantities of mud. They login to your site using their username and password, which allows them to view their orders and buy more mud. Right now, Terracotta Mud is on sale, which is very popular. A minority of your customers regularly buys Bright Red Mud, which is also on sale, though not as popular and usually relegated to the margin of your web page. Information about each customer is tracked in your database, so one day the question arises, Why not use Velocity to target special deals on mud to the customers who are most interested in those types of mud?</p> |
| <p>Velocity makes it easy to customize web pages to your online visitors. As a web site designer at The Mud Room, you want to make the web page that the customer will see after logging into your site.</p> |
| <p>You meet with software engineers at your company, and everyone has agreed that <em>$customer</em> will hold information pertaining to the customer currently logged in, that <em>$mudsOnSpecial</em> will be all the types mud on sale at present. The <em>$flogger</em> object contains methods that help with promotion. For the task at hand, let's concern ourselves only with these three references. Remember, you don't need to worry about how the software engineers extract the necessary information from the database, you just need to know that it works. This lets you get on with your job, and lets the software engineers get on with theirs.</p> |
| <p>You could embed the following VTL statement in the web page:</p> |
| <div class="codehilite"><pre><span class="p"><</span><span class="nt">html</span><span class="p">></span> |
| <span class="p"><</span><span class="nt">body</span><span class="p">></span> |
| Hello <span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Name</span>! |
| <span class="p"><</span><span class="nt">table</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">mud</span> <span class="o">in</span> <span class="p">$</span><span class="nv">mudsOnSpecial</span> <span class="p">)</span> |
| <span class="cp">#</span><span class="nf">if</span><span class="p"> (</span> <span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">hasPurchased</span><span class="p">($</span><span class="nv">mud</span><span class="p">)</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">></span> |
| <span class="p"><</span><span class="nt">td</span><span class="p">></span> |
| <span class="p">$</span><span class="nv">flogger</span><span class="p">.</span><span class="nv">getPromo</span><span class="p">(</span> <span class="p">$</span><span class="nv">mud</span> <span class="p">)</span> |
| <span class="p"></</span><span class="nt">td</span><span class="p">></span> |
| <span class="p"></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">end</span> |
| <span class="cp">#</span><span class="nf">end</span> |
| <span class="p"></</span><span class="nt">table</span><span class="p">></span> |
| <span class="p"></</span><span class="nt">body</span><span class="p">></span> |
| <span class="p"></</span><span class="nt">html</span><span class="p">></span> |
| </pre></div> |
| |
| |
| <p>The exact details of the <em>foreach</em> statement will be described in greater depth shortly; what's important is the impact this short script can have on your web site. When a customer with a penchant for Bright Red Mud logs in, and Bright Red Mud is on sale, that is what this customer will see, prominently displayed. If another customer with a long history of Terracotta Mud purchases logs in, the notice of a Terracotta Mud sale will be front and center. The flexibility of Velocity is enormous and limited only by your creativity.</p> |
| <p>Documented in the VTL Reference are the many other Velocity elements, which collectively give you the power and flexibility you need to make your web site a web <em>presence</em>. As you get more familiar with these elements, you will begin to unleash the power of Velocity.</p> |
| <h2 id="velocity-template-language-vtl-an-introduction">Velocity Template Language (VTL): An Introduction<a class="headerlink" href="#velocity-template-language-vtl-an-introduction" title="Permanent link">¶</a></h2> |
| <p>The Velocity Template Language (VTL) is meant to provide the easiest, simplest, and cleanest way to incorporate dynamic content in a web page. Even a web page developer with little or no programming experience should soon be capable of using VTL to incorporate dynamic content in a web site.</p> |
| <p>VTL uses <em>references</em> to embed dynamic content in a web site, and a variable is one type of reference. Variables are one type of reference that can refer to something defined in the Java code, or it can get its value from a VTL <em>statement</em> in the web page itself. Here is an example of a VTL statement that could be embedded in an HTML document:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">a</span> <span class="o">=</span> <span class="s2">"Velocity"</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>This VTL statement, like all VTL statements, begins with the <em>#</em> character and contains a directive: <em>set</em>. When an online visitor requests your web page, the Velocity Templating Engine will search through your web page to find all <em>#</em> characters, then determine which mark the beginning of VTL statements, and which of the <em>#</em> characters that have nothing to do with VTL.</p> |
| <p>The <em>#</em> character is followed by a directive, <em>set</em>. The <em>set</em> directive uses an expression (enclosed in brackets) -- an equation that assigns a <em>value</em> to a <em>variable</em>. The variable is listed on the left hand side and its value on the right hand side; the two are separated by an <em>=</em> character.</p> |
| <p>In the example above, the variable is <em>$a</em> and the value is <em>Velocity</em>. This variable, like all references, begins with the <em>$</em> character. String values are always enclosed in quotes, either single or double quotes. Single quotes will ensure that the quoted value will be assigned to the reference as is. Double quotes allow you to use velocity references and directives to interpolate, such as "Hello $name", where the <em>$name</em> will be replaced by the current value before that string literal is assigned to the left hand side of the <em>=</em></p> |
| <p>The following rule of thumb may be useful to better understand how Velocity works: <strong>References begin with <em>$</em> and are used to get something. Directives begin with <em>#</em> and are used to do something.</strong></p> |
| <p>In the example above, <em>#set</em> is used to assign a value to a variable. The variable, <em>$a</em>, can then be used in the template to output "Velocity".</p> |
| <h2 id="hello-velocity-world">Hello Velocity World!<a class="headerlink" href="#hello-velocity-world" title="Permanent link">¶</a></h2> |
| <p>Once a value has been assigned to a variable, you can reference the variable anywhere in your HTML document. In the following example, a value is assigned to <em>$foo</em> and later referenced.</p> |
| <div class="codehilite"><pre><span class="p"><</span><span class="nt">html</span><span class="p">></span> |
| <span class="p"><</span><span class="nt">body</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"Velocity"</span> <span class="p">)</span> |
| Hello <span class="p">$</span><span class="nv">foo</span> World! |
| <span class="p"></</span><span class="nt">body</span><span class="p">></span> |
| <span class="p"></</span><span class="nt">html</span><span class="p">></span> |
| </pre></div> |
| |
| |
| <p>The result is a web page that prints "Hello Velocity World!".</p> |
| <p>To make statements containing VTL directives more readable, we encourage you to start each VTL statement on a new line, although you are not required to do so. The <em>set</em> directive will be revisited in greater detail later on.</p> |
| <h2 id="comments">Comments<a class="headerlink" href="#comments" title="Permanent link">¶</a></h2> |
| <p>Comments allows descriptive text to be included that is not placed into the output of the template engine. Comments are a useful way of reminding yourself and explaining to others what your VTL statements are doing, or any other purpose you find useful. Below is an example of a comment in VTL.</p> |
| <div class="codehilite"><pre><span class="cp">##</span><span class="c"> This is a single line comment.</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>A single line comment begins with <em>##</em> and finishes at the end of the line. If you're going to write a few lines of commentary, there's no need to have numerous single line comments. Multi-line comments, which begin with <em>#*</em> and end with <em>*#</em>, are available to handle this scenario.</p> |
| <div class="codehilite"><pre><span class="x">This is text that is outside the multi-line comment.</span> |
| <span class="x">Online visitors can see it.</span> |
| |
| <span class="cp">#</span><span class="c">*</span> |
| <span class="c"> Thus begins a multi-line comment. Online visitors won't</span> |
| <span class="c"> see this text because the Velocity Templating Engine will</span> |
| <span class="c"> ignore it.</span> |
| <span class="c">*</span><span class="cp">#</span><span class="x"></span> |
| |
| <span class="x">Here is text outside the multi-line comment; it is visible.</span> |
| </pre></div> |
| |
| |
| <p>Here are a few examples to clarify how single line and multi-line comments work:</p> |
| <div class="codehilite"><pre><span class="x">This text is visible. </span><span class="cp">##</span><span class="c"> This text is not.</span><span class="x"></span> |
| <span class="x">This text is visible.</span> |
| <span class="x">This text is visible. </span><span class="cp">#</span><span class="c">* This text, as part of a multi-line</span> |
| <span class="c">comment, is not visible. This text is not visible; it is also</span> |
| <span class="c">part of the multi-line comment. This text still not</span> |
| <span class="c">visible. *</span><span class="cp">#</span><span class="x"> This text is outside the comment, so it is visible.</span> |
| <span class="cp">##</span><span class="c"> This text is not visible.</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>There is a third type of comment, the VTL comment block, which may be used to store any sort of extra information you want to track in the template (e.g. javadoc-style author and versioning information):</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="c">**</span> |
| <span class="c"> This is a VTL comment block and</span> |
| <span class="c"> may be used to store such information</span> |
| <span class="c"> as the document author and versioning</span> |
| <span class="c"> information:</span> |
| <span class="c"> @author John Doe</span> |
| <span class="c"> @version 5</span> |
| <span class="c">*</span><span class="cp">#</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <h2 id="references">References<a class="headerlink" href="#references" title="Permanent link">¶</a></h2> |
| <p>There are three types of references in the VTL: variables, properties and methods. As a designer using the VTL, you and your engineers must come to an agreement on the specific names of references so you can use them correctly in your templates.</p> |
| <h3 id="variables">Variables<a class="headerlink" href="#variables" title="Permanent link">¶</a></h3> |
| <p>The shorthand notation of a variable consists of a leading "$" character followed by a VTL <em>Identifier</em>. A VTL Identifier must start with an alphabetic character (a .. z or A .. Z). The rest of the characters are limited to the following types of characters:</p> |
| <ul> |
| <li>alphabetic (a .. z, A .. Z)</li> |
| <li>numeric (0 .. 9)</li> |
| <li>underscore ("_")</li> |
| </ul> |
| <p>Here are some examples of valid variable references in the VTL:</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">mudSlinger</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">mud_slinger</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">mudSlinger1</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>When VTL references a variable, such as <em>$foo</em>, the variable can get its value from either a <em>set</em> directive in the template, or from the Java code. For example, if the Java variable <em>$foo</em> has the value <em>bar</em> at the time the template is requested, <em>bar</em> replaces all instances of <em>$foo</em> on the web page. Alternatively, if I include the statement</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"bar"</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The output will be the same for all instances of <em>$foo</em> that follow this directive.</p> |
| <h3 id="properties">Properties<a class="headerlink" href="#properties" title="Permanent link">¶</a></h3> |
| <p>The second flavor of VTL references are properties, and properties have a distinctive format. The shorthand notation consists of a leading <em>$</em> character followed a VTL Identifier, followed by a dot character (".") and another VTL Identifier. These are examples of valid property references in the VTL:</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Address</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">purchase</span><span class="p">.</span><span class="nv">Total</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Take the first example, <em>$customer.Address</em>. It can have two meanings. It can mean, Look in the hashtable identified as <em>customer</em> and return the value associated with the key <em>Address</em>. But <em>$customer.Address</em> can also be referring to a method (references that refer to methods will be discussed in the next section); <em>$customer.Address</em> could be an abbreviated way of writing <em>$customer.getAddress()</em>. When your page is requested, Velocity will determine which of these two possibilities makes sense, and then return the appropriate value.</p> |
| <h3 id="methods">Methods<a class="headerlink" href="#methods" title="Permanent link">¶</a></h3> |
| <p>A method is defined in the Java code and is capable of doing something useful, like running a calculation or arriving at a decision. Methods are references that consist of a leading "$" character followed a VTL Identifier, followed by a VTL <em>Method Body</em>. A VTL Method Body consists of a VTL Identifier followed by an left parenthesis character ("("), followed by an optional parameter list, followed by right parenthesis character (")"). These are examples of valid method references in the VTL:</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">getAddress</span><span class="p">()</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">purchase</span><span class="p">.</span><span class="nv">getTotal</span><span class="p">()</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">page</span><span class="p">.</span><span class="nv">setTitle</span><span class="p">(</span> <span class="s2">"My Home Page"</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">person</span><span class="p">.</span><span class="nv">setAttributes</span><span class="p">(</span> <span class="p">[</span><span class="s2">"Strange"</span><span class="p">,</span> <span class="s2">"Weird"</span><span class="p">,</span> <span class="s2">"Excited"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The first two examples -- <em>$customer.getAddress()</em> and <em>$purchase.getTotal()</em> -- may look similar to those used in the Properties section above, <em>$customer.Address</em> and <em>$purchase.Total</em>. If you guessed that these examples must be related some in some fashion, you are correct!</p> |
| <p>VTL Properties can be used as a shorthand notation for VTL Methods. The Property <em>$customer.Address</em> has the exact same effect as using the Method <em>$customer.getAddress()</em>. It is generally preferable to use a Property when available. The main difference between Properties and Methods is that you can specify a parameter list to a Method.</p> |
| <p>The shorthand notation can be used for the following Methods</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">getPlanets</span><span class="p">()</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">annelid</span><span class="p">.</span><span class="nv">getDirt</span><span class="p">()</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">album</span><span class="p">.</span><span class="nv">getPhoto</span><span class="p">()</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>We might expect these methods to return the names of planets belonging to the sun, feed our earthworm, or get a photograph from an album. Only the long notation works for the following Methods.</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">getPlanet</span><span class="p">(</span> <span class="p">[</span><span class="s2">"Earth"</span><span class="p">,</span> <span class="s2">"Mars"</span><span class="p">,</span> <span class="s2">"Neptune"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">##</span><span class="c"> Can't pass a parameter list with $sun.Planets</span><span class="x"></span> |
| |
| <span class="p">$</span><span class="nv">sisyphus</span><span class="p">.</span><span class="nv">pushRock</span><span class="p">()</span><span class="x"></span> |
| <span class="cp">##</span><span class="c"> Velocity assumes I mean $sisyphus.getRock()</span><span class="x"></span> |
| |
| <span class="p">$</span><span class="nv">book</span><span class="p">.</span><span class="nv">setTitle</span><span class="p">(</span> <span class="s2">"Homage to Catalonia"</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">##</span><span class="c"> Can't pass a parameter</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>All array references are treated as if they are fixed-length lists. This means that you can call java.util.List methods and properties on array references. So, if you have a reference to an array (let's say this one is a String[] with three values), you can do:</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">isEmpty</span><span class="p">()</span><span class="x"> or </span><span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">empty</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">size</span><span class="p">()</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">get</span><span class="p">(</span><span class="m">2</span><span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">myarray</span><span class="p">.</span><span class="nv">set</span><span class="p">(</span><span class="m">1</span><span class="p">,</span> <span class="s1">'test'</span><span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Velocity also supports vararg methods. A method like <code>azpublic void setPlanets(String... planets)</code> or even just <code>public void setPlanets(String[] planets)</code> can now accept any number of arguments when called in a template.</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">setPlanets</span><span class="p">(</span><span class="s1">'Earth'</span><span class="p">,</span> <span class="s1">'Mars'</span><span class="p">,</span> <span class="s1">'Neptune'</span><span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">setPlanets</span><span class="p">(</span><span class="s1">'Mercury'</span><span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">setPlanets</span><span class="p">()</span><span class="x"></span> |
| <span class="cp">##</span><span class="c"> Will just pass in an empty, zero-length array</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>As of Velocity 2.0, method calls now provides implicit conversions between all Java basic builtin types: numbers, booleans and strings.</p> |
| <h3 id="property-lookup-rules">Property Lookup Rules<a class="headerlink" href="#property-lookup-rules" title="Permanent link">¶</a></h3> |
| <p>As was mentioned earlier, properties often refer to methods of the parent object. Velocity is quite clever when figuring out which method corresponds to a requested property. It tries out different alternatives based on several established naming conventions. The exact lookup sequence depends on whether or not the property name starts with an upper-case letter. For lower-case names, such as <em>$customer.address</em>, the sequence is</p> |
| <ol> |
| <li>getaddress()</li> |
| <li>getAddress()</li> |
| <li>get("address")</li> |
| <li>isAddress()</li> |
| </ol> |
| <p>For upper-case property names like <em>$customer.Address</em>, it is slightly different:</p> |
| <ol> |
| <li>getAddress()</li> |
| <li>getaddress()</li> |
| <li>get("Address")</li> |
| <li>isAddress()</li> |
| </ol> |
| <h3 id="rendering">Rendering<a class="headerlink" href="#rendering" title="Permanent link">¶</a></h3> |
| <p>The final value resulting from each and every reference (whether variable, property, or method) is converted to a String object when it is rendered into the final output. If there is an object that represents <em>$foo</em> (such as an Integer object), then Velocity will call its <code>.toString()</code> method to resolve the object into a String.</p> |
| <h3 id="index-notation">Index Notation<a class="headerlink" href="#index-notation" title="Permanent link">¶</a></h3> |
| <p>Using the notation of the form <code>$foo[0]</code> can be used to access a given index of an object. This form is synonymous with calling the get(Object) method on a given object i.e, <code>$foo.get(0)</code>, and provides essentially a syntactic shorthand for such operations. Since this simply calls the get method all of the following are valid uses:</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="x">[0] </span><span class="cp">##</span><span class="c"> $foo takes in an Integer look up</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">foo</span><span class="x">[</span><span class="p">$</span><span class="nv">i</span><span class="x">] </span><span class="cp">##</span><span class="c"> Using another reference as the index </span><span class="x"></span> |
| <span class="p">$</span><span class="nv">foo</span><span class="x">["bar"] </span><span class="cp">##</span><span class="c"> Passing a string where $foo may be a Map</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The bracketed syntax also works with Java arrays since Velocity wraps arrays in an access object that provides a <code>get(Integer)</code> method which returns the specified element.</p> |
| <p>The bracketed syntax is valid anywhere <code>.get</code> is valid, for example:</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bar</span><span class="x">[1].junk</span> |
| <span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">callMethod</span><span class="p">()</span><span class="x">[1]</span> |
| <span class="p">$</span><span class="nv">foo</span><span class="x">["apple"][4]</span> |
| </pre></div> |
| |
| |
| <p>A reference can also be set using index notation, for example:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">foo</span><span class="o">[</span><span class="m">0</span><span class="p">]</span> <span class="o">=</span> <span class="m">1</span><span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bar</span><span class="o">[</span><span class="m">1</span><span class="p">]</span> <span class="o">=</span> <span class="m">3</span><span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">map</span><span class="o">[</span><span class="s2">"apple"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"orange"</span><span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The specified element is set with the given value. Velocity tries first the 'set' method on the element, then 'put' to make the assignment.</p> |
| <h2 id="formal-reference-notation">Formal Reference Notation<a class="headerlink" href="#formal-reference-notation" title="Permanent link">¶</a></h2> |
| <p>Shorthand notation for references was used for the examples listed above, but there is also a formal notation for references, which is demonstrated below:</p> |
| <div class="codehilite"><pre><span class="p">${</span><span class="nv">mudSlinger</span><span class="p">}</span><span class="x"></span> |
| <span class="p">${</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Address</span><span class="p">}</span><span class="x"></span> |
| <span class="p">${</span><span class="nv">purchase</span><span class="p">.</span><span class="nv">getTotal</span><span class="p">()}</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>In almost all cases you will use the shorthand notation for references, but in some cases the formal notation is required for correct processing.</p> |
| <p>Suppose you were constructing a sentence on the fly where <em>$vice</em> was to be used as the base word in the noun of a sentence. The goal is to allow someone to choose the base word and produce one of the two following results: "Jack is a pyromaniac." or "Jack is a kleptomaniac.". Using the shorthand notation would be inadequate for this task. Consider the following example:</p> |
| <div class="codehilite"><pre><span class="x">Jack is a </span><span class="p">$</span><span class="nv">vicemaniac</span><span class="x">.</span> |
| </pre></div> |
| |
| |
| <p>There is ambiguity here, and Velocity assumes that <em>$vicemaniac</em>, not <em>$vice</em>, is the Identifier that you mean to use. Finding no value for <em>$vicemaniac</em>, it will return <em>$vicemaniac</em>. Using formal notation can resolve this problem.</p> |
| <div class="codehilite"><pre><span class="x">Jack is a </span><span class="p">${</span><span class="nv">vice</span><span class="p">}</span><span class="x">maniac.</span> |
| </pre></div> |
| |
| |
| <p>Now Velocity knows that <em>$vice</em>, not <em>$vicemaniac</em>, is the reference. Formal notation is often useful when references are directly adjacent to text in a template.</p> |
| <h2 id="alternate-values">Alternate values<a class="headerlink" href="#alternate-values" title="Permanent link">¶</a></h2> |
| <p>Formal reference notations can also be used to provide an <em>alternate value</em> whenever the boolean evaluation of a reference is false.</p> |
| <div class="codehilite"><pre><span class="x">My name is </span><span class="p">${</span><span class="nv">name</span><span class="x">|'John Doe'}</span> |
| </pre></div> |
| |
| |
| <p>If $name is null, empty, false or zero (see <a href="#conditionals">Conditionals</a>), then the altername string <code>'John Doe'</code> will be displayed.</p> |
| <h2 id="quiet-reference-notation">Quiet Reference Notation<a class="headerlink" href="#quiet-reference-notation" title="Permanent link">¶</a></h2> |
| <p>When Velocity encounters an undefined reference, its normal behavior is to output the image of the reference. For example, suppose the following reference appears as part of a VTL template.</p> |
| <div class="codehilite"><pre><span class="p"><</span><span class="nt">input</span> <span class="na">type</span><span class="o">=</span><span class="s">"text"</span> <span class="na">name</span><span class="o">=</span><span class="s">"email"</span> <span class="na">value</span><span class="o">=</span><span class="s">"</span><span class="p">$</span><span class="nv">email</span><span class="s">"</span><span class="p">/></span> |
| </pre></div> |
| |
| |
| <p>When the form initially loads, the variable reference <em>$email</em> has no value, but you prefer a blank text field to one with a value of "$email". Using the quiet reference notation circumvents Velocity's normal behavior; instead of using <em>$email</em> in the VTL you would use <em>$!email</em>. So the above example would look like the following:</p> |
| <div class="codehilite"><pre><span class="p"><</span><span class="nt">input</span> <span class="na">type</span><span class="o">=</span><span class="s">"text"</span> <span class="na">name</span><span class="o">=</span><span class="s">"email"</span> <span class="na">value</span><span class="o">=</span><span class="s">"</span><span class="p">$</span><span class="s">!email"</span><span class="p">/></span> |
| </pre></div> |
| |
| |
| <p>Now when the form is initially loaded and <em>$email</em> still has no value, an empty string will be output instead of "$email".</p> |
| <p>Formal and quiet reference notation can be used together, as demonstrated below.</p> |
| <div class="codehilite"><pre><span class="p"><</span><span class="nt">input</span> <span class="na">type</span><span class="o">=</span><span class="s">"text"</span> <span class="na">name</span><span class="o">=</span><span class="s">"email"</span> <span class="na">value</span><span class="o">=</span><span class="s">"</span><span class="p">$</span><span class="s">!</span><span class="err">{</span><span class="s">email}"</span><span class="p">/></span> |
| </pre></div> |
| |
| |
| <h2 id="strict-rendering-mode">Strict Rendering Mode<a class="headerlink" href="#strict-rendering-mode" title="Permanent link">¶</a></h2> |
| <p>The strict rendering mode is activated by setting the velocity configuration property 'runtime.strict_mode.enable' to true. The general intent of this setting is to make Velocity behave more strictly in cases that are undefined or ambiguous, similar to a programming language, which may be more appropriate for some uses of Velocity. In such undefined or ambiguous cases Velocity will throw an exception. The following discussion outlines the cases in which strict behavior is different from traditional behavior.</p> |
| <p>With this setting references are required to be either placed explicitly into the context or defined with a #set directive or Velocity will throw an exception. References that are in the context with a value of null will not produce an exception. Additionally, if an attempt is made to call a method or a property on an object within a reference that does not define the specified method or property then Velocity will throw an exception. This is also true if there is an attempt to call a method or property on a null value.</p> |
| <p>In the following examples $bar is defined but $foo is not, and all these statements will throw an exception:</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="x"> </span><span class="cp">##</span><span class="c"> Exception</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">bar</span> <span class="o">=</span> <span class="p">$</span><span class="nv">foo</span><span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> Exception</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">if</span><span class="p">($</span><span class="nv">foo</span> <span class="o">==</span> <span class="p">$</span><span class="nv">bar</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> Exception</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">($</span><span class="nv">item</span> <span class="o">in</span> <span class="p">$</span><span class="nv">foo</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> Exception</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Also, The following statements show examples in which Velocity will throw an exception when attempting to call methods or properties that do not exist. In these examples $bar contains an object that defines a property 'foo' which returns a string, and 'retnull' which returns null.</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">bar</span><span class="p">.</span><span class="nv">bogus</span><span class="x"> </span><span class="cp">##</span><span class="c"> $bar does not provide property bogus, Exception</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">bar</span><span class="p">.</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bogus</span><span class="x"> </span><span class="cp">##</span><span class="c"> $bar.foo does not provide property bogus, Exception</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">bar</span><span class="p">.</span><span class="nv">retnull</span><span class="p">.</span><span class="nv">bogus</span><span class="x"> </span><span class="cp">##</span><span class="c"> cannot call a property on null, Exception</pre></span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>In general strict rendering mode behavior is true for all situations in which references are used except for a special case within the #if directive. If a reference is used within a #if or #elseif directive without any methods or properties, and if it is not being compared to another value, then undefined references are allowed. This behavior provides an easy way to test if a reference is defined before using it in a template. In the following example where $foo is not defined the statements will not throw an exception.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p"> ($</span><span class="nv">foo</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> False</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">if</span><span class="p"> (</span> <span class="o">!</span> <span class="p">$</span><span class="nv">foo</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> True</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">if</span><span class="p"> ($</span><span class="nv">foo</span> <span class="o">&&</span> <span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bar</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> False and $foo.bar will not be evaluated</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">if</span><span class="p"> ($</span><span class="nv">foo</span> <span class="o">&&</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">==</span> <span class="s2">"bar"</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> False and $foo == "bar" wil not be evaluated</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">if</span><span class="p"> ($</span><span class="nv">foo1</span> <span class="o">||</span> <span class="p">$</span><span class="nv">foo2</span><span class="p">)</span><span class="cp">#</span><span class="nf">end</span><span class="x"> </span><span class="cp">##</span><span class="c"> False $foo1 and $foo2 are not defined</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Strict rendering mode requires that comparisons of >, <, >= or <= within an #if directive makes sense. Also, the argument to #foreach must be iterable (this behavior can be modified with the property directive.foreach.skip_invalid). Finally, undefined macro references will also throw an exception in strict mode.</p> |
| <p>References that Velocity attempts to render but evaluate to null will cause an Exception. To simply render nothing in this case the reference can be preceded by '$!' instead of '$', similar to non strict mode. Keep in mind this is different from the reference not existing in the context which will always throw an exception when attempting to render it in strict mode. For example, below $foo has a value of null in the context</p> |
| <div class="codehilite"><pre><span class="x">this is </span><span class="p">$</span><span class="nv">foo</span><span class="x"> </span><span class="cp">##</span><span class="c"> throws an exception because $foo is null</span><span class="x"></span> |
| <span class="x">this is </span><span class="p">$</span><span class="x">!foo </span><span class="cp">##</span><span class="c"> renders to "this is " without an exception</span><span class="x"></span> |
| <span class="x">this is </span><span class="p">$</span><span class="x">!bogus </span><span class="cp">##</span><span class="c"> bogus is not in the context so throws an exception</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <h2 id="case-substitution">Case Substitution<a class="headerlink" href="#case-substitution" title="Permanent link">¶</a></h2> |
| <p>Now that you are familiar with references, you can begin to apply them effectively in your templates. Velocity references take advantage of some Java principles that template designers will find easy to use. For example:</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">foo</span><span class="x"></span> |
| |
| <span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">getBar</span><span class="p">()</span><span class="x"></span> |
| <span class="cp">##</span><span class="c"> is the same as</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">Bar</span><span class="x"></span> |
| |
| <span class="p">$</span><span class="nv">data</span><span class="p">.</span><span class="nv">setUser</span><span class="p">(</span><span class="s2">"jon"</span><span class="p">)</span><span class="x"></span> |
| <span class="cp">##</span><span class="c"> is the same as</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">data</span><span class="p">.</span><span class="nv">User</span> <span class="o">=</span> <span class="s2">"jon"</span> <span class="p">)</span><span class="x"></span> |
| |
| <span class="p">$</span><span class="nv">data</span><span class="p">.</span><span class="nv">getRequest</span><span class="p">().</span><span class="nv">getServerName</span><span class="p">()</span><span class="x"></span> |
| <span class="cp">##</span><span class="c"> is the same as</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">data</span><span class="p">.</span><span class="nv">Request</span><span class="p">.</span><span class="nv">ServerName</span><span class="x"></span> |
| <span class="cp">##</span><span class="c"> is the same as</span><span class="x"></span> |
| <span class="p">${</span><span class="nv">data</span><span class="p">.</span><span class="nv">Request</span><span class="p">.</span><span class="nv">ServerName</span><span class="p">}</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>These examples illustrate alternative uses for the same references. Velocity takes advantage of Java's introspection and bean features to resolve the reference names to both objects in the Context as well as the objects methods. It is possible to embed and evaluate references almost anywhere in your template.</p> |
| <p>Velocity, which is modelled on the Bean specifications defined by Sun Microsystems, is case sensitive; however, its developers have strove to catch and correct user errors wherever possible. When the method <em>getFoo()</em> is referred to in a template by <code>$bar.foo</code>, Velocity will first try <code>$getfoo</code>. If this fails, it will then try <code>$getFoo</code>. Similarly, when a template refers to <code>$bar.Foo</code>, Velocity will try <em>$getFoo()</em> first and then try <em>getfoo()</em>.</p> |
| <p>Note: <em>References to instance variables in a template are not resolved.</em> Only references to the attribute equivalents of JavaBean getter/setter methods are resolved (i.e. <code>$foo.Name</code> does resolve to the class Foo's <code>getName()</code> instance method, but not to a public <code>Name</code> instance variable of Foo).</p> |
| <h2 id="directives">Directives<a class="headerlink" href="#directives" title="Permanent link">¶</a></h2> |
| <p>References allow template designers to generate dynamic content for web sites, while <em>directives</em> -- easy to use script elements that can be used to creatively manipulate the output of Java code -- permit web designers to truly take charge of the appearance and content of the web site.</p> |
| <p>Directives always begin with a <code>#</code>. Like references, the name of the directive may be bracketed by a <code>{</code> and a <code>}</code> symbol. This is useful with directives that are immediately followed by text. For example the following will display <code>true enough#elseno way!</code>, which probably isn't the expected behavior.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p">($</span><span class="nv">a</span><span class="o">==</span><span class="m">1</span><span class="p">)</span><span class="x">true enough</span><span class="cp">#</span><span class="nf">elseno</span><span class="x"> way!</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>In such a case, use the brackets to separate <code>#else</code> from the rest of the line.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p">($</span><span class="nv">a</span><span class="o">==</span><span class="m">1</span><span class="p">)</span><span class="x">true enough</span><span class="cp">#{</span><span class="nf">else</span><span class="cp">}</span><span class="x">no way!</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <h3 id="set">Set<a class="headerlink" href="#set" title="Permanent link">¶</a></h3> |
| <p>The <em>#set</em> directive is used for setting the value of a reference. A value can be assigned to either a variable reference or a property reference, and this occurs in brackets, as demonstrated:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">primate</span> <span class="o">=</span> <span class="s2">"monkey"</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Behavior</span> <span class="o">=</span> <span class="p">$</span><span class="nv">primate</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The left hand side (LHS) of the assignment must be a variable reference or a property reference. The right hand side (RHS) can be one of the following types:</p> |
| <ul> |
| <li>Variable reference</li> |
| <li>String literal</li> |
| <li>Property reference</li> |
| <li>Method reference</li> |
| <li>Number literal</li> |
| <li>ArrayList</li> |
| <li>Map</li> |
| </ul> |
| <p>These examples demonstrate each of the aforementioned types:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bill</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> variable reference</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Friend</span> <span class="o">=</span> <span class="s2">"monica"</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> string literal</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Blame</span> <span class="o">=</span> <span class="p">$</span><span class="nv">whitehouse</span><span class="p">.</span><span class="nv">Leak</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> property reference</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Plan</span> <span class="o">=</span> <span class="p">$</span><span class="nv">spindoctor</span><span class="p">.</span><span class="nv">weave</span><span class="p">($</span><span class="nv">web</span><span class="p">)</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> method reference</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Number</span> <span class="o">=</span> <span class="m">123</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c">number literal</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Say</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"Not"</span><span class="p">,</span> <span class="p">$</span><span class="nv">my</span><span class="p">,</span> <span class="s2">"fault"</span><span class="p">]</span> <span class="p">)</span><span class="x"> </span><span class="cp">##</span><span class="c"> ArrayList</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">monkey</span><span class="p">.</span><span class="nv">Map</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"banana"</span> <span class="p">:</span> <span class="s2">"good"</span><span class="p">,</span> <span class="s2">"roast beef"</span> <span class="p">:</span> <span class="s2">"bad"</span><span class="p">})</span><span class="x"> </span><span class="cp">##</span><span class="c"> Map</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>NOTE: For the ArrayList example the elements defined with the [..] operator are accessible using the methods defined in the ArrayList class. So, for example, you could access the first element above using $monkey.Say.get(0).</p> |
| <p>Similarly, for the Map example, the elements defined within the { } operator are accessible using the methods defined in the Map class. So, for example, you could access the first element above using $monkey.Map.get("banana") to return a String 'good', or even $monkey.Map.banana to return the same value.</p> |
| <p>The RHS can also be a simple arithmetic expression:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">value</span> <span class="o">=</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">+</span> <span class="m">1</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">value</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">-</span> <span class="m">1</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">value</span> <span class="o">=</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">*</span> <span class="p">$</span><span class="nv">bar</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">value</span> <span class="o">=</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">/</span> <span class="p">$</span><span class="nv">bar</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>If the RHS is a property or method reference that evaluates to <em>null</em>, then the LHS will be set to null.</p> |
| <p>Unlike some of the other Velocity directives, the <em>#set</em> directive does not have an <em>#end</em> statement.</p> |
| <h4 id="literals">Literals<a class="headerlink" href="#literals" title="Permanent link">¶</a></h4> |
| <p>When using the <em>#set</em> directive, string literals that are enclosed in double quote characters will be parsed and rendered, as shown:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">directoryRoot</span> <span class="o">=</span> <span class="s2">"www"</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">templateName</span> <span class="o">=</span> <span class="s2">"index.vm"</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">template</span> <span class="o">=</span> <span class="s2">"$directoryRoot/$templateName"</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">template</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The output will be</p> |
| <div class="codehilite"><pre>www/index.vm |
| </pre></div> |
| |
| |
| <p>However, when the string literal is enclosed in single quote characters, it will not be parsed:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"bar"</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">foo</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">blargh</span> <span class="o">=</span> <span class="s1">'$foo'</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">blargh</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>This renders as:</p> |
| <div class="codehilite"><pre>bar |
| $foo |
| </pre></div> |
| |
| |
| <p>By default, this feature of using single quotes to render unparsed text is available in Velocity. This default can be changed by editing <code>velocity.properties</code> such that <code>stringliterals.interpolate=false</code>.</p> |
| <p>Alternately, the <em>#[[</em>don't parse me!<em>]]#</em> syntax allows the template designer to easily use large chunks of uninterpreted and unparsed content in VTL code. This can be especially useful in place of <a href="#EscapingVTLDirectives">escaping</a> multiple directives or escaping sections which have content that would otherwise be invalid (and thus unparseable) VTL.</p> |
| <div class="codehilite"><pre><span class="err">#</span><span class="x">[[</span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p"> ($</span><span class="nv">woogie</span> <span class="o">in</span> <span class="p">$</span><span class="nv">boogie</span><span class="p">)</span><span class="x"></span> |
| <span class="x"> nothing will happen to </span><span class="p">$</span><span class="nv">woogie</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| <span class="x">]]</span><span class="err">#</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Renders as:</p> |
| <div class="codehilite"><pre>#foreach ($woogie in $boogie) |
| nothing will happen to $woogie |
| #end |
| </pre></div> |
| |
| |
| <h3 id="conditionals">Conditionals<a class="headerlink" href="#conditionals" title="Permanent link">¶</a></h3> |
| <h4 id="if-elseif-else">If / ElseIf / Else<a class="headerlink" href="#if-elseif-else" title="Permanent link">¶</a></h4> |
| <p>The <em>#if</em> directive in Velocity allows for text to be included when the web page is generated, on the conditional that the if statement is true. For example:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> <strong>Velocity!</strong></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The variable <em>$foo</em> is evaluated to determine whether it is true, which will happen under one of those circumstances:</p> |
| <ul> |
| <li><em>$foo</em> is a boolean (true/false) which has a true value</li> |
| <li><em>$foo</em> is a string or a collection which is not null <strong>and</strong> not empty</li> |
| <li><em>$foo</em> is a number which is not equal to zero</li> |
| <li><em>$foo</em> is an object (other than a string, a number or a collection) which is not null (and for which the standard public methods for querying the object size, length or boolean/string representations, if they exist, indicate a non-empty, non-zero, non-false object).</li> |
| </ul> |
| <p>Please check the <a href="configuration.html#if-directive">#if directive configuration section</a> for implementation details. This section also explains how to change this default behavior so that Velocity skips all checks beyond boolean and nullity ones.</p> |
| <p>To test if a reference has a special values, you can use:</p> |
| <ul> |
| <li><code>#if ($ref == $null)</code> to specifically test for the null value (provided you didn't put anything in <code>$null</code>)</li> |
| <li><code>#if ($ref == false)</code> to specifically test for the false value</li> |
| <li><code>#if ($ref == '')</code> to specifically test for the empty string</li> |
| <li><code>#if ($ref == 0)</code> to specifically test for zero</li> |
| <li><code>#if ($ref.size() == 0)</code> to specifically test for an empty collection</li> |
| </ul> |
| <p>Remember that the Velocity context only contains Objects, so when we say 'boolean', it will be represented as a Boolean (the class). This is true even for methods that return <code>boolean</code> - the introspection infrastructure will return a <code>Boolean</code> of the same logical value.</p> |
| <p>The content between the <em>#if</em> and the <em>#end</em> statements become the output if the evaluation is true. In this case, if <em>$foo</em> is true, the output will be: "Velocity!". Conversely, if <em>$foo</em> has a null value, or if it is a boolean false, the statement evaluates as false, and there is no output.</p> |
| <p>An <em>#elseif</em> or <em>#else</em> element can be used with an <em>#if</em> element. Note that the Velocity Templating Engine will stop at the first expression that is found to be true. In the following example, suppose that <em>$foo</em> has a value of 15 and <em>$bar</em> has a value of 6.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o"><</span> <span class="m">10</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> **Go North**</span> |
| <span class="cp">#</span><span class="nf">elseif</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">==</span> <span class="m">10</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> **Go East**</span> |
| <span class="cp">#</span><span class="nf">elseif</span><span class="p">(</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">==</span> <span class="m">6</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> **Go South**</span> |
| <span class="cp">#</span><span class="nf">else</span><span class="x"></span> |
| <span class="x"> **Go West**</span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>In this example, <em>$foo</em> is greater than 10, so the first two comparisons fail. Next <em>$bar</em> is compared to 6, which is true, so the output is <strong>Go South</strong>.</p> |
| <h4 id="relational-and-logical-operators">Relational and Logical Operators<a class="headerlink" href="#relational-and-logical-operators" title="Permanent link">¶</a></h4> |
| <p>Velocity uses the equivalent operator to determine the relationships between variables. Here is a simple example to illustrate how the equivalent operator is used.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p"> ($</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"deoxyribonucleic acid"</span><span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p"> ($</span><span class="nv">bar</span> <span class="o">=</span> <span class="s2">"ribonucleic acid"</span><span class="p">)</span><span class="x"></span> |
| |
| <span class="cp">#</span><span class="nf">if</span><span class="p"> ($</span><span class="nv">foo</span> <span class="o">==</span> <span class="p">$</span><span class="nv">bar</span><span class="p">)</span><span class="x"></span> |
| <span class="x"> In this case it's clear they aren't equivalent. So...</span> |
| <span class="cp">#</span><span class="nf">else</span><span class="x"></span> |
| <span class="x"> They are not equivalent and this will be the output.</span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Note that the semantics of <em>==</em> are slightly different than Java where <em>==</em> can only be used to test object equality. In Velocity the equivalent operator can be used to directly compare numbers, strings, or objects. When the objects are of different classes, the string representations are obtained by calling <code>toString()</code> for each object and then compared.</p> |
| <p>Velocity has logical AND, OR and NOT operators as well. Below are examples demonstrating the use of the logical AND, OR and NOT operators.</p> |
| <div class="codehilite"><pre><span class="cp">##</span><span class="c"> logical AND</span><span class="x"></span> |
| |
| <span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">&&</span> <span class="p">$</span><span class="nv">bar</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> ** This AND that**</span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The <em>#if()</em> directive will only evaluate to true if both <em>$foo</em> and <em>$bar</em> are true. If <em>$foo</em> is false, the expression will evaluate to false; <em>$bar</em> will not be evaluated. If <em>$foo</em> is true, the Velocity Templating Engine will then check the value of <em>$bar</em>; if <em>$bar</em> is true, then the entire expression is true and <strong>This AND that</strong> becomes the output. If <em>$bar</em> is false, then there will be no output as the entire expression is false.</p> |
| <p>Logical OR operators work the same way, except only one of the references need evaluate to true in order for the entire expression to be considered true. Consider the following example.</p> |
| <div class="codehilite"><pre><span class="cp">##</span><span class="c"> logical OR</span><span class="x"></span> |
| |
| <span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">||</span> <span class="p">$</span><span class="nv">bar</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> **This OR That**</span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>If <em>$foo</em> is true, the Velocity Templating Engine has no need to look at <em>$bar</em>; whether <em>$bar</em> is true or false, the expression will be true, and <strong>This OR That</strong> will be output. If <em>$foo</em> is false, however, <em>$bar</em> must be checked. In this case, if <em>$bar</em> is also false, the expression evaluates to false and there is no output. On the other hand, if <em>$bar</em> is true, then the entire expression is true, and the output is <strong>This OR That</strong></p> |
| <p>With logical NOT operators, there is only one argument :</p> |
| <div class="codehilite"><pre><span class="cp">##</span><span class="c">logical NOT</span><span class="x"></span> |
| |
| <span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="o">!</span><span class="p">$</span><span class="nv">foo</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> **NOT that**</span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Here, the if <em>$foo</em> is true, then <em>!$foo</em> evaluates to false, and there is no output. If <em>$foo</em> is false, then <em>!$foo</em> evaluates to true and <strong>NOT that</strong> will be output. Be careful not to confuse this with the <em>quiet reference $!foo</em> which is something altogether different.</p> |
| <p>There are text versions of all logical operators, including <em>eq</em>, <em>ne</em>, <em>and</em>, <em>or</em>, <em>not</em>, <em>gt</em>, <em>ge</em>, <em>lt</em>, and <em>le</em>.</p> |
| <p>One more useful note. When you wish to include text immediately following a <em>#else</em> directive you will need to use curly brackets immediately surrounding the directive to differentiate it from the following text. (Any directive can be delimited by curly brackets, although this is most useful for <em>#else</em>).</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">==</span> <span class="p">$</span><span class="nv">bar</span><span class="p">)</span><span class="x">it's true!</span><span class="cp">#{</span><span class="nf">else</span><span class="cp">}</span><span class="x">it's not!</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <h3 id="loops">Loops<a class="headerlink" href="#loops" title="Permanent link">¶</a></h3> |
| <h4 id="foreach-loop">Foreach Loop<a class="headerlink" href="#foreach-loop" title="Permanent link">¶</a></h4> |
| <p>The <em>#foreach</em> element allows for looping. For example:</p> |
| <div class="codehilite"><pre><span class="p"><</span><span class="nt">ul</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">product</span> <span class="o">in</span> <span class="p">$</span><span class="nv">allProducts</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">li</span><span class="p">>$</span><span class="nv">product</span><span class="p"></</span><span class="nt">li</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">end</span> |
| <span class="p"></</span><span class="nt">ul</span><span class="p">></span> |
| </pre></div> |
| |
| |
| <p>This <em>#foreach</em> loop causes the <em>$allProducts</em> list (the object) to be looped over for all of the products (targets) in the list. Each time through the loop, the value from <em>$allProducts</em> is placed into the <em>$product</em> variable.</p> |
| <p>The contents of the <em>$allProducts</em> variable is a Vector, a Hashtable or an Array. The value assigned to the <em>$product</em> variable is a Java Object and can be referenced from a variable as such. For example, if <em>$product</em> was really a Product class in Java, its name could be retrieved by referencing the <em>$product.Name</em> method (ie: <em>$Product.getName()</em>).</p> |
| <p>Lets say that <em>$allProducts</em> is a Hashtable. If you wanted to retrieve the key values for the Hashtable as well as the objects within the Hashtable, you can use code like this:</p> |
| <div class="codehilite"><pre><span class="p"><</span><span class="nt">ul</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">key</span> <span class="o">in</span> <span class="p">$</span><span class="nv">allProducts</span><span class="p">.</span><span class="nv">keySet</span><span class="p">()</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">li</span><span class="p">></span>Key: <span class="p">$</span><span class="nv">key</span> -> Value: <span class="p">$</span><span class="nv">allProducts</span><span class="p">.</span><span class="nv">get</span><span class="p">($</span><span class="nv">key</span><span class="p">)</</span><span class="nt">li</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">end</span> |
| <span class="p"></</span><span class="nt">ul</span><span class="p">></span> |
| </pre></div> |
| |
| |
| <p>Velocity provides an easy way to get the loop counter so that you can do something like the following:</p> |
| <div class="codehilite"><pre><span class="p"><</span><span class="nt">table</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">customer</span> <span class="o">in</span> <span class="p">$</span><span class="nv">customerList</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span><span class="p">>$</span><span class="nv">foreach</span><span class="p">.</span><span class="nv">count</span><span class="p"></</span><span class="nt">td</span><span class="p">><</span><span class="nt">td</span><span class="p">>$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Name</span><span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">end</span> |
| <span class="p"></</span><span class="nt">table</span><span class="p">></span> |
| </pre></div> |
| |
| |
| <p>Velocity also provides an easy way to tell if you are on the first or last iteration of a loop, and also lets you define what happens whenever the loop is empty:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">customer</span> <span class="o">in</span> <span class="p">$</span><span class="nv">customerList</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> </span><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foreach</span><span class="p">.</span><span class="nv">first</span> <span class="p">)</span><span class="x"> There are customer: </span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| <span class="x"> </span><span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Name</span><span class="x"> </span><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foreach</span><span class="p">.</span><span class="nv">hasNext</span> <span class="p">)</span><span class="x">,</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">else</span><span class="x"></span> |
| <span class="x"> Nobody around</span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>If you want a zero-based index of the #foreach loop, you can just use $foreach.index instead of $foreach.count. Likewise, $foreach.first and $foreach.last are provided to compliment $foreach.hasNext. If you want to access these properties for an outer #foreach loop, you can reference them directly through the $foreach.parent or $foreach.topmost properties (e.g. $foreach.parent.index or $foreach.topmost.hasNext).</p> |
| <p>It's possible to set a maximum allowed number of times that a loop may be executed. By default there is no max (indicated by a value of 0 or less), but this can be set to an arbitrary number in the <code>velocity.properties</code> file. This is useful as a fail-safe.</p> |
| <div class="codehilite"><pre><span class="c"># The maximum allowed number of loops.</span> |
| <span class="na">directive.foreach.max_loops</span> <span class="o">=</span> <span class="s">-1</span> |
| </pre></div> |
| |
| |
| <p>If you want to stop looping in a foreach from within your template, you can now use the #break directive to stop looping at any time:</p> |
| <div class="codehilite"><pre><span class="cp">##</span><span class="c"> list first 5 customers only</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">customer</span> <span class="o">in</span> <span class="p">$</span><span class="nv">customerList</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> </span><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">foreach</span><span class="p">.</span><span class="nv">count</span> <span class="o">></span> <span class="m">5</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> </span><span class="cp">#</span><span class="nf">break</span><span class="x"></span> |
| <span class="x"> </span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| <span class="x"> </span><span class="p">$</span><span class="nv">customer</span><span class="p">.</span><span class="nv">Name</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <h3 id="include">Include<a class="headerlink" href="#include" title="Permanent link">¶</a></h3> |
| <p>The <em>#include</em> script element allows the template designer to import a local file, which is then inserted into the location where the <em>#include</em> directive is defined. The contents of the file are not rendered through the template engine. For security reasons, the file to be included may only be under TEMPLATE_ROOT.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">include</span><span class="p">(</span> <span class="s2">"one.txt"</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The file to which the <em>#include</em> directive refers is enclosed in quotes. If more than one file will be included, they should be separated by commas.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">include</span><span class="p">(</span> <span class="s2">"one.gif"</span><span class="p">,</span><span class="s2">"two.txt"</span><span class="p">,</span><span class="s2">"three.htm"</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The file being included need not be referenced by name; in fact, it is often preferable to use a variable instead of a filename. This could be useful for targeting output according to criteria determined when the page request is submitted. Here is an example showing both a filename and a variable.</p> |
| <div class="codehilite"><pre>#include( "greetings.txt", $seasonalstock ) |
| </pre></div> |
| |
| |
| <h3 id="parse">Parse<a class="headerlink" href="#parse" title="Permanent link">¶</a></h3> |
| <p>The <em>#parse</em> script element allows the template designer to import a local file that contains VTL. Velocity will parse the VTL and render the template specified.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">parse</span><span class="p">(</span> <span class="s2">"me.vm"</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Like the <em>#include</em> directive, <em>#parse</em> can take a variable rather than a template. Any templates to which <em>#parse</em> refers must be included under TEMPLATE_ROOT. Unlike the <em>#include</em> directive, <em>#parse</em> will only take a single argument.</p> |
| <p>VTL templates can have <em>#parse</em> statements referring to templates that in turn have <em>#parse</em> statements. By default set to 10, the <em>directive.parse.max_depth</em> line of the <code>velocity.properties</code> allows users to customize maximum number of <em>#parse</em> referrals that can occur from a single template. (Note: If the <em>directive.parse.max_depth</em> property is absent from the <code>velocity.properties</code> file, Velocity will set this default to 10.) Recursion is permitted, for example, if the template <code>dofoo.vm</code> contains the following lines:</p> |
| <div class="codehilite"><pre><span class="x">Count down.</span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">count</span> <span class="o">=</span> <span class="m">8</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">parse</span><span class="p">(</span> <span class="s2">"parsefoo.vm"</span> <span class="p">)</span><span class="x"></span> |
| <span class="x">All done with dofoo.vm!</span> |
| </pre></div> |
| |
| |
| <p>It would reference the template <code>parsefoo.vm</code>, which might contain the following VTL:</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">count</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">count</span> <span class="o">=</span> <span class="p">$</span><span class="nv">count</span> <span class="o">-</span> <span class="m">1</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">count</span> <span class="o">></span> <span class="m">0</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> </span><span class="cp">#</span><span class="nf">parse</span><span class="p">(</span> <span class="s2">"parsefoo.vm"</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">else</span><span class="x"></span> |
| <span class="x"> All done with parsefoo.vm!</span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>After "Count down." is displayed, Velocity passes through <code>parsefoo.vm</code>, counting down from 8. When the count reaches 0, it will display the "All done with parsefoo.vm!" message. At this point, Velocity will return to <code>dofoo.vm</code> and output the "All done with dofoo.vm!" message.</p> |
| <h3 id="break">Break<a class="headerlink" href="#break" title="Permanent link">¶</a></h3> |
| <p>The <em>#break</em> directive stops any further rendering of the current execution scope. An "execution scope" is essentially any directive with content (i.e. #foreach, #parse, #evaluate, #define, #macro, or #@somebodymacro) or any "root" scope (i.e. template.merge(...), Velocity.evaluate(...) or velocityEngine.evaluate(...)). Unlike #stop, #break will only stop the innermost, immediate scope, not all of them.</p> |
| <p>If you wish to break out of a specific execution scope that is not necessarily the most immediate one, then you can pass the scope control reference (i.e. $foreach, $template, $evaluate, $define, $macro, or $somebodymacro) as an argument to #break. (e.g. #break($macro)). This will stop rendering of all scopes up to the specified one. When within nested scopes of the same type, remember that you can always access the parent(s) via $<scope>.parent or $<scope>.topmost and pass those to #break instead (e.g. #break($foreach.parent) or #break($macro.topmost)).</p> |
| <h3 id="stop">Stop<a class="headerlink" href="#stop" title="Permanent link">¶</a></h3> |
| <p>The <em>#stop</em> directive stops any further rendering and execution of the template. This is true even when the directive is nested within another template accessed through #parse or located in a velocity macro. The resulting merged output will contain all the content up to the point the #stop directive was encountered. This is handy as an early exit from a template. For debugging purposes, you may provide a message argument (e.g. #stop('$foo was not in context') ) that will be written to the logs (DEBUG level, of course) upon completion of the stop command.</p> |
| <h3 id="evaluate">Evaluate<a class="headerlink" href="#evaluate" title="Permanent link">¶</a></h3> |
| <p>The <em>#evaluate</em> directive can be used to dynamically evaluate VTL. This allows the template to evaluate a string that is created at render time. Such a string might be used to internationalize the template or to include parts of a template from a database.</p> |
| <p>The example below will display <code>abc</code>.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">source1</span> <span class="o">=</span> <span class="s2">"abc"</span><span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">select</span> <span class="o">=</span> <span class="s2">"1"</span><span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">dynamicsource</span> <span class="o">=</span> <span class="s2">"$source$select"</span><span class="p">)</span><span class="x"></span> |
| <span class="cp">##</span><span class="c"> $dynamicsource is now the string '$source1'</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">evaluate</span><span class="p">($</span><span class="nv">dynamicsource</span><span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <h3 id="define">Define<a class="headerlink" href="#define" title="Permanent link">¶</a></h3> |
| <p>The <em>#define</em> directive lets one assign a block of VTL to a reference.</p> |
| <p>The example below will display <code>Hello World!</code>.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">define</span><span class="p">(</span> <span class="p">$</span><span class="nv">block</span> <span class="p">)</span><span class="x">Hello </span><span class="p">$</span><span class="nv">who</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">who</span> <span class="o">=</span> <span class="s1">'World!'</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">block</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <h3 id="velocimacros">Velocimacros<a class="headerlink" href="#velocimacros" title="Permanent link">¶</a></h3> |
| <p>The <em>#macro</em> script element allows template designers to define a repeated segment of a VTL template. Velocimacros are very useful in a wide range of scenarios both simple and complex. This Velocimacro, created for the sole purpose of saving keystrokes and minimizing typographic errors, provides an introduction to the concept of Velocimacros.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">d</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span><span class="p">></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">end</span> |
| </pre></div> |
| |
| |
| <p>The Velocimacro being defined in this example is <em>d</em>, and it can be called in a manner analogous to any other VTL directive:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">d</span><span class="p">()</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>When this template is called, Velocity would replace <em>#d()</em> with a row containing a single, empty data cell. If we want to put something in that cell, we can alter the macro to allow for a body:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">d</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span><span class="p">>$</span>!bodyContent<span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">end</span> |
| </pre></div> |
| |
| |
| <p>Now, if we call the macro just a bit differently, using #@ before the name and providing a body and #end to the call, then Velocity will render the body when it gets to the $!bodyContent:</p> |
| <div class="codehilite"><pre><span class="err">#</span><span class="x">@d()Hello!</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>You can still call the macro as you did before, and since we used the silent reference notation for the body reference ($!bodyContent instead of $bodyContent), it will still render a row with a single, empty data cell.</p> |
| <p>A Velocimacro can also take any number of arguments -- even zero arguments, as demonstrated in the first example, is an option -- but when the Velocimacro is invoked, it must be called with the same number of arguments with which it was defined. Many Velocimacros are more involved than the one defined above. Here is a Velocimacro that takes two arguments, a color and an array.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">tablerows</span> <span class="p">$</span><span class="nv">color</span> <span class="p">$</span><span class="nv">somelist</span> <span class="p">)</span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">something</span> <span class="o">in</span> <span class="p">$</span><span class="nv">somelist</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span> <span class="na">bgcolor</span><span class="o">=</span><span class="p">$</span><span class="nv">color</span><span class="err">></span><span class="p">$</span><span class="nv">something</span><span class="s"></td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">end</span> |
| <span class="cp">#</span><span class="nf">end</span> |
| </pre></div> |
| |
| |
| <p>The Velocimacro being defined in this example, <em>tablerows</em>, takes two arguments. The first argument takes the place of <em>$color</em>, and the second argument takes the place of <em>$somelist</em>.</p> |
| <p>Anything that can be put into a VTL template can go into the body of a Velocimacro. The <em>tablerows</em> Velocimacro is a <em>foreach</em> statement. There are two <em>#end</em> statements in the definition of the <em>#tablerows</em> Velocimacro; the first belongs to the <em>#foreach</em>, the second ends the Velocimacro definition.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">greatlakes</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"Superior"</span><span class="p">,</span><span class="s2">"Michigan"</span><span class="p">,</span><span class="s2">"Huron"</span><span class="p">,</span><span class="s2">"Erie"</span><span class="p">,</span><span class="s2">"Ontario"</span><span class="p">]</span> <span class="p">)</span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">color</span> <span class="o">=</span> <span class="s2">"blue"</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">table</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">tablerows</span><span class="p">(</span> <span class="p">$</span><span class="nv">color</span> <span class="p">$</span><span class="nv">greatlakes</span> <span class="p">)</span> |
| <span class="p"></</span><span class="nt">table</span><span class="p">></span> |
| </pre></div> |
| |
| |
| <p>Notice that <em>$greatlakes</em> takes the place of <em>$somelist</em>. When the <em>#tablerows</em> Velocimacro is called in this situation, the following output is generated:</p> |
| <div class="codehilite"><pre><span class="p"><</span><span class="nt">table</span><span class="p">></span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span> <span class="na">bgcolor</span><span class="o">=</span><span class="s">"blue"</span><span class="p">></span>Superior<span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span> <span class="na">bgcolor</span><span class="o">=</span><span class="s">"blue"</span><span class="p">></span>Michigan<span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span> <span class="na">bgcolor</span><span class="o">=</span><span class="s">"blue"</span><span class="p">></span>Huron<span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span> <span class="na">bgcolor</span><span class="o">=</span><span class="s">"blue"</span><span class="p">></span>Erie<span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="p"><</span><span class="nt">tr</span><span class="p">><</span><span class="nt">td</span> <span class="na">bgcolor</span><span class="o">=</span><span class="s">"blue"</span><span class="p">></span>Ontario<span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="p"></</span><span class="nt">table</span><span class="p">></span> |
| </pre></div> |
| |
| |
| <p>Velocimacros can be defined <em>inline</em> in a Velocity template, meaning that it is unavailable to other Velocity templates on the same web site. Defining a Velocimacro such that it can be shared by all templates has obvious advantages: it reduces the need to redefine the Velocimacro on numerous templates, saving work and reducing the chance of error, and ensures that a single change to a macro available to more than one template.</p> |
| <p>Were the <em>#tablerows($color $list)</em> Velocimacro defined in a Velocimacros template library, this macro could be used on any of the regular templates. It could be used many times and for many different purposes. In the template <code>mushroom.vm</code> devoted to all things fungi, the <em>#tablerows</em> Velocimacro could be invoked to list the parts of a typical mushroom:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">parts</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"volva"</span><span class="p">,</span><span class="s2">"stipe"</span><span class="p">,</span><span class="s2">"annulus"</span><span class="p">,</span><span class="s2">"gills"</span><span class="p">,</span><span class="s2">"pileus"</span><span class="p">]</span> <span class="p">)</span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">cellbgcol</span> <span class="o">=</span> <span class="s2">"#CC00FF"</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">table</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">tablerows</span><span class="p">(</span> <span class="p">$</span><span class="nv">cellbgcol</span> <span class="p">$</span><span class="nv">parts</span> <span class="p">)</span> |
| <span class="p"></</span><span class="nt">table</span><span class="p">></span> |
| </pre></div> |
| |
| |
| <p>When fulfilling a request for <code>mushroom.vm</code>, Velocity would find the <em>#tablerows</em> Velocimacro in the template library (defined in the <code>velocity.properties</code> file) and generate the following output:</p> |
| <div class="codehilite"><pre><span class="nt"><table></span> |
| <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"#CC00FF"</span><span class="nt">></span>volva<span class="nt"></td></tr></span> |
| <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"#CC00FF"</span><span class="nt">></span>stipe<span class="nt"></td></tr></span> |
| <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"#CC00FF"</span><span class="nt">></span>annulus<span class="nt"></td></tr></span> |
| <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"#CC00FF"</span><span class="nt">></span>gills<span class="nt"></td></tr></span> |
| <span class="nt"><tr><td</span> <span class="na">bgcolor=</span><span class="s">"#CC00FF"</span><span class="nt">></span>pileus<span class="nt"></td></tr></span> |
| <span class="nt"></table></span> |
| </pre></div> |
| |
| |
| <h4 id="velocimacro-arguments">Velocimacro Arguments<a class="headerlink" href="#velocimacro-arguments" title="Permanent link">¶</a></h4> |
| <p>Velocimacros can take as arguments any of the following VTL elements :</p> |
| <ul> |
| <li>Reference : anything that starts with '$'</li> |
| <li>String literal : something like "$foo" or 'hello'</li> |
| <li>Number literal : 1, 2 etc</li> |
| <li>IntegerRange : [ 1..2] or [$foo .. $bar]</li> |
| <li>ObjectArray : [ "a", "b", "c"]</li> |
| <li>boolean value true</li> |
| <li>boolean value false</li> |
| </ul> |
| <p>Since 2.0, Velocimacros arguments are passed by value (or, more precisely, the result of their evaluation is passed by reference). This means that they are evaluated only once, even when used several times inside the macro. It means that in the following example:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">callme</span> <span class="p">$</span><span class="nv">a</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> </span><span class="p">$</span><span class="nv">a</span><span class="x"> </span><span class="p">$</span><span class="nv">a</span><span class="x"> </span><span class="p">$</span><span class="nv">a</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| |
| <span class="cp">#</span><span class="nf">callme</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span><span class="p">.</span><span class="nv">bar</span><span class="p">()</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>the method bar() of the reference $foo is only called once.</p> |
| <h4 id="velocimacro-properties">Velocimacro Properties<a class="headerlink" href="#velocimacro-properties" title="Permanent link">¶</a></h4> |
| <p>Several lines in the <code>velocity.properties</code> file allow for flexible implementation of Velocimacros. Note that these are also documented in the <a href="developer-guide.html">Developer Guide</a>.</p> |
| <p><code>velocimacro.library.path</code> - A comma-separated list of all Velocimacro template libraries. By default, Velocity looks for a single library: <em>velocimacros.vtl</em> (since 2.1 ; and if not found it will also look at the old default <em>VM_global_library.vm</em>). The configured template path is used to find the Velocimacro libraries.</p> |
| <p><code>velocimacro.inline.allow</code> - This property, which has possible values of true or false, determines whether Velocimacros can be defined in regular templates. The default, true, allows template designers to define Velocimacros in the templates themselves.</p> |
| <p><code>velocimacro.inline.replace_global</code> - With possible values of true or false, this property allows the user to specify if a Velocimacro defined inline in a template can replace a globally defined template, one that was loaded on startup via the <code>velocimacro.library.path</code> property. The default, <code>false</code>, prevents Velocimacros defined inline in a template from replacing those defined in the template libraries loaded at startup.</p> |
| <p><code>velocimacro.inline.local_scope</code> - This property, with possible values of true or false, defaulting to false, controls if Velocimacros defined inline are 'visible' only to the defining template. In other words, with this property set to true, a template can define inline VMs that are usable only by the defining template. You can use this for fancy VM tricks - if a global VM calls another global VM, with inline scope, a template can define a private implementation of the second VM that will be called by the first VM when invoked by that template. All other templates are unaffected.</p> |
| <p><code>velocimacro.library.autoreload</code> - This property controls Velocimacro library autoloading. The default value is <code>false</code>. When set to <code>true</code> the source Velocimacro library for an invoked Velocimacro will be checked for changes, and reloaded if necessary. This allows you to change and test Velocimacro libraries without having to restart your application or servlet container, just like you can with regular templates. This mode only works when caching is <i>off</i> in the resource loaders (e.g. <code>resource.loader.file.cache = false</code> ). This feature is intended for development, not for production.</p> |
| <p>Please note than when two templates each define a macro with the same name, you either need <code>velocimacro.inline.local_scope</code> or <code>velocimacro.inline.replace_global</code> to be set to true for each template to use its own macro version.</p> |
| <h2 id="getting-literal">Getting Literal<a class="headerlink" href="#getting-literal" title="Permanent link">¶</a></h2> |
| <p>VTL uses special characters, such as <em>$</em> and <em>#</em>, to do its work, so some added care should be taken where using these characters in your templates. This section deals with escaping these characters.</p> |
| <h3 id="currency">Currency<a class="headerlink" href="#currency" title="Permanent link">¶</a></h3> |
| <p>There is no problem writing "I bought a 4 lb. sack of potatoes at the farmer's market for only $2.50!" As mentioned, a VTL identifier always begins with an upper- or lowercase letter, so $2.50 would not be mistaken for a reference.</p> |
| <h3 id="escaping-valid-vtl-references">Escaping Valid VTL References<a class="headerlink" href="#escaping-valid-vtl-references" title="Permanent link">¶</a></h3> |
| <p>Cases may arise where you do not want to have a reference rendered by Velocity. <em>Escaping</em> special characters is the best way to output VTL's special characters in these situations, and this can be done using the backslash ( ** ) character <i>when those special characters are part of a valid VTL reference</i>.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">email</span> <span class="o">=</span> <span class="s2">"foo"</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">email</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>If Velocity encounters a reference in your VTL template to <em>$email</em>, it will search the Context for a corresponding value. Here the output will be <em>foo</em>, because <em>$email</em> is defined. If <em>$email</em> is not defined, the output will be <em>$email</em>.</p> |
| <p>Suppose that <em>$email</em> is defined (for example, if it has the value <em>foo</em>), and that you want to output <em>$email</em>. There are a few ways of doing this, but the simplest is to use the escape character. Here is a demonstration:</p> |
| <div class="codehilite"><pre><span class="cp">##</span><span class="c"> The following line defines $email in this template:</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">email</span> <span class="o">=</span> <span class="s2">"foo"</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">email</span><span class="x"></span> |
| <span class="x">\</span><span class="p">$</span><span class="nv">email</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>renders as</p> |
| <div class="codehilite"><pre>foo |
| $email |
| </pre></div> |
| |
| |
| <p>If, for some reason, you need a backslash before either line above, you can do the following:</p> |
| <div class="codehilite"><pre><span class="cp">##</span><span class="c"> The following line defines $email in this template:</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">email</span> <span class="o">=</span> <span class="s2">"foo"</span> <span class="p">)</span><span class="x"></span> |
| <span class="x">\\</span><span class="p">$</span><span class="nv">email</span><span class="x"></span> |
| <span class="x">\\\</span><span class="p">$</span><span class="nv">email</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>which renders as</p> |
| <div class="codehilite"><pre>\foo |
| \$email |
| </pre></div> |
| |
| |
| <p>Note that the <em>* character bind to the </em>$<em> from the left. The bind-from-left rule causes </em>\\$email<em> to render as </em>\$email<em>. Compare these examples to those in which </em>$email* is not defined.</p> |
| <div class="codehilite"><pre><span class="p">$</span><span class="nv">email</span><span class="x"></span> |
| <span class="x">\</span><span class="p">$</span><span class="nv">email</span><span class="x"></span> |
| <span class="x">\\</span><span class="p">$</span><span class="nv">email</span><span class="x"></span> |
| <span class="x">\\\</span><span class="p">$</span><span class="nv">email</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>renders as</p> |
| <div class="codehilite"><pre>$email |
| \$email |
| \\$email |
| \\\$email |
| </pre></div> |
| |
| |
| <p>Notice Velocity handles references that are defined differently from those that have not been defined. Here is a set directive that gives <em>$foo</em> the value <em>gibbous</em>.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"gibbous"</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">moon</span><span class="x"> = </span><span class="p">$</span><span class="nv">foo</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>The output will be: <em>$moon = gibbous</em> -- where <em>$moon</em> is output as a literal because it is undefined and <em>gibbous</em> is output in place of <em>$foo</em>.</p> |
| <h3 id="escaping-invalid-vtl-references">Escaping Invalid VTL References<a class="headerlink" href="#escaping-invalid-vtl-references" title="Permanent link">¶</a></h3> |
| <p>Sometimes Velocity has trouble parsing your template when it encounters an "invalid reference" that you never intended to be a reference at all. <em>Escaping</em> special characters is, again, the best way to handle these situations, but in these situations, the backslash will likely fail you. Instead of simply trying to escape the problematic <code>$</code> or <code>#</code>, you should probably just replace this:</p> |
| <div class="codehilite"><pre><span class="p">${</span><span class="nv">my</span><span class="x">:invalid:non:reference}</span> |
| </pre></div> |
| |
| |
| <p>with something like this</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">D</span> <span class="o">=</span> <span class="s1">'$'</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">${</span><span class="nv">D</span><span class="p">}</span><span class="err">{</span><span class="x">my:invalid:non:reference}</span> |
| </pre></div> |
| |
| |
| <p>You can, of course, put your <code>$</code> or <code>#</code> string directly into the context from your java code (e.g. <code>context.put("D","$");</code>) to avoid the extra #set() directive in your template(s). Or, if you are using <a href="/tools/devel">VelocityTools</a>, you can just use the EscapeTool like this:</p> |
| <div class="codehilite"><pre><span class="p">${</span><span class="nv">esc</span><span class="p">.</span><span class="nv">d</span><span class="p">}</span><span class="err">{</span><span class="x">my:invalid:non:reference}</span> |
| </pre></div> |
| |
| |
| <p>Escaping of both valid and invalid VTL directives is handled in much the same manner; this is described in more detail in the Directives section.</p> |
| <h3 id="escaping-vtl-directives">Escaping VTL Directives<a class="headerlink" href="#escaping-vtl-directives" title="Permanent link">¶</a></h3> |
| <p>VTL directives can be escaped with the backslash character ("\") in a manner similar to valid VTL references.</p> |
| <div class="codehilite"><pre><span class="cp">##</span><span class="c"> #include( "a.txt" ) renders as <contents of a.txt></span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">include</span><span class="p">(</span> <span class="s2">"a.txt"</span> <span class="p">)</span><span class="x"></span> |
| |
| <span class="cp">##</span><span class="c"> \#include( "a.txt" ) renders as #include( "a.txt" )</span><span class="x"></span> |
| <span class="x">\</span><span class="cp">#</span><span class="nf">include</span><span class="p">(</span> <span class="s2">"a.txt"</span> <span class="p">)</span><span class="x"></span> |
| |
| <span class="cp">##</span><span class="c"> \\#include ( "a.txt" ) renders as \<contents of a.txt></span><span class="x"></span> |
| <span class="x">\\</span><span class="cp">#</span><span class="nf">include</span><span class="p"> (</span> <span class="s2">"a.txt"</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Extra care should be taken when escaping VTL directives that contain multiple script elements in a single directive (such as in an if-else-end statements). Here is a typical VTL if-statement:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">jazz</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> Vyacheslav Ganelin</span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>If <em>$jazz</em> is true, the output is</p> |
| <div class="codehilite"><pre>Vyacheslav Ganelin |
| </pre></div> |
| |
| |
| <p>If <em>$jazz</em> is false, there is no output. Escaping script elements alters the output. Consider the following case:</p> |
| <div class="codehilite"><pre><span class="x">\</span><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">jazz</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> Vyacheslav Ganelin</span> |
| <span class="x">\</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>This causes the directives to be escaped, but the rendering of <em>$jazz</em> proceeds as normal. So, if <em>$jazz</em> is true, the output is</p> |
| <div class="codehilite"><pre>#if( true ) |
| Vyacheslav Ganelin |
| #end |
| </pre></div> |
| |
| |
| <p>Suppose backslashes precede script elements that are legitimately escaped:</p> |
| <div class="codehilite"><pre><span class="x">\\</span><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">jazz</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> Vyacheslav Ganelin</span> |
| <span class="x">\\</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>In this case, if <em>$jazz</em> is true, the output is</p> |
| <div class="codehilite"><pre>\ Vyacheslav Ganelin |
| \ |
| </pre></div> |
| |
| |
| <p>To understand this, note that the <code>#if( arg )</code> when ended by a newline (return) will omit the newline from the output. Therefore, the body of the <code>#if()</code> block follows the first '\', rendered from the '\' preceding the <code>#if()</code>. The last \ is on a different line than the text because there is a newline after 'Ganelin', so the final \, preceding the <code>#end</code> is part of the body of the block.</p> |
| <p>If <em>$jazz</em> is false, the output is</p> |
| <div class="codehilite"><pre>\ |
| </pre></div> |
| |
| |
| <p>Note that things start to break if script elements are not properly escaped.</p> |
| <div class="codehilite"><pre><span class="x">\\\</span><span class="cp">#</span><span class="nf">if</span><span class="p">(</span> <span class="p">$</span><span class="nv">jazz</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> Vyacheslave Ganelin</span> |
| <span class="x">\\</span><span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Here the <em>#if</em> is escaped, but there is an <em>#end</em> remaining; having too many endings will cause a parsing error.</p> |
| <h2 id="vtl-formatting-issues">VTL: Formatting Issues<a class="headerlink" href="#vtl-formatting-issues" title="Permanent link">¶</a></h2> |
| <p>Although VTL in this user guide is often displayed with newlines and whitespaces, the VTL shown below</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">imperial</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"Munetaka"</span><span class="p">,</span><span class="s2">"Koreyasu"</span><span class="p">,</span><span class="s2">"Hisakira"</span><span class="p">,</span><span class="s2">"Morikune"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">shogun</span> <span class="o">in</span> <span class="p">$</span><span class="nv">imperial</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> </span><span class="p">$</span><span class="nv">shogun</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>is equally valid as the following snippet that Geir Magnusson Jr. posted to the Velocity user mailing list to illustrate a completely unrelated point:</p> |
| <div class="codehilite"><pre><span class="x">Send me </span><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">foo</span><span class="o">=[</span><span class="s2">"$10 and "</span><span class="p">,</span><span class="s2">"a pie"</span><span class="p">])</span><span class="cp">#</span><span class="nf">foreach</span><span class="p">($</span><span class="nv">a</span> <span class="o">in</span> <span class="p">$</span><span class="nv">foo</span><span class="p">)$</span><span class="nv">a</span><span class="cp">#</span><span class="nf">end</span><span class="x"> please.</span> |
| </pre></div> |
| |
| |
| <p>Velocity's default behaviour is to gobble up excess whitespace. The preceding directive can be written as:</p> |
| <div class="codehilite"><pre><span class="x">Send me</span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"$10 and "</span><span class="p">,</span><span class="s2">"a pie"</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">a</span> <span class="o">in</span> <span class="p">$</span><span class="nv">foo</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">a</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| <span class="x">please.</span> |
| </pre></div> |
| |
| |
| <p>or as</p> |
| <div class="codehilite"><pre><span class="x">Send me</span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">foo</span> <span class="o">=</span> <span class="o">[</span><span class="s2">"$10 and "</span><span class="p">,</span><span class="s2">"a pie"</span><span class="p">])</span><span class="x"></span> |
| <span class="x"> </span><span class="cp">#</span><span class="nf">foreach</span><span class="x"> (</span><span class="p">$</span><span class="nv">a</span><span class="x"> in </span><span class="p">$</span><span class="nv">foo</span><span class="x"> )</span><span class="p">$</span><span class="nv">a</span><span class="x"></span> |
| <span class="x"> </span><span class="cp">#</span><span class="nf">end</span><span class="x"> please.</span> |
| </pre></div> |
| |
| |
| <p>In each case the output will be the same. Please note that it's possible to configure Velocity with other space gobbling behaviors.</p> |
| <h2 id="other-features-and-miscellany">Other Features and Miscellany<a class="headerlink" href="#other-features-and-miscellany" title="Permanent link">¶</a></h2> |
| <h3 id="math">Math<a class="headerlink" href="#math" title="Permanent link">¶</a></h3> |
| <p>Velocity has a handful of built-in mathematical functions that can be used in templates with the <em>set</em> directive. The following equations are examples of addition, subtraction, multiplication and division, respectively:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">+</span> <span class="m">3</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">-</span> <span class="m">4</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">*</span> <span class="m">6</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">/</span> <span class="m">2</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>When a division operation is performed between two integers, the result will be an integer, as the fractional portion is discarded. Any remainder can be obtained by using the modulus (<em>%</em>) operator.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">%</span> <span class="m">5</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <h3 id="range-operator">Range Operator<a class="headerlink" href="#range-operator" title="Permanent link">¶</a></h3> |
| <p>The range operator can be used in conjunction with <em>#set</em> and <em>#foreach</em> statements. Useful for its ability to produce an object array containing integers, the range operator has the following construction:</p> |
| <div class="codehilite"><pre><span class="x">[n..m]</span> |
| </pre></div> |
| |
| |
| <p>Both <em>n</em> and <em>m</em> must either be or produce integers. Whether <em>m</em> is greater than or less than <em>n</em> will not matter; in this case the range will simply count down. Examples showing the use of the range operator as provided below:</p> |
| <div class="codehilite"><pre><span class="x">First example:</span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">in</span> <span class="o">[</span><span class="m">1</span><span class="o">..</span><span class="m">5</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">foo</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| |
| <span class="x">Second example:</span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">bar</span> <span class="o">in</span> <span class="o">[</span><span class="m">2</span><span class="o">..</span><span class="err">-</span><span class="m">2</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">bar</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| |
| <span class="x">Third example:</span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">arr</span> <span class="o">=</span> <span class="o">[</span><span class="m">0</span><span class="o">..</span><span class="m">1</span><span class="p">]</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">foreach</span><span class="p">(</span> <span class="p">$</span><span class="nv">i</span> <span class="o">in</span> <span class="p">$</span><span class="nv">arr</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="nv">i</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| |
| <span class="x">Fourth example:</span> |
| <span class="x">[1..3]</span> |
| </pre></div> |
| |
| |
| <p>Produces the following output:</p> |
| <div class="codehilite"><pre>First example: |
| 1 2 3 4 5 |
| |
| Second example: |
| 2 1 0 -1 -2 |
| |
| Third example: |
| 0 1 |
| |
| Fourth example: |
| [1..3] |
| </pre></div> |
| |
| |
| <p>Note that the range operator only produces the array when used in conjunction with <em>#set</em> and <em>#foreach</em> directives, as demonstrated in the fourth example.</p> |
| <p>Web page designers concerned with making tables a standard size, but where some will not have enough data to fill the table, will find the range operator particularly useful.</p> |
| <h3 id="advanced-issues-escaping-and">Advanced Issues: Escaping and !<a class="headerlink" href="#advanced-issues-escaping-and" title="Permanent link">¶</a></h3> |
| <p>When a reference is silenced with the <em>!</em> character and the <em>!</em> character preceded by an <em>* escape character, the reference is handled in a special way. Note the differences between regular escaping, and the special case where </em>* precedes <em>!</em> follows it:</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">foo</span> <span class="o">=</span> <span class="s2">"bar"</span> <span class="p">)</span><span class="x"></span> |
| <span class="p">$</span><span class="x">\!foo</span> |
| <span class="p">$</span><span class="x">\!</span><span class="err">{</span><span class="x">foo}</span> |
| <span class="p">$</span><span class="x">\\!foo</span> |
| <span class="p">$</span><span class="x">\\\!foo</span> |
| </pre></div> |
| |
| |
| <p>This renders as:</p> |
| <div class="codehilite"><pre>$!foo |
| $!{foo} |
| $\!foo |
| $\\!foo |
| </pre></div> |
| |
| |
| <p>Contrast this with regular escaping, where <em>* precedes </em>$*:</p> |
| <div class="codehilite"><pre><span class="x">\</span><span class="p">$</span><span class="nv">foo</span><span class="x"></span> |
| <span class="x">\</span><span class="p">$</span><span class="x">!foo</span> |
| <span class="x">\</span><span class="p">$</span><span class="x">!</span><span class="err">{</span><span class="x">foo}</span> |
| <span class="x">\\</span><span class="p">$</span><span class="x">!</span><span class="err">{</span><span class="x">foo}</span> |
| </pre></div> |
| |
| |
| <p>This renders as:</p> |
| <div class="codehilite"><pre>$foo |
| $!foo |
| $!{foo} |
| \bar |
| </pre></div> |
| |
| |
| <h3 id="velocimacro-miscellany">Velocimacro Miscellany<a class="headerlink" href="#velocimacro-miscellany" title="Permanent link">¶</a></h3> |
| <p>This section is a mini-FAQ on topics relating to Velocimacros. This section will change over time, so it's worth checking for new information from time to time.</p> |
| <p>Note : Throughout this section, 'Velocimacro' will commonly be abbreviated as 'VM'.</p> |
| <h4 id="can-i-use-a-directive-or-another-vm-as-an-argument-to-a-vm">Can I use a directive or another VM as an argument to a VM?<a class="headerlink" href="#can-i-use-a-directive-or-another-vm-as-an-argument-to-a-vm" title="Permanent link">¶</a></h4> |
| <p>Example : <code>#center( #bold("hello") )</code></p> |
| <p>No. A directive isn't a valid argument to a directive, and for most practical purposes, a VM is a directive.</p> |
| <p><em>However...</em>, there are things you can do. One easy solution is to take advantage of the fact that 'doublequote' (") renders its contents. So you could do something like</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">stuff</span> <span class="o">=</span> <span class="s2">"#bold('hello')"</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">center</span><span class="p">(</span> <span class="p">$</span><span class="nv">stuff</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>You can save a step...</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">center</span><span class="p">(</span> <span class="s2">"#bold( 'hello' )"</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Please note that in the latter example the arg is evaluated <i>inside</i> the VM, not at the calling level. In other words, the argument to the VM is passed in in its entirety and evaluated within the VM it was passed into. This allows you to do things like :</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">inner</span> <span class="p">$</span><span class="nv">foo</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> inner : </span><span class="p">$</span><span class="nv">foo</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| |
| <span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">outer</span> <span class="p">$</span><span class="nv">foo</span> <span class="p">)</span><span class="x"></span> |
| <span class="x"> </span><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">bar</span> <span class="o">=</span> <span class="s2">"outerlala"</span><span class="p">)</span><span class="x"></span> |
| <span class="x"> outer : </span><span class="p">$</span><span class="nv">foo</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">end</span><span class="x"></span> |
| |
| <span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">bar</span> <span class="o">=</span> <span class="s1">'calltimelala'</span><span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">outer</span><span class="p">(</span> <span class="s2">"#inner($bar)"</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <p>Where the output is</p> |
| <div class="codehilite"><pre><span class="n">Outer</span> <span class="o">:</span> <span class="n">inner</span> <span class="o">:</span> <span class="n">outerlala</span> |
| </pre></div> |
| |
| |
| <p>because the evaluation of the "#inner($bar)" happens inside #outer(), so the $bar value set inside #outer() is the one that's used.</p> |
| <p>This is an intentional and jealously guarded feature - args are passed 'by name' into VMs, so you can hand VMs things like stateful references such as</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">macro</span><span class="p">(</span> <span class="nf">foo</span> <span class="p">$</span><span class="nv">color</span> <span class="p">)</span> |
| <span class="p"><</span><span class="nt">tr</span> <span class="na">bgcolor</span><span class="o">=</span><span class="s">"</span><span class="p">$</span><span class="nv">color</span><span class="s">"</span><span class="p">><</span><span class="nt">td</span><span class="p">></span>Hi<span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="p"><</span><span class="nt">tr</span> <span class="na">bgcolor</span><span class="o">=</span><span class="s">"</span><span class="p">$</span><span class="nv">color</span><span class="s">"</span><span class="p">><</span><span class="nt">td</span><span class="p">></span>There<span class="p"></</span><span class="nt">td</span><span class="p">></</span><span class="nt">tr</span><span class="p">></span> |
| <span class="cp">#</span><span class="nf">end</span> |
| |
| <span class="cp">#</span><span class="nf">foo</span><span class="p">(</span> <span class="p">$</span><span class="nv">bar</span><span class="p">.</span><span class="nv">rowColor</span><span class="p">()</span> <span class="p">)</span> |
| </pre></div> |
| |
| |
| <p>And have rowColor() called repeatedly, rather than just once. To avoid that, invoke the method outside of the VM, and pass the value into the VM.</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">color</span> <span class="o">=</span> <span class="p">$</span><span class="nv">bar</span><span class="p">.</span><span class="nv">rowColor</span><span class="p">())</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">foo</span><span class="p">(</span> <span class="p">$</span><span class="nv">color</span> <span class="p">)</span><span class="x"></span> |
| </pre></div> |
| |
| |
| <h4 id="can-i-register-velocimacros-via-parse">Can I register Velocimacros via #parse() ?<a class="headerlink" href="#can-i-register-velocimacros-via-parse" title="Permanent link">¶</a></h4> |
| <p><strong>Yes! This became possible in Velocity 1.6.</strong></p> |
| <p>If you are using an earlier version, your Velocimacros must be defined before they are first used in a template. This means that your #macro() declarations should come before using the Velocimacros.</p> |
| <p>This is important to remember if you try to #parse() a template containing inline #macro() directives. Because the #parse() happens at runtime, and the parser decides if a VM-looking element in the template is a VM at parsetime, #parse()-ing a set of VM declarations won't work as expected. To get around this, simply use the <code>velocimacro.library</code> facility to have Velocity load your VMs at startup.</p> |
| <h4 id="what-is-velocimacro-autoreloading">What is Velocimacro Autoreloading?<a class="headerlink" href="#what-is-velocimacro-autoreloading" title="Permanent link">¶</a></h4> |
| <p>There is a property, meant to be used in <i>development</i>, not production :</p> |
| <div class="codehilite"><pre>`velocimacro.library.autoreload` |
| </pre></div> |
| |
| |
| <p>which defaults to false. When set to true <em>along with</em></p> |
| <div class="codehilite"><pre>`resource.loader.<type>.cache = false` |
| </pre></div> |
| |
| |
| <p>(where <type> is the name of the resource loader that you are using, such as 'file') then the Velocity engine will automatically reload changes to your Velocimacro library files when you make them, so you do not have to dump the servlet engine (or application) or do other tricks to have your Velocimacros reloaded.</p> |
| <p>Here is what a simple set of configuration properties would look like.</p> |
| <div class="codehilite"><pre>resource.loader.file.path = templates |
| resource.loader.file.cache = false |
| velocimacro.library.autoreload = true |
| </pre></div> |
| |
| |
| <p>Don't keep this on in production.</p> |
| <h3 id="string-concatenation">String Concatenation<a class="headerlink" href="#string-concatenation" title="Permanent link">¶</a></h3> |
| <p>A common question that developers ask is <em>How do I do String concatenation? Is there any analogue to the '+' operator in Java?</em>.</p> |
| <p>To do concatenation of references in VTL, you just have to 'put them together'. The context of where you want to put them together does matter, so we will illustrate with some examples.</p> |
| <p>In the regular 'schmoo' of a template (when you are mixing it in with regular content) :</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">size</span> <span class="o">=</span> <span class="s2">"Big"</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">name</span> <span class="o">=</span> <span class="s2">"Ben"</span> <span class="p">)</span><span class="x"></span> |
| |
| <span class="x">The clock is </span><span class="p">$</span><span class="nv">size</span><span class="p">$</span><span class="nv">name</span><span class="x">.</span> |
| </pre></div> |
| |
| |
| <p>and the output will render as 'The clock is BigBen'. For more interesting cases, such as when you want to concatenate strings to pass to a method, or to set a new reference, just do</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">size</span> <span class="o">=</span> <span class="s2">"Big"</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">name</span> <span class="o">=</span> <span class="s2">"Ben"</span> <span class="p">)</span><span class="x"></span> |
| |
| <span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">clock</span> <span class="o">=</span> <span class="s2">"$size$name"</span> <span class="p">)</span><span class="x"></span> |
| |
| <span class="x">The clock is </span><span class="p">$</span><span class="nv">clock</span><span class="x">.</span> |
| </pre></div> |
| |
| |
| <p>Which will result in the same output. As a final example, when you want to mix in 'static' strings with your references, you may need to use 'formal references' :</p> |
| <div class="codehilite"><pre><span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">size</span> <span class="o">=</span> <span class="s2">"Big"</span> <span class="p">)</span><span class="x"></span> |
| <span class="cp">#</span><span class="nf">set</span><span class="p">(</span> <span class="p">$</span><span class="nv">name</span> <span class="o">=</span> <span class="s2">"Ben"</span> <span class="p">)</span><span class="x"></span> |
| |
| <span class="cp">#</span><span class="nf">set</span><span class="p">($</span><span class="nv">clock</span> <span class="o">=</span> <span class="s2">"${size}Tall$name"</span> <span class="p">)</span><span class="x"></span> |
| |
| <span class="x">The clock is </span><span class="p">$</span><span class="nv">clock</span><span class="x">.</span> |
| </pre></div> |
| |
| |
| <p>Now the output is 'The clock is BigTallBen'. The formal notation is needed so the parser knows you mean to use the reference '$size' versus '$sizeTall' which it would if the '{}' weren't there.</p> |
| <h2 id="feedback">Feedback<a class="headerlink" href="#feedback" title="Permanent link">¶</a></h2> |
| <p>If you encounter any mistakes in this manual or have other feedback related to the Velocity User Guide, please email the <a href="mailto:dev@velocity.apache.org">Velocity developers list</a>. Thanks!</p></div></div> |
| <hr/> |
| <div id="copyright"> |
| Copyright © 2020 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/>Apache and the Apache feather logo are trademarks of The Apache Software Foundation. |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
