svn commit: r1827911 - in /ofbiz/ofbiz-framework/trunk/docs/asciidoc: developer-manual.adoc images/ofbiz-architecture.png

[Taher Alkhateeb]

Author: taher
Date: Wed Mar 28 10:49:06 2018
New Revision: 1827911

URL: http://svn.apache.org/viewvc?rev=1827911&view=rev
Log:
Implemented: added initial skeleton and some content to developer manual
(OFBIZ-10285)

Provide the following to the developer manual

- an initial draft skeleton of the topics to be covered
- add an introduction
- add an example workflow with corresponding diagram

This is still very much a work in progress. Modifications, improvements and
comments are very welcomed.

Added:
    ofbiz/ofbiz-framework/trunk/docs/asciidoc/images/ofbiz-architecture.png   (with props)
Modified:
    ofbiz/ofbiz-framework/trunk/docs/asciidoc/developer-manual.adoc

Modified: ofbiz/ofbiz-framework/trunk/docs/asciidoc/developer-manual.adoc
URL: http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/docs/asciidoc/developer-manual.adoc?rev=1827911&r1=1827910&r2=1827911&view=diff
==============================================================================
--- ofbiz/ofbiz-framework/trunk/docs/asciidoc/developer-manual.adoc (original)
+++ ofbiz/ofbiz-framework/trunk/docs/asciidoc/developer-manual.adoc Wed Mar 28 10:49:06 2018
@@ -30,6 +30,238 @@ ifdef::backend-pdf[]
 :source-highlighter: rouge
 endif::[]
 
-== Intro
+== Introduction
 
-content goes here
+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
+├── groovyScripts/       - A collection of scripts written in Groovy
+├── 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/java/       - java source code
+    â””── 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.
+
+== Web Framework
+
+=== Web Apps
+
+=== Control Servlet
+
+==== Requests
+
+==== Views
+
+== Entity Engine
+
+=== Entities
+
+==== Standard Entities
+
+==== View Entities
+
+==== Extended Entities
+
+==== Dynamic View Entities
+
+=== XML Data
+
+=== Entity engine configuration
+
+=== Supported databases
+
+== Service Engine
+
+=== 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
+
+== Core APIs
+
+== Development environment
+
+=== Web tools
+
+== Testing
+
+=== Unit Tests
+
+=== Integration Tests
+
+== Deployment
+
+== Security
+
+== Appendices

Added: ofbiz/ofbiz-framework/trunk/docs/asciidoc/images/ofbiz-architecture.png
URL: http://svn.apache.org/viewvc/ofbiz/ofbiz-framework/trunk/docs/asciidoc/images/ofbiz-architecture.png?rev=1827911&view=auto
==============================================================================
Binary file - no diff available.

Propchange: ofbiz/ofbiz-framework/trunk/docs/asciidoc/images/ofbiz-architecture.png
------------------------------------------------------------------------------
    svn:keywords = Date Rev Author URL Id

Propchange: ofbiz/ofbiz-framework/trunk/docs/asciidoc/images/ofbiz-architecture.png
------------------------------------------------------------------------------
    svn:mime-type = image/png