Inquirer GUI
Vue3 migration
The master
branch now supports Vue3 and Vuetify3.
The Form
component, builtin plugins and all custom plugins were migrated.
The new versioning is 3.x.y.
Vue2 maintenance mode
We still keep master-maintenance
branch that is based on Vue2.
Please reserve the use of this branch exclusively for critical features or bug fixes.
Since we're still in the process of fully transitioning to Vue3, any changes made here will also need to be contributed to the master branch (Vue3 based).
When making changes, make sure to increase the version number based on the nature of the change. However, DO NOT increase the major version to 3, as that version is specifically reserved for the Vue3 release channel.
Description
inquirer-gui
is a UI component that displays Inquirer.js-compliant questions in an interactive HTML form.
Requirements
- node.js version 10 or higher.
Installation and Usage
There are several use-cases for the consuming inquirer-gui
component:
- You can use it in another Vue application or in a non-Vue application.
- You can use it in a browser or in Visual Studio Code.
- You can provide the questions in the frontend or in the backend (providing questions in the backend implies more flexibility in composing questions)
We provide examples for some of the above use-cases.
First, clone this directory:
git clone https://github.com/SAP/inquirer-gui
Run in Browser (Frontend Questions)
Use the provided sample-app
:
npm install
cd sample-app
npm install
npm run serve
This will run the web server on localhost
on an available port. Open the provided link in the browser.
Run in Browser - vite based application (Frontend Questions)
Use the provided sample-app-vite
:
npm install
cd sample-app-vite
npm install
npm run serve
This will run the web server on localhost
on an available port. Open the provided link in the browser.
Run in Browser (Backend Questions)
Use the provided sample-app
and websocket-server
:
npm install
cd websocket-server
npm install
If using Visual Studio Code, run the WebSocket Server
debug configuration. This will start the sample WebSocket server that listens for requests on port 8081
.
cd sample-app
npm install
npm run serve
This will run the web server on localhost
on an available port. Open the provided link in the browser.
Run as VSCode Extension
Use the provided sample-vscode-extension
:
cd sample-vscode-extension
npm install
npm run compile
npm run copy-dist
Open the sample-vscode-extension
as root folder and in the run configurations choose Launch Extension
.
If you change the source code of the extension itself you must re-run npm run compile
.
If changing the webview content don't forget to update the dist
folder by running npm run clean-dist && npm run copy-dist
.
The copy-dist
script creates the dist
folder containing the Vue Web application you want to load as webview in a VSCode extension panel and copy it to the extension.
Note that the vscode extension contains example code that loads the index.html, styles and scripts. In Vue3 using vite based configuration, the bundled code and structure has been changed so this code has to be adjusted accordingly.
Usage
If writing a Vue application, simply add the following line to your <template>
tag:
<form ref="form" :questions="questions" @answered="onAnswered" />
The questions
property is an inquirer.js-compliant array of questions. E.g.:
[
{
type: "input",
name: "name",
message: "Your name (frontend)",
default: "Joe",
validate: function (input) {
if (input.length >= 2) {
return true;
} else {
return "Name must be at least 2 characters long";
}
},
},
];
The answered
event is fired when any answer is changed:
- The first parameter to the event handler,
answers
, contains all answers. - The second parameter,
issues
, can be used to, for example, enable or disable aNext
button.
Custom form elements
inquirer-gui
provides built-in form elements for all built-in inquirer.js
question types:
list
,rawlist
expand
checkbox
confirm
input
(number, password and input)editor
inquirer-gui
supports custom form elements via its plugin
mechanism (see more here).
Creating a custom form element
A form element plugin is a javascript
object with this structure:
{
questionType: '<inquirer-question-type>';
component: <MyVueComponent>;
}
Where questionType
is the string provided in the question's type
property, and component
is a Vue
component that renders questions of the given type.
There is example of a custom form element in the /sample-plugin
folder. It is defined as a Vue plugin
and was published as @sap-devx/inquirer-gui-date-plugin
on npm
.
Consuming a custom form element
Consume a custom form element as a Vue plugin
using the app.use()
method. The plugin is returned in the method's options
parameter. For example, refer to /sample-app/src/App.vue
:
import DatePlugin from "@sap-devx/inquirer-gui-date-plugin";
const options = {};
// use the Vue plugin
app.use(DatePlugin, options);
// register the inquirer-gui plugin with your form instance
form.registerPlugin(options.plugin);
How to obtain support
To get more help, support and information please open a github issue.
Contributing
Contributing information can be found in the CONTRIBUTING.md file.