anchor.diff:  :lang: en
   :encoding: iso-8859-1
   
  -== What is the feature used for ==
  -
  -PmCommand is an interface to execute actions for e.g. buttons, links or menu entries.
  +== Purpose of the component ==
  +
  +PmCommand models support UI logic for view components triggering actions. E.g. buttons, links or menu entries.
   
   == Usage of PmCommand objects ==
   
  +=== Relevant classes and interfaces ===
  +
  +==== Core interfaces and classes ====
  +
  +* _PmCommand_ - external interface for views
  +* _PmCommandImpl_ - a basic command logic implementation
  +
  +==== Specialized command classes ====
  +
  +* _PmCommandDecorator_ - interface for command execution interceptors
  +* _PmCommandProxy_ - fix commands that may delegate requests to a registered executing command. +
  +  Example use case: A fix toolbars that delegating calls to actual context specific real commands.
  +
  +== PmCommand usage ==
  +
   In this chapter we will describe how a framework user can add a new command element. An example for that will be the usage of a button command element.  
   
   === Adding a new PmCommand ===
   
   To use a new command element you have to add the ui element (e.g. commandButton) into the xhtml file and corresponding PmCommand object into the related java implementation.
   
  -1. XHTML file:
  -[source]
  -<ui:define name="content">
  -	...
  -		<base:commandButton pm="#{pm.button}" />
  -	...
  -</ui:define>
  -
  -1. Java class:
  -[source]
  -public final PmCommand button = new PmCommandImpl(this) {
  -};
  -
  -=== Performing an action ===
  -
  -To implement the necessary actions to execute you just have to override the doItImpl method.
  -
  -[source]
  -@Override
  -protected void doItImpl() throws Exception {
  -};
  -
  -Example for a simple action:
  -
  -[source]
  -------------------------------------------------------------------------
  -@PmTitleCfg(title = "Save")
  -public final PmCommand add = new PmCommandImpl(this) {
  -
  -    @Override
  -    protected void doItImpl() throws Exception { // Perform an action
  -        Person person = new Person();
  -
  -        person.setFirstname(firstname.getValue());
  -        person.setLastname(lastname.getValue());
  -
  -        persons.add(person);
  -    }
  -};
  -------------------------------------------------------------------------
  -
  +1. Java code:
  +[source]
  +public final PmCommand cmdSave = new PmCommandImpl(this);
  +
  +1. View (e.g. JSF)
  +[source]
  +<pmtags:commandButton pm="#{pm.cmdSave}" />
  +
  +=== Defining an action ===
  +
  +To implement the necessary actions to execute you just have to override the _doItImpl()_ method.
  +
  +[source]
  +@Override
  +protected void doItImpl() {
  +  // ... some UI logic code
  +}
  +
  +
  +// OBO: Den Validierungsblock wrde ich weglassen. Die Doku sollte sich auf beforeDo und afterDo beschrnken.
  +// die validate() Methode ist m.E. durchaus ein Lschkandidat.
   === Validation of a PM area ===
   
   The validation of a command element is automatically called before executing the command. The default implementation of PMCommand 
  
positive.code: With the PmCommandCfg you have the possibility to change the default behaviour of the PmCommand object. This means that you can configure for example 
  the behaviour before or after executing the command.
  
  ==== BeforeDo ====
  
  The beforeDo paramter defines what should be done before executing the command logic, whereat the following actions are possible:
  
  * VALIDATE: This call validates the entered data of the containing PmDataInput objects (see Validation of a PM area [HIER LINK SETZEN!]). The doItImpl method of the command 
  will only be executed if the validation was successful.
  
negative.code: * GROUP: A pure organizational structure of commands.
  * SEPARATOR: A separator between command sections of a command list.
  
  // OBO: will be deprecated.
  ==== hideWhenNotEnabled ====
  
  * If true, the command should be hidden when not applicable. The default value is false.
  
  ==== clearCaches ====
  
  *  Defines the caches to clear within the element context of this command. The default value is an empty array, which means that there is nothing to clear.
  
  === Navigate to another view ===
  
  //OBO: HotLinkCommandPm is not available in pm4j. - I just detected it, and it's a candidate for removal. - A view adapter should do what's defined there.
  
  To navigate to another view you can use the HotLinkCommandPm. Here you have to override the getNaviLinkImpl to return a NaviLink object, 
  that contains the information about the target to navigate to. Optional it is also possible to add some parameters.
  
  [source]
  ------------------------------------------------------------------------
  public final PmCommand cmdNavigateToFixTarget = new PmCommandImpl(this, new NaviLinkImpl("/page/someDialog.iface"));
  
  public final PmCommand cmdNavigateToCalculatedTarget = new PmCommandImpl(this);
  
      @Override
      protected NaviLink getNaviLinkImpl() {
  		String page = someCondition() ? "targetPage1" : "targetPage2";
  		
          // Path to the requested component
          NaviLinkImpl naviLink = new NaviLinkImpl(page);
          
          naviLink.addParam("name", "value");
          // ... more parameter ...
          return naviLink;
      }
  };
  
  public final PmCommand cmdThatOnlySometimesNavigates = new PmCommandImpl(this);
  
      @Override
      protected void doItImpl() {
          // .. some logic
  		if (verySpecialCondition()) {
  		   setNaviLink(new NaviLinkImpl("specialConditionHandlingPage");
  		}
      }
  };
  
  ------------------------------------------------------------------------
  
  // OBO: should be moved to the Globe specific hotlink docu.
  
  You can read these parameter in the target object like this:
  
  