Reusing of UI Definitions: General Information

You can reuse a UI definition as follows:

To reuse a TypeScript declaration, extend a screen class or a class that derives from a screen class.
To reuse an HTML declaration or any part of it, use one of the following approaches:
- Add the qp-include tag
- Specify the template tag’s id in the ref attribute of the control tag

Learning Objectives

In this chapter, you’ll learn how to:

Reuse the whole UI definition of an MYOB Acumatica form for another form
Create and use a reusable UI definition with and without parameters

Applicable Scenarios

You reuse a UI definition when:

You need to implement two almost-identical MYOB Acumatica forms, such as Site Map (SM200520) and Portal Map (SM200521). You reuse the UI definition of one form to define the other.
You need to implement multiple MYOB Acumatica forms with similar UI definitions, such as Scan and Receive (IN301020), Scan and Issue (IN302020), Scan and Transfer (IN304020), and Scan and Count (IN305020). You implement a reusable UI definition for the common parts and adjust the definition for each form.
You need to use identical form components—such as sections, tabs, or dialog boxes—on multiple forms.

Use of the Whole UI Definition of a Form

A reusable UI definition that defines an entire form usually contains the declaration of a screen class and view classes. So to use it for your form, you need your screen class to extend the screen class of the UI definition. This way, your screen class will have the same logic and properties (that is, views) as the original screen class. To reuse the HTML template of the UI definition, you need to add the qp-include tag with the reference to the original HTML template.

To reuse the UI definition of a form, you need to reuse both the TypeScript declaration and the HTML code:

In the TypeScript file, import the classes from the reusable UI definition, as shown below. You need to import the screen class and all view classes you plan to use.
```
import { SM200520 } from "../SM200520/SM200520";
```
In the TypeScript file, extend the screen class defined in the reusable definition. You must specify the graph type and primary view of the new form in the graphInfo decorator.
Attention: In the Modern UI, each MYOB Acumatica form must use its own graph type.
For example, suppose that a reusable definition declares the SM200520 screen class, and you need to reuse it for the screen with SM200521 screen ID. You define the SM200521 class that extends the SM200520 class and specify the graph for the SM200521 screen, as shown below.
```
@graphInfo({
  graphType: "PX.SiteMap.Graph.PortalMapMaint"
  primaryView: "SiteMap",
})
export class SM200521 extends SM200520 {}
```
You can use an exact copy of the original class or modify the UI definition inherited from the base class.
In the HTML file for the new form, insert the HTML code of the existing form by using the qp-include tag, as shown below.
```
<template>
  <qp-include url="../SM200520/SM200520.html">
</template>
```

Use of a Reusable UI Definition That Defines Part of a Form

A reusable UI definition that defines a part of a form usually contains declarations of view classes but no screen class. So to use the definition for your form, you need to import the view classes from the reusable definition and initialize the views in your screen class. To reuse the HTML template of the UI definition, you need to add the qp-include tag with a reference to the original HTML template.

To use a reusable UI definition that defines part of a form, such as a fieldset:

In the TypeScript file of the form where you need to insert the reusable UI definition, import the view classes, as shown below.
```
import { Address } from "src/screens/common/form-address/form-address";
```

In your form’s screen class, initialize the views and specify the imported view classes as parameters.

@graphInfo({ ... })
export class AM310000 extends PXScreen {
  @viewInfo({ containerName: "Ship-To Address" })
  ShippingAddress = createSingle(Address);
}

In the HTML code of the form where you need to insert the reusable UI definition, add the qp-include tag with a reference to this reusable UI definition. If the reusable definition has parameters, provide their values in the qp-include tag.
Note: You can determine whether the reusable definition has parameters by reviewing the qp-include-parameters tag in the HTML template of the reusable definition.
The following example shows the insertion of a reusable UI definition with parameters. (For details, see Reusing of UI Definitions: Reusable UI Definitions with Parameters.)
```
<div slot="B">
  <qp-include 
    url="src/screens/common/form-address/form-address.html" 
    fs-id="formB" 
    address-view="ShippingAddress" 
    fs-caption="Ship-To Address">
  </qp-include>
</div>
```

Adjusting of the Reusable UI Definition

After inserting a reusable UI definition into a form’s UI definition, you may need to add, remove, or replace particular elements to adjust the definition. Do the following:

In the TypeScript code of the form, you define the elements that aren’t included in the reusable UI definition, as shown below. You can add more view classes, initialize views, or define more logic (for example, in event handlers).
```
export class IN202520 extends BarcodeProcessingScreen {
  @viewInfo({ containerName: "Scan Header"  })
  HeaderView = createSingle(ScanHeader);
}
```
You can find examples of TypeScript code adjustments in UI Adjustments in HTML and TypeScript: TypeScript Examples.
Adjust the HTML template as follows:
1. Add the tags you need to modify after or inside the qp-include tag.
  If the reusable UI definition defines a whole form—that is, your screen class extends the screen class of the UI definition—adjust the layout by adding tags after the qp-include tag. These tags must be located in the top-level template tag of the HTML file.
  If the reusable UI definition defines a part of a form (for example, a fieldset), adjust the layout by adding tags inside the qp-include tag.
2. Specify the attribute that indicates the type of modification, which can be one of these:
  - before: Places the element before the element referenced in this attribute.
  - after: Places the element after the element referenced in this attribute.
  - append: Places the element after all child elements of the element referenced in this attribute.
  - prepend: Places the element before all child elements of the element referenced in this attribute.
  - modify: Modifies the attribute values of the element referenced in this attribute.
  - remove: Removes the element referenced in this attribute.
  - replace: Replaces the element referenced in this attribute.
3. As the value of the attribute, specify a CSS selector that defines the element relative to which you need to place the new element, such as #main or #secondary [name='OriginalFieldName']".
  Tip: You can use the following approaches when specifying the CSS selector:
  - Specifying the exact location of the element, such as the fieldset’s ID and the field’s name.
    If no element satisfies the CSS selector, the build process fails. For example, suppose that you want to place a box right after the specific box in the specific fieldset of a form. You specify the exact location of the new field in the CSS selector, including the fieldset’s ID and the field’s name. If in a future version of MYOB Acumatica, the field relative to which the new field is placed is moved to another fieldset, the build process will fail for this CSS selector.
  - Specifying only the field’s name.
    If more than one item satisfies the specified CSS selector, the build process fails. For example, suppose that you want to place a new box right after a specific box and it doesn’t matter where this specific box is located on the form. You specify only the field’s name in the CSS selector. If the field is moved to another fieldset in a future version of MYOB Acumatica, the build process will be successful for this CSS selector.
  Below you can see an example of adjusting a reusable UI definition that defines a whole form. The code adds three boxes in various fieldsets of the reusable UI definition and adds a tab with a table.
```
<template>
	<qp-include url="../../barcodeProcessing/BarcodeProcessingScreen.html"></qp-include>

	<field append="#fsColumnA-Header" name="RefNbr" config-allow-edit.bind="true"></field>
	<field append="#fsColumnA-Header" name="SiteID"></field>

	<field append="#fsColumnB-Header" name="Mode"></field>

	<qp-tab id="tabIssue" before="#tab-Logs" caption="Issue">
		<qp-grid id="gridPicked" view.bind="transactions"></qp-grid>
	</qp-tab>
</template>
```
  The following example shows an adjustment of a reusable UI definition that defines a part of a form. The code modifies a field in the reusable UI definition.
```
<qp-include url="src/screens/common/form-address/form-address.html"
	fs-id="groupAccountAddress"
	address-view="DefAddress"
	fs-caption="Account Address"
	fs-wg-container="DefAddress_DefAddress"
	override-fieldname
	view-on-map-action-name="ViewMainOnMap"
>
	<field modify="#groupAccountAddress [name='CountryID']" 
        after="#groupAccountAddress [name='PostalCode']"></field>
</qp-include>
```
You add as many adjustments as you need. You can find examples of layout adjustments in UI Adjustments in HTML and TypeScript: HTML Examples.

Predefined Reusable UI Definitions

A number of predefined reusable UI definitions are available in the following locations:

The FrontendSources/screen/src/screens/common folder of the MYOB Acumatica instance
The common folder for particular functionality, such as the FrontendSources/screen/src/screens/IN/common folder of the MYOB Acumatica instance for inventory functionality

You can use these reusable UI definitions in your UI customization projects.