Using prefabs

Use prefabs (prefabricated templates) to create consistent interfaces. Prefabs allow you to create the building blocks of your application and make the application easier to maintain.

Create a prefab for every item in your application that appears more than once or if you want to logically separate a part of your application. For example, use prefabs to:

Create content with consistent structure. For example, with prefabs you can create buttons that always have the same structure, but can vary in appearance.
Modularize your project and make it easier to maintain.
Control the loading and launch times of your Kanzi application.
Create different themes for your Kanzi application UI.

When using prefabs keep in mind that:

You can duplicate an instance of a prefab like any other node in the scene graph.
Property values you add to an instance of a prefab override the property values set in the prefab.
Use relative paths when you want to reference items inside a prefab (for example, in a message trigger or a property binding). Do not use the prefab itself as a target path for any messages or animations.

You can nest prefabs within prefabs.

Creating an using a prefab

To create and use a prefab:

In the Project right-click Prefabs, select Create, and then the object you want to create.
For example, create a Button 2D, add an Image and a Text Block 2D to it.
In the Project drag and drop the prefab from the Prefabs to the location in your project where you want to use the prefab.
Kanzi Studio creates a new instance of the prefab in your project.

(Optional) To instantiate a different prefab, in the Project select the prefab you want to change, and in the Properties set the Prefab Template property to the prefab you want to instantiate.
(Optional) If you know where in the scene graph you want to instantiate a prefab, but do not yet have that prefab ready, create a Prefab Placeholder 3D for 3D prefabs and Prefab Placeholder 2D for 2D prefabs. To instantiate a prefab using a placeholder, in the Project select the prefab placeholder and in the Properties set the Prefab Template property to the prefab you want to instantiate.

Customizing instances of a prefab

A prefab can contain a tree of nodes, each with their own properties. When you edit the nodes in a prefab or its instance, you change those nodes in all instances of that prefab. However, you can customize individual instances of the prefab to have individual values by overriding the values in the default prefab. For example, when you create a prefab for an address book entry you want to show a different name, number, and photo for each address book entry.

To customize individual instances of a prefab:

In the Project select the node in a prefab you want to customize in an individual instance of that prefab.
In the Properties next to the property you want to edit click .
Kanzi Studio creates from that property a custom property, adds it to the root of the prefab, and creates a binding to the property in the prefab root.
In the Project select the root of the prefab instance you want to customize.
In the Properties click next to the property for which you enabled editing and enter the value of the property you want to use only in that instance of the prefab.

Editing a prefab

To edit a prefab double-click the prefab in the Project > Prefabs. Kanzi Studio shows only the prefab in a Preview window tab. You can now edit the prefab with the Preview tools and see the result of your edits without instantiating the prefab.

Turning scene graph nodes into prefab

To turn any part of the your project's scene graph into a prefab, in the Project drag the root of the part you want to turn into a prefab to the Project > Prefabs directory.

Kanzi Studio creates a prefab template from the object and replaces the original object with an instance of the prefab.

Replacing the root node of a prefab

Replace the root node of a prefab when you want to add or change the node that is used as the parent node of a prefab. For example, if you first created a prefab that has a Grid Layout 3D as its root, but now you to place that Grid Layout 3D into a Stack Layout 3D, you need to replace the root node of that prefab.

To replace the root of a prefab:

In the Project > Prefabs press Alt and right-click the root of the prefab you want to replace and select Empty Node 3D From Items.
Kanzi replaces the current root of the prefab with an Empty Node 3D node and places the entire prefab inside that empty node.
In the Project > Prefabs create the node you want to use as the new root node of the prefab.
For example, create a Stack Layout 3D.
Drag and drop the old prefab from the Empty Node 3D node to the new node.

Instantiating a prefab using a script

Use a script to instantiate a prefab or replace objects with prefabs in your project when you know where in the scene graph in your project you want to use a prefab, but do not want to instantiate the prefab in Kanzi Studio.

To instantiate a prefab using a script:

In the Project > Prefabs create a prefab you want to instantiate using a script.
For example, create a Text Block 3D.
In the Project create the object to which you want to instantiate a prefab.
For example, in the Scene create a Stack Layout 3D.
In the Project create the object you want to use to trigger the instantiating of a prefab.
For example, in the Scene create a Button 3D and use its Button: Click trigger.
In the Triggers in the trigger you want to use instantiate a prefab, click the Add drop-down menu, and select the Execute Script action.
The Execute Script window opens.
In the Execute Script window select an existing script, or select <Add new script...> to create a new script.
The Script Editor window opens.
In the Execute Script window click Save.
In the Script Editor write the script that instantiates a prefab. See Reference for scripting.
To get the kzb URL of a prefab, in the Project right-click the prefab and select Copy as kzb URL.
For example, to instantiate the Text Block 3D prefab in a Stack Layout 3D using the Button 3D you created in this procedure
```
var layout = node.lookupNode('../Stack Layout 3D');
var item = instantiatePrefab('kzb://ProjectName/Prefabs/Text Block 3D', 'Text prefab');
layout.addChild(item);
```
When you are done writing the script, but before executing it, in the Script Editor click Save.
Set off the trigger to execute the script.
For example, if you created a button and used the Button: Click trigger, click that button.