The factory method is static and hence it has to be called from the class rather than any instance of the class. That is you call it using:

BlankFragment myFrag= BlankFragment.newInstance("param1","param2")

The parameters param1 and param2 are stand-ins for you to change to the number and type of parameters you actually want to use. The parameters are the arguments you are going to use to customise your Fragment's View hierarchy.

The template also automatically adds two private fields for you to to store the parameter values in if you need to:

private String mParam1;private String mParam2;

Again you have to change the type, name and number of these variables to fit in with whatever you are passing as parameters.

Now we come to the tricky part.

You don't want to make use of the parameters passed to the factory method when the Fragment is constructed because it can be destroyed and recreated by the system via the parameterless constructor.

Just as in the case of an Activity you have to be prepared to re-set the state of a Fragment when the system restores it and to do this we have to make use of a Bundle. This is exactly what we have to do with the Activity's state and the way a Bundle works was described in Chapter 4.

The basic idea is that a Bundle is just an object that you can use to store simple values as name, value pairs.

To make this slightly easier, the template creates some default names for each for the parameters it has generated:

and again you need to edit these lines to use appropriate names for the parameters. You also need to change putString to what ever data type you are using of each parameter. Notice that you can only store a limited range of data types in a Bundle - you can't use it to pass an object say (unless the object can be serialized).

Finally you make use of the Fragment's setArguments method to store the Bundle:

fragment.setArguments(args); return fragment;}

Ok so now you have stored the Fragment's arguments safely in a Bundle and you can rely on the system to take care of them even if the Fragment is removed. We have yet to see how to make use of the Bundle but this is fairly easy.

if the system needs to destroy the Fragment it will preserve its Arguments bundle and make it available again when it restores the Fragment.

Using The Bundle

Ok, this is fine but where to you actually make use of them?

You have some freedom in this.

The basic idea is that you can make use of the getArguments method to retrieve the arguments Bundle anywhere in your Fragment that they are needed. Of course it only makes sense to do this in methods that are called when the Fragment is being created or recreated.

In most cases this means retrieving the arguments in the Fragment's onCreate event handler or in the onCreateView handler.

The onCreate method is called before the onCreateView handler and it is most often used to retrieve the arguments and store them in locations that the rest of the Fragment can access. It also has the advantage that it keeps the onCreateView method dedicated to what it is supposed to do i.e. create the view.

The generated onCreate simply checks to see if there are any arguments to retrieve and if there are it retrieves them and stores them in the private variables:

Following this the arguments that you have passed are accessible via the private fields from anywhere within the Fragment class.

if you are following this description it should be clear to you why the template doesn't just store the arguments into the private fields using the factory method or the parametrized constructor.

So to summarise:

Use the factory method or the parametrized constructor to store any arguments needed in the arguments Bundle

Retrieve the arguments stored in the Bundle as part of the onCreate or if you really need to the onCreateView event handlers.

If you follow these two rules your Fragment will be correctly initialized when you create it and when the system recreates it.

The final thing we have to do is look at the onCreateView event handler. This simply inflates the XML layout file and returns it as a result. In a more general situation it might use mParam1 or mParam2 to modify the UI in some way: