= General Overview =
These are the base classes that of which the MVC consists: [[BR]]
MVC is based upon the MVC pattern.[[BR]]
 '''Not that the tree kinds of Frames mentioned below ARE NOT the only frames Sophie2.0 will have. Though for the time being these are the Frames it has.'''
== Model ==
Model represents this part of the application that is responsible for the persistence and the things that are later displayed by the View.
Our Model (a single instance of it) consists of: [[BR]]
 * [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/model/app/App.java@112 App]
 * the App has Books
 * a [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/model/book/Book.java@112 Book] has Pages
 * a [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/model/page/Page.java@112 Page] contains Frames
 * [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/model/frame/Frame.java@112 Frame]s on the other hand a various by type and functionality:
  * [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/model/frame/text/TextFrame.java@112 TextFrame]s
  * [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/model/frame/image/ImageFrame.java@112 ImageFrame]s
  * [source:/trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/model/frame/media/MediaFrame.java@112 MediaFrame]s
  * Other types, not defined yet.
Diagram: [[BR]] [[Image(source:/trunk/sophie2-platform/doc/uml-design-diagrams/SimpleModelHierarchy.png)]]
 About the diagram:
 * an App contains Books
 * a Book contains Pages
 * a Page contains Frames
 * Frames are divided into several types which extend the functionalities of a Frame. These include !TextFrame, !ImageFrame, !MediaFrame and other not defined yet.

== View ==
The View in Sophie2.0 is the visual representation of what is in the Model. Every change in the Model affects the View and this is done '''automatically''' via the properties library.
Our View contains:
 * [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/view/app/AppView.java@203 AppView]
 * The  [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/view/app/AppView.java@203 AppView] has !BookViews
 * a [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/view/book/BookView.java@148 BookView] contains !PageViews
 * a [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/view/page/PageView.java@112 PageView] has various [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/view/frame/FrameView.java@112 FrameView]s corresponding to the Frames in the model: [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/view/frame/TextFrameView.java@112 TextFrameView], [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/view/frame/ImageFrameView.java@112 ImageFrameView], [source:trunk/sophie2-platform/modules/org.sophie2.messy/src/main/java/org/sophie2/messy/view/frame/MediaFrameView.java@112 MediaFrameView] up to now.
Diagram of the View part of the MVC is not needed since every View is a corresponding part of the model. A diagram for the Views will be more or less like the diagram of the model. For example every !FrameView is a visual representation of a Frame. A Book has a corresponding !BookView etc. [[BR]]

== Controller ==

The Controller part is represented by the Logics. We have !AppLogic, !BookLogic, !PageLogic and !FrameLogic. At this point we have only a !TextFrameLogic instead of several !FrameLogics(for Text, Image, Media and other) but Logics will be provided later. While one can create instances of the model and view (Books, Pages, Frames, !AppViews, !BookViews, !PageViews etc.), the Logics are singletons which means that they have only one instance which is used to control the instances of the model. The only instance of a Logic is the one invoked by the View. This means that if we have multiple !BookViews, we use only one !BookLogic to apply changes to the Books. Logics are entirely and only used to control the model and change it. They '''do not have state'''. By convention, the names of the methods which control the Model should start with "user" and continue with an explanation of what the method changes or does. Example: (method which is part of the !PageLogic and serves to create a Frame on a certain point on the screen)[[BR]]
{{{
public void userDropFrame(PageView pageView, ImmPoint location, final FrameKind kind) {
		if (!pageView.isInReaderMode()) {
			insertFrame(pageView, new ImmRect(location, FrameStyle.DEFAULT_FRAME_SIZE), kind);
		}
	}
}}}

Since the Logics are the part of Sophie where the control takes place below is provided a detailed digram of the Logics which contains the methods used to apply changes.

Diagram: [source:/trunk/sophie2-platform/doc/uml-design-diagrams/Logics.png Logics Heirarchy]

== MVC ==
The Model-Viewer-Controlled in Sophie2.0 can be noticed in four levels (or layers) up to now and these are: App, Book, Page and Frame including the several types of frames. Here is a detailed diagram of the MVC. One can think of it as a tree containing layers of MVCs. [[BR]]

[[Image(source:/trunk/sophie2-platform/doc/uml-design-diagrams/MVC-diagram-detailed.png)]]. [[BR]]

Although changes are supposed to happen on one layer only (as described in the diagram), sometimes a user interaction may appear in the App which may result in invoking a !FrameLogic. This is a typical scenario if a new frame is created.

Next is a general picture of the MVC on one level only. It is important to notice that:
 * the View is controlled by the user. The corresponding user method is invoked in the Logic and the model is changed.
 * Every change in the model affects the corresponding View. (this is done automatically by the pro lib).
 * the whole flow of information goes in one way ONLY.

[[Image(source:/trunk/sophie2-platform/doc/uml-design-diagrams/MVC-diagram.png)]] 

= General Rules =
 * View is '''automatically''' updated.
 * Model is modified '''only''' by the Logic. If model is to be changed you '''should''':
  * Use the '''implemented''' methods int he corresponding Logic to do this.
  * Create methods to serve your needs if '''there aren't''' such. These methods:
   * should be '''public methods''' that are invoked by the View and '''should'''
    * begin with user....
    * be public....
   * may use '''helper''' methods to provide the functionality needed. The helper methods '''should not''':
     * be public. They '''should be protected'''. Otherwise the application will not run.
     * begin with '''user'''.

= Additional things =
The MVC in Sophie2.0 is divided into two parts:
 * The library part.
 * A concrete implementation.

== Library Part ==
The library part consists of the base classes of the MVC. For the time being we have two base classes of the MVC and these are the [source:/trunk/sophie2-platform/modules/org.sophie2.core/src/main/java/org/sophie2/core/mvc/logic/Logic.java@291 Logic] and the [source:/trunk/sophie2-platform/modules/org.sophie2.core/src/main/java/org/sophie2/core/mvc/logic/LogicHelper.java@291 LogicHelper]. Later we should provide more classes that can be part of the Model and the View. Library part is not tightly connected with Sophie2.0 and can be used elsewhere as well. Different tools that we use will also be included in the library part. These include things like Helpers, Monitoring utilities etc.
 * all the things connected with the library part should go in '''/sophie2-platform/modules/org.sophie2.core/src/main/java/org/sophie2/core/mvc/'''
 * define sub-packages if needed.
== Implementation ==
The implementation part include the concrete implementation of parts of the MVC: Logic, Model, View. Since all the model and View parts are now typical implementations (!TextFrame, !PageView etc.) they are NOT part of the core module but rather parts of different modules.

= Comments =

* Please note, that the classes related to frames on this diagram, are not correct according to the [wiki:UNPLANNED_BASE_MODEL_FRAME_CONTENT_R0] (or probably revisions). So get this information with care. --milo@2008-11-26