Create a wizard page

15 minutes

A wizard page guides a user through the installation process. The wizard page is called from within Assisted Setup. To build a wizard page, you need to set the PageType property to NavigatePage.

In the client, the NavigatePage page doesn't an action bar. It's designed to have buttons at the bottom that let users move back and forth through the steps by selecting the Back and Next buttons, until they finish by selecting the Finish button.

The purpose of a wizard is to enable a user to configure settings and store those settings only when the user selects the Finish button. Because Business Central automatically stores all modifications from the moment you leave an input field, you need to set the SourceTableTemporary property to true. This setting ensures that modifications are only stored in memory and that, when the user selects the Finish button, you can copy the modifications from memory to the database.

Build the assisted setup

This section describes the basic tasks for creating an assisted setup. It gives you an understanding of the general structure of an assisted setup guide. Knowing this information helps you build assisted setup guides that look and feel like the ones provided by Microsoft. This section includes some basic AL code for the various steps involved in creating an assisted setup guide.

The example code for reference only, and your implementation might vary.

Create a page for the assisted setup, for example:

page 50100 ToDoAssistedSetup
{
PageType = NavigatePage;
SourceTable = "To-do";
SourceTableTemporary = true;
Caption = 'Add a To-Do for the Team';
}

Set the following properties:
- PageType property - Set to NavigatePage.
- SourceTable - Set to the name of the table that stores the data for the assisted setup.
- SourceTableTemporary - Set to true. The reason is because Business Central automatically stores all modifications to database tables as soon as users move focus to another field or close the page. Using a temporary table let's users exit the assisted setup guide at any point, without saving the changes they've made so far to the database. Instead, the data modifications are only stored in memory, until code is run to transfer the data to the database.
- Caption - Set to the title that you want to show on the top of each step of the assisted guide.
Add the steps that comprise the assisted setup.

For each step that you want in the guide, add a group() control to the root-level of the layout > area(Content) control. For example, the following code adds three steps.
```
layout
{
    area(Content)
    {
        group(Step1)
        {
            Caption = '';
            InstructionalText = '';
            Visibility = Step1Visible;
        }
        group(Step2)
        {
            Caption = '';
            InstructionalText = '';
            Visibility = Step2Visible;

            field(Field2; "Field2")
            {
                ApplicationArea = All;
                Caption = '';
            }
        }
        group(Step3)
        {
            Caption = '';
            InstructionalText = '';
            Visibility = Step3Visible;
        }
    }
}

var
    Step1Visible: Boolean;
    Step2Visible: Boolean;
    Step3Visible: Boolean;
    Step: Option Start,Fill,Finish;

local procedure EnableControls()
begin
    ResetControls();
    case Step of
        Step::Start:
            ShowStep1();
        Step::Fill:
            ShowStep2();
        Step::Finish:
            ShowStep3();
    end;
end;
```
The individual group() controls define the content to display for the step, like text and data entry fields. For example, use the Caption and InstructionalText properties to add text. Use field() controls for source table fields.

The order of the group() controls doesn't necessarily determine the order of the steps in the assisted setup. You add AL code to define the logic for when each step appears.

You can include group() controls within the root-level group() controls. These subgroups can be useful for adjusting the layout fields on a step and adding captions and instructional text.

Because only one step can be shown at a time, you have to add logic to control when each step is shown. To control the visibility:
- For each step, define a global Boolean variable or a step number condition and apply it the group's Visible property. The example uses the Boolean variables Step1Visible, Step2Visible, and Step3Visible.
- You then have to add AL code to change these variables depending on which step the user is working on.
- Define a global option variable that has a value for each step.
- You use this variable in code to track which step is active.
Multiline fields shown inside a step are shown without a gray background. This behavior allows you to write a list of items or any formatted text that requires new lines.

Add the navigation buttons.

Assisted setups typically have a Back, Next, and Finish button at the bottom-right of the page. Add each button by using an action() control.

actions
{
    area(Processing)
    {
        action(Back)
        {
            Enabled = BackEnable;
            InFooterBar = true;
            Image = PreviousRecord;

            trigger OnAction()
            begin
                NextStep(true);
            end;
        }
        action(Next)
        {
            Enabled = NextEnable;
            InFooterBar = true;
            Image = NextRecord;

            trigger OnAction()
            begin
                NextStep(false);
            end;
        }
        action(Finish)
        {
            Enabled = FinishEnable;
            InFooterBar = true;
            Image = Approve;

            trigger OnAction()
            begin
                Finished();
            end;
        }
    }
}

var
    BackEnable: Boolean;
    NextEnable: Boolean;
    FinishEnable: Boolean;

local procedure NextStep(Backwards: Boolean)
begin
    if Backwards then
        Step := Step - 1
    else
        Step := Step + 1;
    EnableControls();
end;

local procedure Finished()
begin
    StoreRecordVar();
    CurrPage.Close();
end;

Set the InFooterBar property for each to true.
If the property isn't set or is false, then the actions don't appear.
Similar to the Visible property on the groups, use the Enabled property to control when buttons are active on the different steps. For example, Back isn't active in the first step, and Next isn't active in the last step.
Like on groups, define global Boolean variables for each action, then apply the variable to the action's Enabled property. The global variables are then controlled in AL code.
To style the buttons to match other assisted setups in the Microsoft base application, set the Image property to PreviousRecord for the back button, NextRecord for the next button, and Approve for the finish.

Transfer data from the temporary table to the database table. For example:

var
     ToDoRec: Record "To-do";

 local procedure StoreRecordVar();
 begin
     ToDoRec.TransferFields(Rec, true);
     ToDoRec.Insert();
 end;

In this example, the StoreRecordVar procedure is called from the Finished procedure used on the actions.

Add standard banners

You might have noticed that most assisted setup guides in the base application, and in this article, include two different banners under the step caption: a gear and a check mark. These banners are based on the following image files in the Media Repository table:

AssistedSetup-NoText-400px.png for the gear
AssistedSetupDone-NoText-400px.png for the check mark.

You can reuse these images in your custom assisted setup guides to provide a consistent look. To a display the banners, add two root-level group() controls in to the area(Content) control, like for the steps. Use field() controls for displaying the gear and check mark images. The following snippets illustrate one way of adding the banners:

...
    layout
    {
        area(Content)
        {
            ...
            group(StandardBanner)
            {
                Caption = '';
                Editable = false;
                Visible = TopBannerVisible and not FinishActionEnabled;
                field(MediaResourcesStandard; MediaResourcesStandard."Media Reference")
                {
                    ApplicationArea = All;
                    Editable = false;
                    ShowCaption = false;
                }
            }
            group(FinishedBanner)
            {
                Caption = '';
                Editable = false;
                Visible = TopBannerVisible and FinishActionEnabled;
                field(MediaResourcesDone; MediaResourcesDone."Media Reference")
                {
                    ApplicationArea = All;
                    Editable = false;
                    ShowCaption = false;
                }
            }
        }
    }
...
var
    ...
    MediaRepositoryDone: Record "Media Repository";
    MediaRepositoryStandard: Record "Media Repository";
    MediaResourcesDone: Record "Media Resources";
    MediaResourcesStandard: Record "Media Resources";

trigger OnInit();
begin
    ...
    LoadTopBanners();
end;

local procedure LoadTopBanners();
begin
    if MediaRepositoryStandard.Get('AssistedSetup-NoText-400px.png', Format(CurrentClientType())) and
        MediaRepositoryDone.Get('AssistedSetupDone-NoText-400px.png', Format(CurrentClientType()))
    then
        if MediaResourcesStandard.Get(MediaRepositoryStandard."Media Resources Ref") and
            MediaResourcesDone.Get(MediaRepositoryDone."Media Resources Ref")
    then
            TopBannerVisible := MediaResourcesDone."Media Reference".HasValue();
end;

Continue

Build the assisted setup

Add standard banners

Feedback