| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| 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. |
| --> |
| <preface conformance="docgen" xml:id="preface" |
| xmlns="http://docbook.org/ns/docbook" |
| xmlns:xlink="http://www.w3.org/1999/xlink" |
| xmlns:ns5="http://www.w3.org/2000/svg" |
| xmlns:ns4="http://www.w3.org/1998/Math/MathML" |
| xmlns:ns3="http://www.w3.org/1999/xhtml" |
| xmlns:ns="http://docbook.org/ns/docbook"> |
| <title>Preface</title> |
| |
| <section> |
| <title>What is FreeMarker?</title> |
| |
| <para>FreeMarker is a <emphasis>template engine</emphasis>: a generic |
| tool to generate text output (anything from HTML to autogenerated source |
| code) based on templates. It's a Java package, a class library for Java |
| programmers. It's not an application for end-users in itself, but |
| something that programmers can embed into their products.</para> |
| |
| <para>FreeMarker is designed to be practical for the generation of |
| <emphasis>HTML Web pages</emphasis>, particularly by servlet-based |
| applications following the <link linkend="gloss.MVC">MVC (Model View |
| Controller) pattern</link>. The idea behind using the MVC pattern for |
| dynamic Web pages is that you separate the designers (HTML authors) from |
| the programmers. Everybody works on what they are good at. Designers can |
| change the appearance of a page without programmers having to change or |
| recompile code, because the application logic (Java programs) and page |
| design (FreeMarker templates) are separated. Templates do not become |
| polluted with complex program fragments. This separation is useful even |
| for projects where the programmer and the HTML page author is the same |
| person, since it helps to keep the application clear and easily |
| maintainable.</para> |
| |
| <para>Although FreeMarker has some programming capabilities, it is |
| <emphasis>not</emphasis> a full-blown programming language like PHP. |
| Instead, Java programs prepare the data to be displayed (like issue SQL |
| queries), and FreeMarker just generates textual pages that display the |
| prepared data using templates.</para> |
| |
| <mediaobject> |
| <imageobject> |
| <imagedata fileref="figures/overview.png"></imagedata> |
| </imageobject> |
| </mediaobject> |
| |
| <para>FreeMarker is <emphasis>not</emphasis> a Web application |
| framework. It is suitable as a component in a Web application framework, |
| but the FreeMarker engine itself knows nothing about HTTP or servlets. |
| It simply generates text. As such, it is perfectly usable in non-web |
| application environments as well. Note, however, that we provide |
| out-of-the-box solutions for using FreeMarker as the view component of |
| Model 2 frameworks such as Struts.</para> |
| |
| <para>FreeMarker is <link |
| xlink:href="http://www.fsf.org/philosophy/free-sw.html">Free</link>, |
| released under a BSD-style license. It is <link |
| xlink:href="http://www.opensource.org/">OSI Certified Open Source |
| Software</link>. OSI Certified is a certification mark of the Open |
| Source Initiative.</para> |
| </section> |
| |
| <section> |
| <title>What should I read?</title> |
| |
| <para>If you are a ...</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>designer, then you should read the <xref linkend="dgui" /> and |
| then you can look into the <xref linkend="ref" /> on an as-needed |
| basis for more specific details.</para> |
| </listitem> |
| |
| <listitem> |
| <para>programmer, then you should read the <xref linkend="dgui" /> |
| guide first, then the <xref linkend="pgui" /> and then you can look |
| into the <xref linkend="ref" /> on an as-needed basis for more |
| specific details.</para> |
| </listitem> |
| </itemizedlist> |
| </section> |
| |
| <section> |
| <title>Document conventions</title> |
| |
| <para>Variable names, template fragments, Java class names, etc. are |
| written like this: <literal>foo</literal>.</para> |
| |
| <para>If something should be replaced with a concrete value then it is |
| written in italics, as follows: <literal>Hello |
| <replaceable>yourName</replaceable>!</literal>.</para> |
| |
| <para>Template examples are written like this:</para> |
| |
| <programlisting role="template">something</programlisting> |
| |
| <para>Data-model examples are written like this:</para> |
| |
| <programlisting role="dataModel">something</programlisting> |
| |
| <para>Output examples are written like this:</para> |
| |
| <programlisting role="output">something</programlisting> |
| |
| <para>Program examples are written like this:</para> |
| |
| <programlisting role="unspecified">something</programlisting> |
| |
| <remark>This paragraph is for the editors, and not visible for the |
| public</remark> |
| |
| <para>In chapters <remark>this section is for the editors |
| too</remark>written for both designers and programmers fragments |
| addressed to programmers are written like this: <phrase |
| role="forProgrammers">This is for programmers only.</phrase></para> |
| |
| <para>New terms are emphasized like this: <emphasis role="term">some new |
| term</emphasis></para> |
| </section> |
| |
| <section> |
| <title>Contact</title> |
| |
| <indexterm> |
| <primary>help</primary> |
| </indexterm> |
| |
| <indexterm> |
| <primary>homepage</primary> |
| </indexterm> |
| |
| <indexterm> |
| <primary>download</primary> |
| </indexterm> |
| |
| <indexterm> |
| <primary>contact</primary> |
| </indexterm> |
| |
| <para>For the latest version of FreeMarker and to subscribe to the |
| <emphasis>mailing lists</emphasis> visit the FreeMarker homepage: <olink |
| targetdoc="homepage"><phrase role="homepage"></phrase></olink></para> |
| |
| <mediaobject xml:id="test_target"> |
| <imageobject> |
| <imagedata fileref="bat.jpg"></imagedata> |
| </imageobject> |
| </mediaobject> |
| |
| <para>If you <emphasis>need help</emphasis> or you have |
| <emphasis>suggestions</emphasis>, use the mailing lists (mail archives |
| can be searched without subscription) or the Web based forums. If you |
| want to <emphasis>report a bug</emphasis>, use the Web based bug |
| tracker, or the mailing lists. To find all of these visit <olink |
| targetdoc="homepage"><phrase role="homepage"></phrase></olink>. Also, |
| note that we have a <link linkend="app_faq">FAQ</link> and <link |
| linkend="alphaidx">index</link>; use them.</para> |
| </section> |
| |
| <section> |
| <title>About this document</title> |
| |
| <para>If you find <emphasis>any mistakes</emphasis> (including |
| <emphasis>grammatical mistakes</emphasis>, <emphasis>typos</emphasis>, |
| typographical mistakes) or you find something <emphasis>misleading or |
| confusing</emphasis> in the documentation, or you have other |
| suggestions, please let me know! Email: ddekany at |
| users.sourceforge.net</para> |
| </section> |
| </preface> |