docs/asciidoc/developer-manual.adoc

////
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.
////
= Apache OFBiz Developer Manual
The Apache OFBiz Project
:imagesdir: ./images
ifdef::backend-pdf[]
:title-logo-image: image::OFBiz-Logo.svg[Apache OFBiz Logo, pdfwidth=4.25in, align=center]
:source-highlighter: rouge
endif::[]

image::https://img.shields.io/badge/License-Apache%202.0-blue.svg[link="http://www.apache.org/licenses/LICENSE-2.0"]

== Introduction

Welcome to the Apache OFBiz developer manual. This manual provides information
to help with customizing and developing OFBiz. If you are new to OFBiz and
interested in learning how to use it, you may want to start with the "Apache
OFBiz User Manual".

OFBiz is a large system composed of multiple subsystems. This manual attempts
to introduce the overall architecture and high level concepts, followed by a
detailed description of each subsystem. In addition, the manual will cover
topics necessary for developers including the development environment, APIs,
deployment, security, and so on.

=== Main systems

OFBiz at its core is a collection of systems:

- A web server (Apache Tomcat)
- A web MVC framework for routing and handling requests.
- An entity engine to define, load and manipulate data.
- A service engine to define and control business logic.
- A widget system to draw and interact with a user interface.

On top of the above mentioned core systems, OFBiz provides:

- A data model shared across most businesses defining things like orders,
  invoices, general ledgers, customers and so on.
- A library of services that operate on the above mentioned data model such as
  "createBillingAccount" or "updateInvoice" and so on.
- A collection of applications that provide a user interface to allow users to
  interact with the system. These applications usually operate on the existing
  data model and service library. Examples include the "Accounting Manager" and
  "Order Manager".
- A collection of optional applications called "plugins" that extend basic
  functionality and is the main way to add custom logic to OFBiz.

=== Components

The basic unit in OFBiz is called "component". A component is at a minimum a
folder with a file inside of it called "ofbiz-component.xml"

Every application in OFBiz is a component. For example, the order manager is a
component, the accounting manager is also a component, and so on.

By convention, OFBiz components have the following main directory structure:

[source]
--
component-name-here/
├── config/              - Properties and translation labels (i18n)
├── data/                - XML data to load into the database
├── entitydef/           - Defined database entities
├── minilang/            - A collection of scripts written in minilang (deprecated)
├── ofbiz-component.xml  - The OFBiz main component configuration file
├── servicedef           - Defined services.
├── src/
    ├── docs/            - component documentation source
    └── main/groovy/     - A collection of scripts written in Groovy
    └── main/java/       - java source code
    └── test/groovy/     - A collection of scripts written in Groovy
    └── test/java/       - java unit-tests
├── testdef              - Defined integration-tests
├── webapp               - One or more Java webapps including the control servlet
└── widget               - Screens, forms, menus and other widgets
--

It is apparent from the above directory structure that each OFBiz component is
in fact a full application as it contains entities, data, services, user
interface, routing, tests, and business logic.

Both core OFBiz applications as well as plugins are nothing more than components.
The only difference is that core applications reside in the "applications" folder
whereas plugins reside in the "plugins" folder; also OFBiz does not ship with
plugins by default.

=== Example workflow

Many basic concepts were explained so far. An example would help in putting
all of these concepts together to understand the bigger picture. Let us take
an example where a user opens a web browser and enters a certain URL and hits
the enter key. What happens? It turns out answering this question is not quite
simple because lots of things occur the moment the user hits "enter".

To try to explain what happens, take a look at the below diagram. Do not worry
if it is not fully understandable, we will go through most of it in our example.

image::ofbiz-architecture.png[]

==== User enters URL

In the first step in our example, the user enters the following URL:

https://localhost:8443/accounting/control/findInvoices

If we break down this URL, we identify the following parts:

- localhost: Name of the server in which OFBiz is running
- 8443: Default https port for OFBiz
- accounting: web application name. A web application is something
  which is defined _inside_ a component
- control: Tells OFBiz to transfer routing to the control servlet
- findInvoices: request name inside the control servlet

==== Control servlet takes over

The Java Servlet Container (tomcat) re-routes incoming requests through web.xml
to a special OFBiz servlet called the control servlet. The control servlet for
each OFBiz component is defined in controller.xml under the webapp folder.

The main configuration for routing happens in controller.xml. The purpose of
this file is to map requests to responses.

===== Request Map

A request in the control servlet might contain the following information:

- Define communication protocol (http or https) as well as whether
  authentication is required.
- Fire up an event which could be either a piece of code (like a script) or a
  service.
- Define a response to the request. A response could either be another request
  or a view map.

So in this example, the findInvoices request is mapped to a findInvoices view.

===== View Map

A view map maps a view name to a certain view-type and a certain location.

View types can be one of:

- screen: A screen widget which translates to normal HTML.
- screenfop: A PDF screen designed with Apache FOP based constructs.
- screencsv: A comma separated value output report.
- screenxml: An XML document.
- simple-content; A special MIME content type (like binary files).
- ftl: An HTML document generated directly from a FreeMarker template.
- screenxls: An Excel spreadsheet.

In the findInvoices example, the view-map type is a normal screen which is
mapped to the screen:
component://accounting/widget/InvoiceScreens.xml#FindInvoices

==== Widget rendered

Once the screen location is identified and retrieved from the previous step,
the OFBiz widget system starts to translate the XML definition of the screen
to actual HTML output.

A screen is a collection of many different things and can include:

- Other screens
- Decorator screens
- Conditional logic for hiding / showing parts of the screen
- data preparation directives in the <action> tag
- Forms
- Menus
- Trees
- Platform specific code (like FreeMarker for HTML output)
- Others (portals, images labels etc ...)

Continuing the example, the FindInvoices screen contains many details including
two forms. One form is for entering invoice search fields and the other form
displays search results.

include::docs/asciidoc/_include/OFBizDocumentationSystem.adoc[leveloffset=+2]

== Web Framework

include::framework/webapp/src/docs/asciidoc/webapp.adoc[leveloffset=+1]

=== Control Servlet

==== Requests

==== Views

include::framework/entity/src/docs/asciidoc/entity-engine.adoc[leveloffset=+1]

=== Entities

==== Standard Entities

==== View Entities

==== Extended Entities

==== Dynamic View Entities

=== XML Data

include::framework/datafile/src/docs/asciidoc/datafiles.adoc[leveloffset=+2]

=== Entity engine configuration

=== Supported databases

include::applications/datamodel/DATAMODEL_CHANGES.adoc[leveloffset=+2]

== Service Engine
A description of the service engine can be found at the
https://cwiki.apache.org/confluence/display/OFBIZ/Service+Engine+Guide[OFBiz wiki Service Engine Guide]

=== Declaration and Implementation

=== Supported languages

=== Transaction management

=== Web services

== Widget System

=== Screen Widget

==== Decoration Pattern

=== Form Widget

=== Menu Widget

=== Tree Widget

=== Portal Widget

=== Platform Specific Code

include::themes/docs/themes.adoc[leveloffset=+2]

== Core APIs

== Development environment

=== Setup your environment

==== Java SE

==== IDE

===== Eclipse

===== Intellij Idea

==== Database

=== Web tools
The Webtools application is the UI-gateway to all the framework functions.

include::framework/webtools/src/docs/asciidoc/_include/webtools-main.adoc[leveloffset=+3]

include::framework/minilang/src/docs/asciidoc/minilang-to-groovy-manual.adoc[leveloffset=+1]

== Testing

include::framework/testtools/src/docs/asciidoc/unit-tests.adoc[leveloffset=+2]

=== Integration Tests

== Deployment

For a core configuration guide check
https://cwiki.apache.org/confluence/display/OFBIZ/Framework+Configuration+Guide[the OFBiz configuration Guide]
 (some points are not up to date).


include::framework/base/src/docs/asciidoc/email.adoc[leveloffset=+2]

include::framework/security/src/docs/asciidoc/security.adoc[leveloffset=+1]

== Appendices

// Developers Plugins

include::plugins/docs/asciidoc/plugins-developer-manual.adoc[leveloffset=+1]