For the purposes of this tutorial, you need a JavaFX Desktop application.

To create the application and a Fragments file:

1. Choose File > New Project. The New Project wizard opens. Under Categories, select JavaFX. Under Projects, select JavaFX Desktop Business Application and click Next.
2. The Name and Location page opens. Name the project Fragments. Select a location for the project. Accept the default options and click Finish. The project is created and an empty design file opens in the Editor.
3. Right-click the Fragments project node in the Projects window. Select New > JavaFX Fragments Design File. (If this option does not appear, try New > Other. The New File wizard opens. Expand the JavaFX category.)
   
4. The New JavaFX Fragments Design File wizard opens. Name the file Fragments and place it in the existing fragments package.
   
5. Click Finish. The new design file opens in the editor.

Switch back to the Design view. In this section, you add and configure UI components to the Fragments file.

To design the fragments:

Click the "Run File" menu action or press Shift+F6 on your keyboard to run the fragments design file. When the application starts, you see that the "Index Buttons" and Labels fragments overlap with each other, but when you were editing them in the Design view, they were positioned properly.

Note: If you see only an empty design, you probably used the "Run Project" action or pressed F6 instead of running only the Fragments file.

This is one of the main differences between fragments design files and regular design files. Fragments are meant to be used as they are, without additional shifting or adjusting, in different parts of your UI, Scene, design, and custom code. Therefore, the tool ignores the layoutX and layoutY properties of the root-level components, such as the "tile" and "label" components, and does not set these properties in the generated source code.

Although the following procedure is not recommended, if you want to run the fragments file and see the layout you designed, do the following:

1. Select the Design File > Design Fragments node in the Navigator window.
2. In the Properties window, set the "Generate LayoutXY for Root-level Components" property to "true".
3. If you run the file again, you see the Scene exactly as it is laid out in the design view.

For the purposes of this tutorial, do NOT set the "Generate LayoutXY ..." property. Leave it set to "false".

In both cases, when you run the Fragments file, it is fully functional. You can press the Previous and Next buttons to control the Label's text.

In this section, you add UI components to the Main design file. Later, you embed the fragments into this file.

To design the Main file:

1. In the Projects window, open the "Main" file. Switch to the Design view.
2. Add a VBox container to the Design.
3. Add a Label to the VBox and change its Text property to "The Index Buttons Fragment:".
4. Add a Panel to the VBox and change its Instance Name to "indexButtonsPlaceHolder".
5. Add a second Label to the VBox and change its Text property to "The Label Fragment:" string.
6. Add a second Panel to the VBox and change its Instance Name to "labelPlaceHolder".

So far the Main and Fragments designs are still disconnected. JavaFX Composer does not yet provide support for embedding design fragments in the visual editor. Therefore, you have to embed the fragments by editing the source code.

To embed fragments in the Main design file:

1. Switch to the Source view of the Main design file.
2. Insert the following code into the Main class, after the generated code block:

   //embed the Fragments design into the Main design
   
   def fragments = Fragments {}
    init {
   
        // tile fragment into indexButtonsPlaceholder
        insert fragments.tile into indexButtonsPlaceholder.content;
   
   
        // label fragment into labelPlaceholder
        insert fragments.label into labelPlaceholder.content;
    }
       

Now you can run the entire application.

Run the Fragments project. (F6 or Run Main Project icon , if it is the main project.) The design file is saved and the project is compiled and started. The buttons switch the application between states.

The "Index Buttons" and "Label" components are synchronized and the animations run as you specified in the Fragments design file. This is because the same instance of the Fragments class holds the instances of the index buttons and the label. The application would work this way even if you had used each fragment in a different Scene.

In the same Main design, you can embed multiple instances of one Fragments design or instances of different Fragments designs.

Note that the Main design can control the instances/content/state of the Fragments design. For example, you can add a new button into the Main design and assign an "action" function with the fragments.currentState.next(); code.

To clean up an application, you can delete the run function from the Fragments design file because it is not needed except for testing purposes.

You can convert an existing Main design file into a Fragments file by removing its Scene. Try this on the Main file in your application.

To convert the Main file into a Fragments file:

1. Open the Main design file in the Design view.
2. In the Navigator window, select the "Design File | scene [Scene]" node.
3. In the Properties window, press the "Code" toggle-button to show properties in the Code category.
   
4. Set the Generate Scene property and the Generate getDesignScene Function property to "false".
   

In the Navigator window, the original Design File > scene [Scene] node is replaced with the Design File > Design Fragments node.

Now switch to the "Source" view and expand the generated code section. You can see that the Main class does not contain a definition of the scene instance or a getDesignScene function. You converted the Main design file to a Fragments design file.

Similarly, you can convert a Fragments design file to a Main design file by adding a Scene. To convert your Design Fragments file back to a Main design file, set the Generate Scene property and the Generate getDesignScene Function property to "true".

By switching the Generate Scene property and the Generate getDesignScene Function property between "true" and "false," you can easily convert files back and forth from being Design Fragments files to being Main design files.

You can create a new project from the Media View sample project included in the IDE. Open this sample from the Samples > JavaFX category. This sample demonstrates the design-fragment concept with a single Main.fx design containing the Scene and Stage and multiple design fragments. The fragments are inserted into the Scene in the Main design.

For more information about using NetBeans IDE to develop JavaFX applications, see the following resources: