Most pages in OGo are triggered using an "activation" system.
TODO: write much more ...
The activation system uses a combination of a MIME type and a "verb"
to locate and trigger web components (eg viewers, editors). The basic
idea is similiar to that of the Java activation framework though the
details differ a lot.
Example activation triples (ID, MIME type, verb, component):
"10000" - eo/person - view - SkyPersonViewer
"10000" - eo-gid/person - view - SkyPersonViewer
Verbs
view
edit
mailview
htmlMail
textMail
link-inline-preview
...
Activation in Code
Lets take a component action triggered by some link:
- (id)viewObject {
return [self activateObject:[self object] withVerb:@"view"];
}
This will place the object returned by "[self object]" in the transfer pasteboard
and trigger the activation system with the "view" verb. The activation system
will instantiate the proper components which is returned as the result page of
the component action and therefore will be displayed as the new current page.
Activate using a URL
Activation of a page can also be triggered using a URL:
http://[yourhost]/OpenGroupware/x/activate?oid=10000&verb=view
10000 is the object id of the root account, so the above URL should work
for you out of the box. The verb parameter can be omitted and defaults
to "view".
Note: the direct action activates based on the object primary key (or
more exactly based on a so called EOKeyGlobalID), which is represented
as "eo-gid/[entity]".
A lot of components are not bound to the primary-key but only to the
"live" object MIME type ("eo/[entity]"). Eg you currently cannot activate
the person editor using "activate?oid=10000&verb=edit".
Writing a component which can be activated ...
Subclasses of LSWEditorPage and LSWViewerPage already provide
some basic activation support, that is, they fill the object ivar of
the page in question.
What happens if -activateObject:withVerb: is invoked?:
- check whether the object passed in is valid at all
- transfer the object to the transfer pasteboard in the session
- call -transferObject:owner:(nil) on the session
- call executePasteboardCommand with the verb
- gets the sessions transfer pasteboard object
- if its the "view" verb, check whether the last page is showing
the same object (and if so, return that)
- call the session -instantiateComponentForCommand:type:object: method to produce a WOComponent
- locate the bundle providing the component using the
NGBundleManager (LSWCommands key)
- use -pageWithName: to instantiate page
- activate the component by doing one of those:
- -activateObject:verb:type: (can replace the component)
- -prepareForActivationCommand:type:object: (deprecated)
- -prepareForActivationCommand:type: (deprecated)
- -prepareForActivationCommand:type:configuration: (deprecated)
- if the components conform to the OGoContentPage protocol,
put it on the navigation stack
- return the active page
So, unless you are using an LSWEditorPage, you probably want to
implement the -activateObject:verb:type: method in your
page component to fill your object with the information you need.
Notably you can return a different object and therefore use it to
dispatch the activation to another component. For example this is
used in the project application if a folder is activated (a folder is
technically a regular document, so the document viewer will forward
activation to the projectviewer).
LSWEditorPage
LSWEditorPage splits up the activation into 'new' or 'edit' mode and
triggers different setup methods which you may or may not want to
override:
- (BOOL)prepareForNewCommand:(NSString *)_command
type:(NGMimeType *)_type
configuration:(NSDictionary *)_cmdCfg;
- (BOOL)prepareForEditCommand:(NSString *)_command
type:(NGMimeType *)_type
configuration:(NSDictionary *)_cmdCfg;
Prior edit activation, it also makes a snapshot of the object being
edited based on the EOEntity of the object.