You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ofbiz.apache.org by ta...@apache.org on 2018/03/28 10:49:06 UTC
svn commit: r1827911 - in /ofbiz/ofbiz-framework/trunk/docs/asciidoc:
developer-manual.adoc images/ofbiz-architecture.png
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