<?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.
-->
<!DOCTYPE document PUBLIC "-//MAKUMBA//DTD Documentation V2.0//EN" "document-v20-mak.dtd">
<document>
  <header>
    <title>Makumba Quick start</title>
  </header>
  <body>
    
    <section>
      <title>Introduction</title>
      <p>This guide will help you getting started with Makumba using the <a href="http://www.eclipse.org/">Eclipse</a> IDE. It explains the notion of Makumba
      Data Definitions, and shows you how to make a simple site where you can display and create data.</p>
      <p>We'll take the example of a company management site, where you can manage the employees,
        departments and projects of a company.</p>
    </section>
    
    <section id="download">
      <title>Download and Eclipse project setup</title>
        <p>First of all, <a href="/download.html">download</a> the Makumba template project in order to get an <a href="http://www.eclipse.org/webtools/">Eclipse WTP project</a> which you can use in order to start working with Makumba.</p>
        <p>You'll also need to download <a href="http://tomcat.apache.org/download-55.cgi">Apache
          Tomcat 5.5</a> and configure a WTP Server (in Eclipse, go to File -> New -> Other and
          choose "Server").</p>
      <p>Optionally, you can also download <a href="http://dev.mysql.com/downloads/mysql/5.1.html">MySQL</a> as a database engine. For this introduction however, the template project comes with the <a href="http://hsqldb.org/">HSQLDB</a> database engine, so you don't need to install anything in that regard.</p>
      <p>The project imported in Eclipse has the following structure:</p>
      <source>
<![CDATA[/src
    /dataDefinitions
/build
/WebContent
           /META-INF
           /WEB-INF
                   /lib
                   web.xml
           index.jsp]]></source>
      <p>This is the standard WTP project structure. The resulting web-application structure (according to the <a href="http://jcp.org/aboutJava/communityprocess/final/jsr154/index.html">Servlet Standard 2.4</a>) is as follows:</p>
      <source>
<![CDATA[/META-INF
/WEB-INF
        /lib
        /classes
                /dataDefinitions
        web.xml
index.jsp]]></source>
    </section>
    
    <section id="MDD">
      <title>Describing the data</title>
      <p>Makumba uses so-called Makumba Data Definitions (further described <a href="site:model">here</a>).</p>
      <p>MDDs are simple text files that contain the description of an entity, i.e. its fields but also validation rules and query functions. These files are kept in the <code>dataDefinitions</code> directory in the classpath of the web-application.</p>
      <p>Start by creating a new <code>company</code> package in the <code>src/dataDefinitions</code> directory and create the file <code>Employee.mdd</code> with the following content:</p>
      <source><![CDATA[name = char[200]
surname = char[200]
gender = int{"Male" = 10, "Female" = 20}
birthdate = date
salary = real

fullName() { name || (' ' || surname) }]]></source>
    </section>
    <p><em>name, surname, gender, birthdate and salary</em> are <strong>field definitions</strong>, while fullName() is a so-called <strong>query-function</strong></p>
    <note>Makumba automatically generates the database schema based on MDDs. If you modify a MDD, you will need to reload your webapp for the changes to be taken into account.</note>
    
    <section id="create">
      <title>Entering new data</title>
      <p>Let's make it possible to feed some data to our webapp.</p>
      <p>For this, let's create a page that contains a mak:newForm, which enables us to enter new data. Create the file <code>WebContent/employeeNew.jsp</code> with following content:</p>
      <source><![CDATA[<%@ taglib uri="http://www.makumba.org/presentation" prefix="mak" %>
<html>
<head>
<title>Create new employee record</title>
</head>
<body>

<mak:newForm type="company.Employee" method="post" action="index.jsp">
  <table>
    <tr>
      <th>Name</th>
      <td><mak:input field="name" /></td>
    </tr>
    <tr>
      <th>Surname</th>
      <td><mak:input field="surname" /></td>
    </tr>
    <tr>
      <th>Birthdate</th>
      <td><mak:input field="birthdate" /></td>
    </tr>
    <tr>
      <th>Salary</th>
      <td><mak:input field="salary" /></td>
    </tr>
    <tr>
      <td><input type="submit" value="Add"> <input type="reset" value="Cancel" onClick="javascript:back();"></td>
    </tr>
  </table>
</mak:newForm>

</body>
</html>]]>        
      </source>
      <p>This will generate the following form:</p>
      <p><img src="/images/employeeNew.png" alt="employeeNew.jsp"/></p>
      <p>When you submit the form, the data is directly saved into the database, without any additional effort. Let's explain a bit each of the elements:</p>
      <ul>
        <li>the <code>mak:newForm</code> tag generates the form for a given <strong>type</strong> (in our case, the type is <code>company.Employee</code>). The <strong>action</strong> attribute specifies the page to show after the form is submitted.</li>
        <li>the <code>mak:input</code> tags generate the inputs, depending on their type (for instance, the birthdate field is automatically shown as a date input). The <strong>field</strong> attribute corresponds to the field name in the MDD.</li>
      </ul>
    </section>
    
    
    <section id="viewing">
      <title>Displaying data</title>
      <p>Let's now see how to display data using the <code>mak:list</code> tag. For this we will edit the <code>WebContent/index.jsp</code> to display the list of all Employees:</p>
      <source><![CDATA[<%@ taglib uri="http://www.makumba.org/presentation" prefix="mak" %>
<html>
  <head>
    <title>Makumba template welcome page</title>
  </head>
  <body>
    
    <h1>List of employees</h1>
    <mak:list from="company.Employee e">
      <em><mak:value expr="e.fullName()" /></em> born on <mak:value expr="e.birthdate" /><br />
    </mak:list>
    
  </body>
</html>]]>
      </source>
      <p>This will generate the following output:</p>
      <p><img src="/images/employeeList.png" alt="index.jsp"/></p>
      <ul>
        <li>the <code>mak:list</code> tag generates a query. In our case, the query's from section is <code>employee.Employee e</code>.</li>
        <li>the <code>mak:input</code> tags represent the projections of the query. The <strong>expr</strong> attribute can contain a field, an MQL expression or a query function name.</li>
      </ul>
      <note><code>mak:list</code> tags can be nested, so as to display the content of sets.</note>
    </section>
    

    <section id="edit">
      <title>Modifying existing data</title>
      <fixme author="manu">editForm</fixme>
    </section>
    
    <section id="delete">
      <title>Deleting data</title>
      <fixme author="manu">deleteForm</fixme>
    </section>
    
    
    
  </body>
</document>
