Navigation framework

Document providers lifecycle

The form providers’ life cycle is almost the same for most of the forms types.

Provider building

When loading a form, the assigned provider class is instantiated and receives three parameters:

  • INavigateContext : navigation context enabling to get sent parameters back;
  • AbstractDocument : the document in which the fields values are maintained;
  • And the template class of the selected screen type (CtlAbstractForm, CtlAbstractWizard, CtlAbstractSheet, CtlAbstractDocument).

    Example of a form provider constructor 

    public DemoFormProvider( INavigateContext context, AbstractDocument document, CtlAbstractForm abstractForm ) 
{ 
    super( context, document, abstractForm ); 
}

Data supplying

Before the form is loaded, a first method is called to allow the developer to fill-in the form fields. The called method is prepareData(). Then, the load() method is called for each built form field (defined in the XML definition document). From that point the « AbstractField » objects are created and are accessible.

Extract of the called methods before loading the form 

public boolean prepareData()
{
        // get some data here… 
        return true;
}
public boolean load( AbstractField value, Element element )
{
        // set the value here… 
        return true;
}

Form loading

Once the form is loaded, i.e just before it is displayed on the screen, the readyState() method is called. It is the right place to modify the user interface.

Extract of code implementing modification such as fields assignment, entry and dynamic button adding, just before the form is rendered.

public void readyState()
{
        // set field value 
        AbstractField field1 = this.getDocument().getAbstractFieldByName( "fldLabel1" );
        field1.setValue( "Value of the day" );

        // add entry 
        this.getForm().addEntry( "fldDynamicEntry", new CtlText( "Dynamic" ), new CtlButton( "myButton", new CtlText( "My button" ) ) );

        // add button 
        CtlButton button = this.getForm().createButton( "message", new CtlLocalizedText( "LG_MESSAGE" ), false, null );

        this.getForm().getButtonsContainer().addFirst( button );
        button.addActionListener( new ActionListener()
        {
                public void onClick( ActionEvent event )
                {
                        getNavigator().showAlertBox( "Hello everybody !!!" );
                }
        } );
        super.readyState();
}

Section loading

For the sheet or wizard forms, another method can be overriden to intervene in the page building.

Extract of code implementing the page activation

On this example, the provider checks, for the page named "page3" and "page4”, that the content section is a view. If this is the case, the provider assigned to this view is called to supply the content.

public void activate( ISection section )
{
        if ( "page3".equals( section.getName() ) || "page4".equals( section.getName() ) )
        {
                if ( section.getContent() instanceof CtlAbstractView )
                {
                        CtlAbstractView view = (CtlAbstractView)section.getContent();
                        IViewProvider provider = view.getProvider();
                        provider.getColumns();
                        provider.getItems();
                }

        }
        super.activate( section );
}