Doc: adding JSON-based custom wizards

Task-number: QTCREATORBUG-13642
Change-Id: Ie3af0d4bdef33364cc442449ccfb5e770c0c3a99
Reviewed-by: Tobias Hunger <tobias.hunger@theqtcompany.com>

4 files changed, 764 insertions, 56 deletions

diff --git a/doc/src/projects/creator-projects-custom-wizards-json.qdoc b/doc/src/projects/creator-projects-custom-wizards-json.qdoc
new file mode 100644
index 0000000000..6cb14c6d2d
--- /dev/null
+++ b/doc/src/projects/creator-projects-custom-wizards-json.qdoc
@@ -0,0 +1,686 @@
+/****************************************************************************
+**
+** Copyright (c) 2014 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of Qt Creator
+**
+**
+** GNU Free Documentation License
+**
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+**
+****************************************************************************/
+
+// **********************************************************************
+// NOTE: the sections are not ordered by their logical order to avoid
+// reshuffling the file each time the index order changes (i.e., often).
+// Run the fixnavi.pl script to adjust the links to the index order.
+// **********************************************************************
+
+/*!
+    \contentspage {Qt Creator Manual}
+    \previouspage creator-project-wizards.html
+    \page creator-project-wizards-json.html
+    \nextpage creator-project-wizards-xml.html
+
+    \title Adding JSON-Based Wizards
+
+    \image qtcreator-new-qt-gui-application.png
+
+    The JSON-based wizards are displayed in the \uicontrol New dialog. To
+    customize them, copy a directory that contains a wizard.json file in
+    \c {share/qtcreator/templates/wizards/} and modify it to fit your needs.
+    After you run qmake and restart \QC, the wizard name appears in the
+    selected or added category. For each wizard, an icon, a display name, and
+    a description are displayed.
+
+    JSON-based wizard template directories contain a JSON configuration file
+    called wizard.json and the template files. The configuration file contains
+    sections that specify information about the wizard, variables that you can
+    use, wizard pages, and generators for creating files.
+
+    \section1 Using Variables in Wizards
+
+    You can use variables (\c %{<variableName>}) in the configuration and
+    template source files. A set of variables is predefined by the wizards and
+    their pages. You can introduce new variables as shortcuts to be used later.
+    Define the variable key names and values in the \c options section in the
+    .json file.
+
+    The variables always return strings. In places where a boolean value is
+    expected and a string is given, an empty string is treated as \c false and
+    anything else as \c true. A common pitfall is that a string containing
+    \c "false" is not empty and is therefore treated as the value \c true when
+    converted to a boolean value. To avoid this pitfall, use the following type
+    of construction:
+
+    \code
+    {"condition": "%{JS: ('%{VersionControl}' === 'G.Git') ? 'yes' : ''}"
+    \endcode
+
+    \section1 Localizing Wizards
+
+    If a setting name starts with the \c tr prefix, the value is visible to
+    users and should be translated. If the new wizard is included in the \QC
+    sources, the translatable strings appear in the \QC translation files and
+    can be translated as a part of \QC. Alternatively, you can place the
+    translations in the .json file using the following syntax:
+
+    \code
+    "trDisplayName": { "C": "default", "en_US": "english", "de_DE": "deutsch" }
+    \endcode
+
+    For example:
+
+    \code
+    "trDisplayName": { "C": "Project Location", "en_US": "Project Location", "de_DE": "Projekt Verzeichnis" }
+    \endcode
+
+    \section1 Creating Wizards
+
+    \QC contains wizards for adding classes, files, and projects. You can
+    use them as basis for adding your own wizards. We use the C++ wizard
+    to explain the process and the sections and settings in the .json file.
+
+    \image qtcreator-cpp-class-wizard.png
+
+    For more information about the pages and widgets that you can add, see
+    \l {Available Pages} and \l{Available Widgets}.
+
+    To create a JSON-based C++ class wizard:
+
+    \list 1
+
+        \li Make a copy of \c {share/qtcreator/templates/wizards/classes/cpp}
+            and rename it.
+
+        \li Right-click the project name in \uicontrol Projects and select
+            \uicontrol {Run qmake} to register the new wizard. Basically, qmake
+            generates a fixed list of files to copy. Therefore, you need to run
+            qmake each time the names or locations of the files change.
+
+        \li Open the wizard configuration file, \c wizard.json for editing:
+
+            \list
+
+                \li The following settings determine the type of the wizard and
+                    its place in the \uicontrol New dialog:
+
+                    \code
+                    "version": 1,
+                    "kind": "class",
+                    "id": "A.Class",
+                    "category": "O.C++",
+                    \endcode
+
+                \list
+
+                    \li \c version is the version of the file contents. Do not
+                        modify this value.
+
+                    \li \c kind specifies the type of the wizard:  \c class,
+                       \c file, or \c project.
+
+                    \li \c id is the unique identifier for your wizard. You can
+                        use a leading letter to specify the position of the
+                        wizard within the \c category.
+
+                    \li \c category is the category in which to place the wizard
+                        in the list. You can use a leading letter to specify the
+                        position of the category in the list in the
+                        \uicontrol New dialog.
+
+                    \li \c disabled is set to to \c true to hide the wizard. By
+                        default, it is set to \c{false}.
+                \endlist
+
+            \li The following settings specify the icon and text that appear in
+               the  \uicontrol New dialog:
+
+                \code
+                "trDescription": "Creates a C++ header and a source file for a new class that you can add to a C++ project.",
+                "trDisplayName": "C++ Class",
+                "trDisplayCategory": "C++",
+                "icon": "../../global/genericfilewizard.png",
+                "featuresRequired": [ "Plugin.CppEditor" ],
+                \endcode
+
+            \list
+
+                \li \c trDescription appears in the right-most panel when
+                    \c trDisplayCategory is selected.
+
+                \li \c trDisplayName appears in the middle panel when
+                    \c trDisplayCategory is selected.
+
+                \li \c trDisplayCategory appears in the \uicontrol New dialog,
+                    under \uicontrol Projects.
+
+                \li \c icon appears next to the \c trDisplayName in the middle
+                    panel when \c trDisplayCategory is selected. We recommend
+                    that you specify the path relative to the wizard.json file,
+                    but you can also use an absolute path.
+
+                \li \c featuresRequired specifies the \QC features that the
+                    wizard depends on. If a required feature is missing, the
+                    wizard is hidden. For example, if the CppEditor plugin is
+                    disabled, the C++ Class wizard is hidden.
+
+                \li \c featuresPreferred specifies the build and run kits to
+                    preselect.
+
+                \li \c platformIndependent is set to \c true if the wizard is
+                    supported by all target platforms. By default, it is set to
+                    \c{false}.
+
+            \endlist
+
+            \li The \c options section contains an array of objects with \e key
+                and \e value attributes. You can define your own variables to
+                use in the configuration and template source files, in addition
+                to the predefined variables. For example, the following
+                variables are used in the C++ class creation wizard:
+
+                \code
+                "options":
+                [
+                    { "key": "TargetPath", "value": "%{Path}" },
+                    { "key": "HdrPath", "value": "%{Path}/%{HdrFileName}" },
+                    { "key": "SrcPath", "value": "%{Path}/%{SrcFileName}" },
+                    { "key": "CN", "value": "%{JS: Cpp.className('%{Class}')}" },
+                    { "key": "Base", "value": "%{JS: ( '%{BaseCB}' === '' ) ? '%{BaseEdit}' : '%{BaseCB}'}" },
+                    { "key": "isQObject", "value": "%{JS: ('%{Base}' === 'QObject' || '%{Base}' === 'QWidget' || '%{Base}' === 'QMainWindow' || '%{Base}' === 'QDeclarativeItem' || '%{Base}' === 'QQuickItem' ) ? 'yes' : ''}" },
+                    { "key": "GUARD", "value": "%{JS: Cpp.classToHeaderGuard('%{Class}', '%{JS: Util.preferredSuffix('text/x-c++hdr')}')}" },
+                    { "key": "SharedDataInit", "value": "%{JS: ('%{IncludeQSharedData}') ? 'data(new %{CN}Data)' : '' }" }
+                ],
+                \endcode
+
+                This section is optional. For more examples of variables, see
+                the wizard.json files for other wizards.
+
+            \li The \c pages section specifies the wizard pages. The pages
+                used depend on the wizard type. You can add standard pages to
+                wizards or create new pages using the available widgets. The
+                following settings specify the display name, title, and type of
+                the page:
+
+                \code
+                "pages":
+                [
+                    {
+                        "trDisplayName": "Define Class",
+                        "trShortTitle": "Details",
+                        "typeId": "Fields",
+                "data" :
+                [
+                    {
+                        "name": "Class",
+                        "trDisplayName": "Class name:",
+                        "mandatory": true,
+                        "type": "LineEdit",
+                        "data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" }
+                    },
+                    ...
+                ]
+                \endcode
+
+                \list
+
+                    \li \c typeId specifies the page to use: \c Fields, \c File,
+                        \c Form, \c Kits, \c Project, or \c Summary. Full page
+                        ID, as used in the code, consists of the \c typeId
+                        prefixed with \c {"PE.Wizard.Page."}. For more
+                        information, about the pages, see \l{Available Pages}.
+
+                    \li \c trDisplayName specifies the title of the page. By
+                        default, the page title is used.
+
+                    \li \c trShortTitle specifies the title used in the sidebar
+                        of the Wizard. By default, the page title is used.
+
+                    \li \c trSubTitle specifies the subtitle of the page. By
+                        default, the page title is used.
+
+                    \li \c index is an integer value that specifies the page ID.
+                        It is automatically assigned if you do not set it.
+
+                    \li \c enabled is set to \c true to show the page and to
+                        \c false to hide it.
+
+                    \li \c data specifies the wizard pages. In the C++ wizard,
+                        it specifies a \c Fields page and a \c Summary page. The
+                        \c Fields page contains the \c CheckBox, \c ComboBox,
+                        \c LineEdit, \c PathChooser, and \c Spacer widgets. For
+                        more information about the widgets, see
+                        \l{Available Widgets}.
+
+                \endlist
+
+            \li The \c generators section specifies the files to be added to the
+                project:
+
+                \code
+                "generators":
+                [
+                    {
+                        "typeId": "File",
+                        "data":
+                        [
+                            {
+                                "source": "file.h",
+                                "target": "%{HdrPath}",
+                                "openInEditor": true
+                            },
+                            {
+                                "source": "file.cpp",
+                                "target": "%{SrcPath}",
+                                "openInEditor": true
+                            }
+                ]
+                \endcode
+
+                \list
+
+                   \li \c typeId specifies the type of the generator. Currently,
+                        only \c File is supported.
+
+                    \li \c data spefices the files to generate. For a each file
+                        to be generated, specify the following values:
+
+                    \list
+
+                        \li \c source specifies the path and filename of the
+                            template file relative to the wizard.json file.
+
+                        \li \c target specifies the location of the generated
+                            file, either absolute or relative to
+                            \c %{TargetPath}, which is usually set by one of the
+                             wizard pages.
+
+                        \li \c openInEditor opens the file in the appropriate
+                            editor if it is set to \c{true}.
+
+                        \li \c openAsProject opens the project file in \QC if it
+                            is set to \c{true}.
+
+                        \li \c condition generates the file if the condition
+                            returns \c{true}. For more information, see
+                            \l{Using Variables in Wizards}.
+
+                    \endlist
+
+                \endlist
+
+          \endlist
+
+    \endlist
+
+    \section1 Available Pages
+
+    You can add predefined pages to wizards by specifying them in the \c pages
+    section of a wizard.json file.
+
+    \section2 Field Page
+
+    A Field page has the \c typeId value \c Field and contains widgets. For more
+    information about widget definitions, see \l{Available Widgets}.
+
+    \code
+    "pages":
+    [
+        {
+            "trDisplayName": "Define Class",
+            "trShortTitle": "Details",
+            "typeId": "Fields",
+            "data" :
+            [
+                {
+                    "name": "Class",
+                    "trDisplayName": "Class name:",
+                    "mandatory": true,
+                    "type": "LineEdit",
+                    "data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" }
+                },
+                ...
+    ],
+    \endcode
+
+    \section2 File Page
+
+    A File page has the \c typeId value \c File. You can leave out the \c data
+    key or assign an empty object to it.
+
+    \code
+    {
+        "trDisplayName": "Location",
+        "trShortTitle": "Location",
+        "typeId": "File"
+    },
+    \endcode
+
+    The page evaluates \c InitialFileName and \c InitialPath from the wizard to
+    set the initial path and filename. The page sets \c TargetPath to the full
+    path of the file to be created.
+
+    \section2 Form Page
+
+    A Form page has the \c typeId value \c Form. You can leave out the \c data
+    key or assign an empty object to it.
+
+    \code
+    {
+        "trDisplayName": "Choose a Form Template",
+        "trShortTitle": "Form Template",
+        "typeId": "Form"
+    },
+    \endcode
+
+    The page sets \c FormContents to an array of strings with the form contents.
+
+    \section2 Kits
+
+    A Kits page has the \c typeId value \c Kits. The \c data section of a Kits
+    page contains an object with the field \c projectFilePath set.
+
+    \code
+    {
+        "trDisplayName": "Kit Selection",
+        "trShortTitle": "Kits",
+        "typeId": "Kits",
+        "enabled": "%{IsTopLevelProject}",
+        "data": { "projectFilePath": "%{ProFileName}" }
+    },
+    \endcode
+
+    The page evaluates \c Platform to set the platform selected in
+    \uicontrol File > \uicontrol New, \c PreferredFeatures to set the preferred
+    features for the project, and \c RequiredFeatures to set the required
+    features for the project. The feature set is used to determine which kits to
+    display and pre-select for the project.
+
+    \section2 Project
+
+    A Project page has the \c typeId value \c Project. It contains no data or an
+    empty object.
+
+    \code
+    {
+        "trDisplayName": "Project Location",
+        "trShortTitle": "Location",
+        "typeId": "Project"
+    },
+    \endcode
+
+    The page evaluates \c InitialPath to set the initial project path. The page
+    sets \c ProjectDirectory and \c TargetPath to the project directory.
+
+    \section2 Summary
+
+    A Summary page has the \c typeId value \c Summary. It contains no data or
+    an empty object.
+
+    \code
+    {
+        "trDisplayName": "Project Management",
+        "trShortTitle": "Summary",
+        "typeId": "Summary"
+    }
+    \endcode
+
+    The page sets \c IsSubproject to an empty string if this is a toplevel
+    project and to \c yes otherwise. It sets \c VersionControl to the ID of the
+    version control system in use.
+
+    \section1 Available Widgets
+
+    You can add the following widgets on a Field page:
+
+    \list
+        \li Check Box
+        \li Combo Box
+        \li Label
+        \li Line Edit
+        \li Path Chooser
+        \li Spacer
+        \li Text Edit
+    \endlist
+
+    Specify the following settings for each widget:
+
+    \list
+
+        \li \c name specifies the widget name. This name is used as the variable
+            name to access the value again.
+
+        \li \c trDisplayName specifies the label text visible in the UI (if
+            \c span is not \c true).
+
+        \li \c type specifies the type of the widget: \c CheckBox, \c ComboBox,
+            \c Label, \c LineEdit, \c PathChooser, \c Spacer, and \c TextEdit.
+
+        \li \c data specifies settings for the widget:
+
+        \list
+
+            \li \c visible is set to \c true if the widget is visible, otherwise
+                it is set to \c false. By default, it is set to \c true.
+
+            \li \c enabled is set to \c true if the widget is enabled, otherwise
+                it is set to \c false. By default, it is set to \c true.
+
+            \li \c mandatory is set to \c true if this widget must have a value
+                for the \uicontrol Next button to become enabled. By default, it
+                is set to \c true.
+
+            \li \c span is set to hide the label and to span the form. By
+                default, it is set to \c false. For more information, see
+                \l{Using Variables in Wizards}.
+
+       \endlist
+
+       The additional settings available for a particular widget are described
+       in the following sections.
+
+    \endlist
+
+    \section2 Check Box
+
+    \code
+    {
+        "name": "IncludeQObject",
+        "trDisplayName": "Include QObject",
+        "type": "CheckBox",
+        "data":
+        {
+            "checkedValue": "QObject",
+            "uncheckedValue": "",
+            "checked": "%{JS: ('%{BaseCB}' === 'QObject' ) ? 'yes' : ''}"
+        }
+    },
+    \endcode
+
+    \list
+
+        \li \c checkedValue specifies the value to set when the check box is
+            enabled. By default, set to \c 0.
+
+        \li \c uncheckedValue specifies the value to set when the check box is
+            disabled. By default, set to \c 1.
+
+         \li \c checked is set to \c true if the check box is enabled, otherwise
+             \c{false}.
+
+    \endlist
+
+    \section2 Combo Box
+
+    \code
+    {
+        "name": "BaseCB",
+        "trDisplayName": "Base class:",
+        "type": "ComboBox",
+        "data":
+        {
+            "items": [ { "trKey": "<Custom>", "value": "" },
+                       "QObject", "QWidget", "QMainWindow", "QDeclarativeItem", "QQuickItem" ]
+        }
+    },
+    \endcode
+
+    \list
+
+        \li \c items specifies a list of items to put into the combo box. The
+            list can contain both JSON objects and plain strings. For JSON
+            objects, define \c trKey and \c value pairs, where the \c trKey is
+            the list item visible to users and \c value contains the data
+            associated with the item.
+
+        \li \c index specifies the index to select when the combo box is
+            enabled. By default, it is set to \c 0.
+
+        \li \c disabledIndex specifies the index to show if the combo box is
+            disabled.
+
+    \endlist
+
+    \section2 Label
+
+    \code
+    {
+    "name": "LabelQQC_1_0",
+        "type": "Label",
+        "span": true,
+        "visible": "%{( '%{CS}' === 'QQC_1_0' ) ? 'yes' : ''}",
+        "data":
+        {
+            "wordWrap": true,
+            "trText": "Creates a deployable Qt Quick 2 application using Qt Quick Controls. Requires Qt 5.1 or newer."
+        }
+    },
+    \endcode
+
+    \list
+
+        \li \c wordWrap is set to \c true to enable word wrap. By default, it is
+             set to \c{false}.
+
+        \li \c trText contains the label text to display.
+
+    \endlist
+
+    \section2 Line Edit
+
+    \code
+    {
+        "name": "Class",
+        "trDisplayName": "Class name:",
+        "mandatory": true,
+        "type": "LineEdit",
+        "data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" }
+    },
+    {
+        "name": "BaseEdit",
+        "type": "LineEdit",
+        "enabled": "%{JS: ( '%{BaseCB}' === '' ) ? 'yes' : ''}",
+        "mandatory": false,
+        "data":
+        {
+            "trText": "%{BaseCB}",
+            "trDisabledText": "%{BaseCB}"
+        }
+    },
+    \endcode
+
+    \list
+
+        \li \c trText specifies the default text to display.
+
+        \li \c trDisabledText specifies the text to display in a disabled field.
+
+        \li \c trPlaceholder specifies the placeholder text.
+
+        \li \c validator specifies a QRegularExpression to validate the line
+            edit against.
+
+        \li \c fixup specifies a variable that is used to fix up the string.
+            For example, to turn the first character in the line edit to upper
+            case.
+
+    \endlist
+
+    \section2 Path Chooser
+
+    \code
+    {
+        "name": "Path",
+        "type": "PathChooser",
+        "trDisplayName": "Path:",
+        "mandatory": true,
+        "data":
+        {
+            "kind": "existingDirectory",
+            "basePath": "%{InitialPath}",
+            "path": "%{InitialPath}"
+        }
+    },
+    \endcode
+
+    \list
+
+        \li \c path specifies the selected path.
+
+        \li \c basePath specifies a base path that lookups are relative to.
+
+        \li \c kind defines what to look for: \c existingDirectory,
+            \c directory, \c file, \c saveFile, \c existingCommand, \c command,
+            or \c any.
+
+    \endlist
+
+    \section2 Spacer
+
+    \code
+    {
+        "name": "Sp1",
+        "type": "Spacer",
+        "data":
+        {
+            "factor": 2
+        }
+    },
+    \endcode
+
+    The \c factor setting specifies the factor (an integer) to multiply the
+    layout spacing for this spacer.
+
+    \section2 Text Edit
+
+    \code
+    {
+        "name": "TextField",
+        "type": "TextEdit",
+        "data" :
+        {
+            "trText": "This is some text",
+            "richText": true
+        }
+    }
+    \endcode
+
+    \list
+
+        \li \c trText specifies the text to display.
+
+        \li \c trDisabledText specifies the text to display when the text edit
+            is disabled.
+
+        \li \c richText is set to \c true for rich text, otherwise \c{false}.
+
+    \endlist
+
+*/
diff --git a/doc/src/projects/creator-projects-custom-wizards-xml.qdoc b/doc/src/projects/creator-projects-custom-wizards-xml.qdoc
index bc4ff8da7e..7e386023ca 100644
--- a/doc/src/projects/creator-projects-custom-wizards-xml.qdoc
+++ b/doc/src/projects/creator-projects-custom-wizards-xml.qdoc
@@ -24,7 +24,7 @@
 
 /*!
     \contentspage {Qt Creator Manual}
-    \previouspage creator-project-wizards.html
+    \previouspage creator-project-wizards-json.html
     \page creator-project-wizards-xml.html
     \nextpage creator-version-control.html
 
@@ -33,55 +33,29 @@
     To display the XML-based example wizards in \QC, rename wizard_sample.xml as wizard.xml in the
     \c {\share\qtcreator\templates\wizards\helloworld} and
     \c {\share\qtcreator\templates\wizards\listmodel} folders. After
-    you restart \QC, the \gui {Custom Classes}
-    and \gui {Custom Projects} categories (1) appear in the \gui New dialog. For
+    you restart \QC, the \uicontrol {Custom Classes}
+    and \uicontrol {Custom Projects} categories (1) appear in the \uicontrol New dialog. For
     each category, an icon (2), a display name (3), and a description (4) are
     displayed.
 
     \image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes"
 
-    A custom wizard defines the user interface of a wizard page. The values the
-    user enters in the wizard are assigned field names. Field name and value
-    pairs are then passed to the file creation process. File creation can happen
-    in the following ways:
+    Files can be generated by using either \l{Processing Template Files}
+    {templates} or \l{Using Generator Scripts}{generator scripts}, where a
+    script is called to create the files.
 
-    \list 1
-
-        \li Template-based, where source files that contain placeholders for
-            the field names are provided. During processing, the placeholders
-            are replaced by the values from the wizard page. Optionally,
-            modifier characters are applied. For more information, see
-            \l{Processing Template Files}.
-
-        \li Generator script, where a script is called to create the files.
-
-            \note This option mainly exists to accommodate existing generator
-            scripts or cases where complicated algorithmic logic is required
-            when generating files. Writing cross-platform scripts is inherently
-            difficult, and therefore, it is not recommended for new wizards. For
-            more information, see \l{Using Generator Scripts}.
-
-    \endlist
-
-    Custom wizards are located in subdirectories of the following directories:
-
-    \list
-
-        \li \c{share/qtcreator/templates/wizards}
-
-        \li the local user's configuration folder,
-            \c{$HOME/.config/QtProject/qtcreator/templates/wizards}
-
-        \li \c{%APPDATA%\QtProject\qtcreator\templates\wizards}
-
-    \endlist
+    \note The generator option mainly exists to accommodate existing generator
+    scripts or cases where complicated algorithmic logic is required when
+    generating files. Writing cross-platform scripts is inherently difficult,
+    and therefore, it is not recommended for new wizards.
 
-    They contain an XML configuration file called wizard.xml, the template
-    source files, and optionally, the generator script.
+    XML-based wizard template directories contain an XML configuration file
+    called  wizard.xml, the template source files, and optionally, the generator
+    script.
 
-    \section1 Creating Project Wizards
+    \section1 Creating XML-Based Project Wizards
 
-    To create a project wizard:
+    To create an XML-based project wizard:
 
     \list 1
 
@@ -91,7 +65,7 @@
         \li Modify the wizard_example.xml file.
 
         \li The following code determines the type of the wizard and its place
-            in the \gui New dialog:
+            in the \uicontrol New dialog:
 
             \code
 
@@ -120,16 +94,16 @@
             \li \c id is the unique identifier for your wizard. The letter
                 specifies the position of the wizard within the \c category. The
                 HelloWorld wizard appears as the first wizard in the second
-                category in the \gui New dialog.
+                category in the \uicontrol New dialog.
 
             \li \c category is the category in which to place the wizard in the
                 list. The letter specifies the position of the category in the
-                list in the \gui New dialog.
+                list in the \uicontrol New dialog.
 
         \endlist
 
         \li The following code specifies the icon and text that appear in the
-            \gui New dialog:
+            \uicontrol New dialog:
 
             \code
 
@@ -145,8 +119,8 @@
 
         \list
 
-            \li \c displayCategory appears in the \gui New dialog, under
-                \gui Projects.
+            \li \c displayCategory appears in the \uicontrol New dialog, under
+                \uicontrol Projects.
 
             \li \c icon appears next to the \c displayName in the middle panel
                 when \c displayCategory is selected.
@@ -187,7 +161,7 @@
 
                 \li \c target specifies the new filename for the file. The
                     \c {%ProjectName%} variable is replaced with the string that
-                    users specify in the \gui Name field on the first page of
+                    users specify in the \uicontrol Name field on the first page of
                     the wizard.
 
                 \li \c openproject indicates that the file is a project file
@@ -560,12 +534,12 @@
             to \c %Path%. For project wizards, it is \c %Path%/%ProjectName%.
 
         \li \c {%CppSourceSuffix%} is replaced by the default source suffix,
-            which is defined in \QC in \gui {Tools > Options > C++ >
+            which is defined in \QC in \uicontrol {Tools > Options > C++ >
             File Naming}. For example, if users enter \b MyClass, the
             filename becomes myclass.cpp when the project is created.
 
         \li \c {%CppHeaderSuffix%} is replaced by the default header suffix,
-            which is also defined in \gui {File Naming}.
+            which is also defined in \uicontrol {File Naming}.
 
         \li \c {%CurrentDate%} is replaced by the current date in the format
             \c {YYYY-MM-DD} as specified by ISO 8601.
diff --git a/doc/src/projects/creator-projects-custom-wizards.qdoc b/doc/src/projects/creator-projects-custom-wizards.qdoc
index f0b1b183b1..fc57ff4c7f 100644
--- a/doc/src/projects/creator-projects-custom-wizards.qdoc
+++ b/doc/src/projects/creator-projects-custom-wizards.qdoc
@@ -26,17 +26,23 @@
     \contentspage {Qt Creator Manual}
     \previouspage creator-project-qmake-libraries.html
     \page creator-project-wizards.html
-    \nextpage creator-project-wizards-xml.html
+    \nextpage creator-project-wizards-json.html
 
     \title Adding New Custom Wizards
 
     If you have a team working on a large application or several applications,
-    you might want to standardize the way the team members create projects
-    and classes.
+    you might want to standardize the way the team members create projects,
+    classes, and files.
 
     You can copy the wizard templates in the template folders to create your own
-    project and class wizards. They are displayed in the \uicontrol New dialog that
-    opens when you choose \uicontrol {File > New File or Project}.
+    project, class, and file wizards. They are displayed in the \uicontrol New
+    dialog that opens when you choose \uicontrol {File > New File or Project}.
+
+    A custom wizard defines the user interface of a wizard page. The values the
+    user enters in the wizard are assigned field names. Field name and value
+    pairs are then passed to the file creation process.
+
+    \section1 Wizard Types
 
     In a project wizard, you can specify the files needed in a project.
     You can add wizard pages to allow developers to specify settings for the
@@ -45,10 +51,51 @@
     In a class wizard, you can allow developers to specify the class name, base
     class, and header and source files for the class.
 
+    In a file wizard, you can allow developers to specify the type and location
+    of the file.
+
     You can create either JSON-based or XML-based wizards. We recommend creating
-    JSON-based wizards for new projects.
+    JSON-based wizards for new projects. For more information, see:
 
     \list
+        \li \l{Adding JSON-Based Wizards}
         \li \l{Adding XML-Based Wizards}
     \endlist
+
+    The following table summarizes the wizards you can create:
+
+    \table
+        \header
+            \li Wizard Type
+            \li JSON-Based
+            \li XML-Based
+        \row
+            \li Class
+            \li \image ok
+            \li \image ok
+        \row
+            \li File
+            \li \image ok
+            \li \image ok
+        \row
+            \li Project
+            \li \image ok
+            \li \image ok
+    \endtable
+
+    \section1 Locating Wizards
+
+    Wizards are located in subdirectories of the following directories:
+
+    \list
+
+        \li \c{share/qtcreator/templates/wizards}
+
+        \li the local user's configuration folder,
+            \c{$HOME/.config/QtProject/qtcreator/templates/wizards}
+
+        \li \c{%APPDATA%\QtProject\qtcreator\templates\wizards}
+
+    \endlist
+
 */
diff --git a/doc/src/qtcreator.qdoc b/doc/src/qtcreator.qdoc
index bdd124d1e6..3f3090b763 100644
--- a/doc/src/qtcreator.qdoc
+++ b/doc/src/qtcreator.qdoc
@@ -144,6 +144,7 @@
                 \li \l{Adding Libraries to Projects}
                 \li \l{Adding New Custom Wizards}
                 \list
+                    \li \l{Adding JSON-Based Wizards}
                     \li \l{Adding XML-Based Wizards}
                 \endlist
             \endlist