Wizard Framework

This is a framework for the development of wizards within the Energie 360 web platform. This project is created in Nuxt 3 and is fully extensible and configurable.

It is mainly based on its powerful layers system that allows to easily inherit all the functionality of this project as well as adding new elements and combining them with each other in a simple way.

Additionally, This project uses Typescript for strict typing, and the most relevant files are located inside the typesfolder.

This framework requires a configuration to be able to work. This configuration is obtained through a fetch call in the URL that appears inside app.config.tsThe framework will adapt the UI and elements based on this configuration.

Normally during development it is usually combined with a local backend, but if not, it is possible to use a test version inside the ki-mocky-api repository, inside the feature/wizard-framework branch.

Another option would be to create your own endpoints inside the server/api folder within this project as explained in the Nuxt documentation, but we must be careful because this project is intended to be inherited and if these endpoints exist they would be available in each of the frameworks that extend this one, and possibly it is not recommended or just take it into consideration before saving them.

Starting the project

To set up the project two parameters need to be set in the app.config.tsfile:

• url: The URL where the configuration is located.
• translationsUrl: The URL where the basic translations for the project will be provided.

After that, the project can be started with the following command:

pnpm -F @energie360/wizard-framework run dev

Key concepts of the framework

Although the framework is based on Nuxt and in its documentation you can find all the explanation to each one of the sections, there are a few concepts that must be understood to be able to work with the framework properly:

• Navigation
• Middleware
• Layouts
• Global Components
• Key Components
• Composables
• Mock Server

Navigation

The wizard framework only uses a single path which is a dynamic parameter which is the node-id. From this parameter the UI is loaded from the configuration obtained from the server.

Middleware

Inside the node-middleware.ts file are the navigation and redirection rules that must be followed, in case you try to access to the route. If an attempt is made to access a path that does not exist (incorrect node-id) or is not allowed, it will redirect to the correct path based on the configuration obtained from the server, stored inside the config store.

Layouts

There are two types of layouts in the framework, the main layout found in the default.vue file and the layout for the embedded Wizards versions found in the embedded.vue file. It will be determined which of the two layouts should be implemented based on the configuration that is defined within the app.config.ts.

Global Components

Inside the components folder are the global components that are used throughout the project loaded dynamically. These components are loaded based on the configuration obtained from the server and as it is impossible to know in advance which components will be used, they are loaded globally and will always be available both in the framework and in the projects that extend it.

Key Components

Maybe one of the most important key components would be the WizardBuilder.vuecomponent, which is in charge of loading and rendering all subcomponents that are defined in the configuration obtained from the server. This component contains all the necessary logic to render the wizard and its steps. That means that if you want to integrate a whole Wizard process into a Nuxt project, all you need to do is to include this component and pass the needed props.

Composables

There are some components that are necessary to highlight and that are key for the operation of the framework, these are:

• UseConfigStore: Is in charge of storing the configuration obtained from the server and of providing and updating it in any part of the project.
• useformStore: Is in charge of storing the state of the form that will be sent to the server.
• completeWizardStep: Is in charge of the request to the server to advance to the next step.
• populateForm: Is in charge of populating the form with the data obtained from the server.

Mock Server

The mock server is a server that is used to simulate the behavior of the backend. It is used to test the project without the need to have a backend. It is a layer that is added to the project and that is only available in development mode.

Every wizard that extends this project will have access to this mock server, and it is recommended to use it to define the behavior of the backend and the data that will be returned.