Edit Introduction
Entity Windows are just a Window frame around the controls you design for your entities, adding some necessary tools around it, like buttons (Ok, Cancel, Close, Save, Refresh...) an
ErrorSummary control and a
LeftNavigationPanel.
This way, we factor the task of showing an entity in windows into two different problems:
- A content control, written by the user, that specifies how the entity has to be shown and edited in a more declarative fashion, independently from the action that is taken.
- One or many different entity windows that surround the control and contextualize as part of some user interface process, like editing an entity, a sub-entity, open it as read-only, or editing all the entities of a type at the same time.
Entity Windows are the glue that mixes the controls defined for your entities in
EntitySettings, and the actions received by Navigation class.
In that sense, they are transparent for the developer, not something the you should use on a day-to-day basis.
Use Navigator actions instead!There are just two reasons you could be interested in Entity Windows:
- You want to use it manually because NavigationManager does something wrong setting-up the window.
- You don't like the current Entity Windows and you want to build your own (and override NavigationManager).
You're still here, huh? Ok, let's get the point.
Currently there are two different Entity Windows:
Edit NormalWindow
NormalWindow is meant to show a single entity and, if IsReadOnly is false, edit it. There are just two new properties:
public partial class NormalWindow
{
public Control MainControl {...}
public ViewButton Buttons {...}
}
- MainControl: The Content controls that will show the entity.
- Buttons: ViewButtons enumeration, as defined in Navigator, that controls which buttons will be visible and which controls won't. OkCancel is usually used when editing sub-entities in an entity graph, while SaveClose is used when editing independent IdentifiableEntities (entity graph roots).
There are many possible buttons at the bottom of a NormalWindow:
- Ok: Closes the window with DialogResult = true. Visible when Buttons == OkCancel
- Cancel: Closes the window with DialogResult = false. Visible when Buttons == OkCancel || Buttons == OkCancelSaving
- Save: Saves the entity asynchronously if there are changes and the FullIntegrityCheck do not fail. Visible when Buttons == SaveClose
- Close: Closes the window without setting DialogResult. Visible when Buttons == SaveClose
- OkSaving: Saves the entity asynchronously if FullIntegrityCheck does not fail, then closes the window with DialogResult = true. Visually indistinguishable from Ok button, is used for attached entities like Notes Notes. Visible when Buttons == OkCancelSaving
- Reload: Buttons that retrieve from the server a new version of the entity, loosing your changes. Enabled only if the Entity is an IdentifiableEntity and has ID.
Edit Example
Let's show our first ProjectDN (Id 1) in the control that we have built for it (Project) using OkCancel as the buttons. OkCancel is usually used on ShowDialog scenarios (modal show) on sub-entities.
NormalWindow nw = new NormalWindow
{
MainControl = new Project(),
DataContext = Server.Retrieve<ProjectDN>(1),
Buttons = ViewButtons.OkCancel
};
nw.ShowDialog();
The end result is this (blue region is the Project control, not the NormalWindow:
Now let's pretend that we want to edit the ProjectDN as an independent entity, using SaveClose instead and doing a normal Show() operation instead:
NormalWindow nw = new NormalWindow
{
MainControl = new Project(),
DataContext = Server.Retrieve<ProjectDN>(1),
Buttons = ViewButtons.SaveClose
};
nw.Show();
With this result:
Edit AdminWindow
AdminWindow, on the other side, is meant to deal with every entity of the same type at the same time. It shows a Master-Detail window where your custom controls are shown as the detail panel.
The exposed API is even simpler than NormalWindow:
public partial class AdminWindow
{
public Control MainControl {...}
public AdminWindow()
public AdminWindow(Type type)
}
- MainControl: The Actual control that will be placed in the detail panel.
- AdminWindows constructor: There are two constructor overloads, the parameterless one is used for designer support, while you should use the one that takes a type as a parameter, providing the type of entities you want to Admin (implements IdentifiableEntity).
AdminWindows always has these three buttons:
- Save: Saves all the entities at the same time asynchronously if there are changes and the FullIntegrityCheck does not fail.
- Close: Closes the window without setting DialogResult.
- Reload: Buttons that retrieve from the server a new version of the entity. Enabled only if the Entity is an IdentifiableEntity and has ID.
Edit Example
Just with this simple code:
AdminWindow aw = new AdminWindow(typeof(ProjectDN))
{
MainControl = new Project(),
};
aw.Show();
Note that you don't have to retrieve the entity manually as we do in NormalWindow, instead AdminWindow is responsible for retrieving the entities given the provided entity Type.
Here is the end result:
