-
Notifications
You must be signed in to change notification settings - Fork 23
Patterns
An Ampere application consists of modules, states, views and transitions.
A good example of an Ampere module would be an address book. It can be executed as standalone application but can additionally integrated as part of a Mail application.
A module encapsulates
- common application logic
- shared data and resources
- state definitions
- global transitions like Undo / Redo
An Ampere application consists of at least a single module. A module is fairly comparable with an Android Activity.
Modules
- can be shared with other modules
- can be reused in other applications
- can be nested within other modules
- are configurable
A Module gets created by providing a function encapsulating the module definition code. The Module can return a Promise tracking its loading state.
A module is expected to be ready if
- the returned Promise was successful
- all of its States were successful initialized
- all module owned Transitions were successful initialized
Think about a state as the current screen of a application including the logic for all operations possible in this screen.
A state encapsulates
- the logic for a specific screen
- transitions to other states
- views representing the user interface for this screen
A State gets created by providing a function encapsulating the state definition code. The State can return a Promise tracking its loading state.
A state is expected to be ready if
- the returned Promise was successful
- all of its Views and Transitions were successful initialized
A state has at least a single view applied. If not configured, at default view will be created.
"If a state represents a screen, why do I need a view ?". Because the screen should look different for various cases of the same application state. Think about the Print view vs. regular view for example.
Views
- are responsible for providing rendering informations like a template for a state.
A view is expected to be ready if all of its related ressources (templates, images, etc.) are loaded and ready to use.
The transition is the coded way to move from a State to another one. Transitions are mostly triggered by user interactions or asynchronous operations like Ajax calls.
A Transition acts as a factory method : whenever a transistion gets executed it is assumed to return a fresh new Redo Command encapsulating the real operation (including data) to be done. It is even allowed to return a Promise transporting the Redo Command as the success result.
If no function or Promise is returned the transition will not be executed.
The Redo Command can return
- a Undo function encapsulating the Undo Command
- a Promise transporting the Undo Command as the success result or nothing to signal undoing is impossible
- value evaluating to false to signal that undoing this operation is not possible
The Undo Command is expected to work exactly the same as the Redo Command but returns the Redo command in the same manner.
A Transition has a enabled property which can be set to a function reflecting the enablement of a transition. If the function returns a value evaluating to true, the transition is assumend to be enabled, otherwise ist disabled.
This property is also be used when rendering a transition. Example use case : If a transition is rendered as a button and enabled returns false, the button will be disabled.
Transition property active can be used to signal that a transition is currently on going. It can be set to a function reflecting the activity of a transition. If the function returns a value evaluating to true, the transition is assumend to be active, otherwise it's disabled.
active doesnt signal the transition is in progress. It tells Ampere that a special user specific scenario of the result of the transitions redo command is active. active will only affect the rendered representation of a transition reflecting that this transition is active.
Example use case : A state is onfigured to have different views and you have multiple transitions to that different transition/view associations. active can now be used to render which state/view pair is currently active.
All Ampere core types (Module, State, Transition etc.) provide an Options interface. By using these interface you can separate logic and optional informations like ui related decorations.
Options acts as a ordinary map keeping optional data uniquely identified by keys.
As detailed above almost everything in Ampere is modeled using Promises.
Ampere supports also progress for a Promise which enables you to code a transition and signal Ampere the progress of the operation. Example : Your operation uploads something large and you want to show the progress of the upload. This is done using the progress interface of the Promise borrowed byjQuery Deferred. This object declares function notify which can be called to signal progress to Ampere.
Ampere handles progress by disabling user interaction and rendering the progress information to the user interface.