diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 91b007d17d..ef76160520 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,3 +1,3 @@ # At least one of the code owners below will be required on each PR: -* @sibille @mvegaca @dgomezc @trevorNgo @jcoc611-microsoft @piotrmark @MehaKaushik @Tanya0609 @javieraparisivaldes +* @sibille @mvegaca @dgomezc @trevorNgo @jcoc611-microsoft @piotrmark @MehaKaushik @Tanya0609 @prupipho diff --git a/.gitignore b/.gitignore index cab32320da..67dcd097f0 100644 --- a/.gitignore +++ b/.gitignore @@ -52,7 +52,6 @@ BenchmarkDotNet.Artifacts/ project.lock.json project.fragment.lock.json artifacts/ -**/Properties/launchSettings.json # StyleCop StyleCopReport.xml @@ -369,3 +368,5 @@ src/extension/src/corets-cli/win32/ # Template tests template_test/ +src/client/src/translations/en.json +src/client/src/translations/whitelist_en.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f343a2376..6b01c3e072 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,9 @@ # Contributing to Web Template Studio -The foundation of _Web Template Studio_ is to get developers up and running with a new +The foundation of *Web Template Studio* is to get developers up and running with a new web app that incorporates cloud services on Azure as fast as possible. -Using Web Template Studio, a developer can select their preferred web +Using *Web Template Studio*, a developer can select their preferred web frameworks, pages and Azure cloud services to generate boilerplate code for their web app. The generated code not only follows best practices and design guidelines, but also includes comments to guide the developer through the logic and adding functionality to @@ -72,9 +72,7 @@ We encourage developers to consider the following guidelines when submitting pul ## Naming and styling conventions -All code that gets merged in must be formatted with [Prettier](https://prettier.io/). Also, -we use [TSLint](https://palantir.github.io/tslint/) to lint our TypeScript code and [ESLint](https://eslint.org/) -for JavaScript. +All code that gets merged in must be formatted with [Prettier](https://prettier.io/). Also, we use [ESLint](hhttps://eslint.org/) to lint our code. ## Documentation diff --git a/README.md b/README.md index f24cd61e87..d4b113e270 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ Platforms Supported: MacOSX, Linux, Windows Project Status: Active – The project has reached a stable, usable state and is being actively developed. License: We are using the MIT License We are welcoming PRS! -Microsoft Web Template Studio (_WebTS_) is a Visual Studio Code Extension that accelerates the creation of new web applications using a +Microsoft *Web Template Studio* (aka *WebTS*) is a Visual Studio Code Extension that accelerates the creation of new web applications using a wizard-based experience. WebTS enables developers to generate boilerplate code for a web application -by choosing between different front-end frameworks, back-end frameworks, pages and cloud services. +by choosing between different frontend frameworks, backend frameworks, pages and cloud services. The resulting web app is well-formed, readable code that incorporates cloud services on Azure while implementing proven patterns and best practices. Sprinkled throughout the generated code we have links to Docs to provide useful insights. WebTS was created using TypeScript and React. Different combinations of generated code @@ -17,33 +17,33 @@ are merged together by [Core Template Studio](https://github.com/Microsoft/CoreT | dev | [![Build Status](https://winappstudio.visualstudio.com/Vegas/_apis/build/status/WebTemplateStudio%20-%20CI%20and%20Deploy?branchName=dev)](https://winappstudio.visualstudio.com/Vegas/_build/latest?definitionId=158&branchName=dev) | | release | [![Build Status](https://winappstudio.visualstudio.com/Vegas/_apis/build/status/webTS/webts.staging.version.create?branchName=release)](https://winappstudio.visualstudio.com/Vegas/_build/latest?definitionId=161&branchName=release) | -# Documentation +## Documentation Web Template Studio (WebTS) documentation is divided into three areas. -## General +### General Everyone should read these. - [Installing the extension](/docs/install.md) - [Core Concepts](/docs/concepts.md) -## Using WebTS to build apps +### Using WebTS to build apps These will help if using WebTS to build apps. -- [Front-end frameworks](docs/generated-apps/frontend-frameworks/readme.md) -- [Back-end frameworks](docs/generated-apps/backend-frameworks/readme.md) +- [Frontend frameworks](docs/generated-apps/frontend-frameworks/readme.md) +- [Backend frameworks](docs/generated-apps/backend-frameworks/readme.md) - [Pages](docs/generated-apps/pages/readme.md) - [Services](docs/generated-apps/services/readme.md) - [Deployment of the generated apps](docs/generated-apps/deployment.md) -## Working on WebTS +### Working on WebTS These will help if you want to know more about WebTS or contribute to the project. - [Application Arquitecture](docs/contributing/application-architecture.md) - [Getting started with the codebase](/docs/contributing/getting-started-developers.md) -- [Templates](./contributing/templates.md) -- [Accessibility](./contributing/accessibility.md) +- [Templates](./docs/contributing/templates.md) +- [Accessibility](./docs/contributing/accessibility.md) ## SHA256 @@ -58,25 +58,25 @@ To verify the integrity of the package, download the vsix from the Marketplace, ### Create a new project - Open **VSCode** -- Press `Ctrl + Shift + P` in Windows/Linux or `Shift ⇧ + Command ⌘ + P` in Mac to open VSCode's extension launcher +- Press `Ctrl + Shift ⇧ + P` in Windows/Linux or `Command ⌘ + Shift ⇧ + P` in Mac to open VSCode's extension launcher - Type/Select `Web Template Studio: Launch` and press `Enter` to launch the extension ### Deploy the generated project - Open **VSCode** - Open the generated project -- Press `Ctrl + Shift + P` in Windows/Linux or `Shift ⇧ + Command ⌘ + P` in Mac to open VSCode's extension launcher +- Press `Ctrl + Shift ⇧ + P` in Windows/Linux or `Command ⌘ + Shift ⇧ + P` in Mac to open VSCode's extension launcher - Type/Select `Web Template Studio: Deploy App` and press `Enter` to begin the deployment ## Example Scenario I need a full-stack web app that is deployed on Azure App Service Web App. -![Readme-app-azure-screenshot](./docs/resources/readme-app-azure-screenshot.png) +App with Azure Services ## Features -Web Template Studio approaches full-stack web app creation using the following three attribute sets: +*Web Template Studio* approaches full-stack web app creation using the following three attribute sets: - **Frameworks**: First, which frameworks do you want to use for your frontend and backend? We currently support three frameworks for frontend: _[React](https://reactjs.org/)_, _[Angular](https://angular.io/)_, _[Vue.js](https://vuejs.org/)_ and four frameworks for backend: _[Node](https://nodejs.org/en/)_, _[Flask](http://flask.pocoo.org/)_, _[Moleculer](https://moleculer.services/)_ and _[ASP.NET Core](https://dotnet.microsoft.com/apps/aspnet)_. We also provide a dependency checker to make sure you have the required version of Node, Python and/or .NET Core installed. - **App pages**: Next, to accelerate app creation, we provide a number of app page templates that you can use to add common UI pages into your new app. The current page templates include: _blank page_, common layouts (*e.g., master detail) and pages that implement common patterns (*e.g., grid, list). Using the wizard, add as many of the pages as you need, providing a name for each one, and we'll generate them for you. @@ -126,4 +126,4 @@ The extension does [log basic telemetry](docs/telemetry.md) for what is being se ## Acknowledgments -Microsoft Web Template Studio was [initially created by Microsoft Garage interns](docs/acknowledgments.md). We hope many more continue with the project +Microsoft *Web Template Studio* was [initially created by Microsoft Garage interns](docs/acknowledgments.md). We hope many more continue with the project. diff --git a/_build/Extension-ReplaceNames.ps1 b/_build/Extension-ReplaceNames.ps1 index 795e56e8e6..b48d6d7853 100644 --- a/_build/Extension-ReplaceNames.ps1 +++ b/_build/Extension-ReplaceNames.ps1 @@ -1,39 +1,60 @@ [CmdletBinding()] Param( - [Parameter(Mandatory=$True,Position=1)] - [string]$vsixPackageJson, + [Parameter(Mandatory = $True, Position = 1)] + [string]$extensionPath, - [Parameter(Mandatory=$True,Position=2)] + [Parameter(Mandatory = $True, Position = 2)] [string]$vsixName, - [Parameter(Mandatory=$True,Position=3)] + [Parameter(Mandatory = $True, Position = 3)] [string]$vsixDisplayName, - [Parameter(Mandatory=$True,Position=4)] + [Parameter(Mandatory = $True, Position = 4)] [string]$versionNumber, - [Parameter(Mandatory=$True,Position=5)] - [string]$aikey + [Parameter(Mandatory = $True, Position = 5)] + [string]$aikey, + + [Parameter(Mandatory = $True, Position = 6)] + [string]$commandCategory, + + [Parameter(Mandatory = $True, Position = 7)] + [string]$wizardLaunchCommand, + + [Parameter(Mandatory = $True, Position = 8)] + [string]$deployAppCommand ) function Clear-WhiteSpace ($Text) { "$($Text -replace "(`t|`n|`r)"," " -replace "\s+"," ")".Trim() } ## SET NAME AND VERSION IN VSIX Package json -if($vsixName){ - Write-Host - Write-Host "Setting name and version in VSIX package json" +if ($vsixName) { + + $vsixPackageJson = Join-Path $extensionPath "package.json" + $vsixPackageNlsJson = Join-Path $extensionPath "package.nls.json" + $vsixPackagei18nJson = Join-Path $extensionPath "locales/en/package.i18n.json" + $vsixExtensionTsFile = Join-Path $extensionPath "src/extension.ts" + + # REPLACE Version, Name, DisplayName and commands IN package.json + if (Test-Path($vsixPackageJson)) { + + Write-Host + Write-Host "Setting name,version and commands in VSIX package json" - if(Test-Path($vsixPackageJson)){ $packagejsonContent = Get-Content $vsixPackageJson | ConvertFrom-Json $LocalIdentity = $packagejsonContent.name $localDisplayName = $packagejsonContent.displayName $localVersionNumber = $packagejsonContent.version $localAiKey = $packagejsonContent.aiKey + $localwizardLaunchCommand = $packagejsonContent.contributes.commands[0].command + $localdeployAppCommand = $packagejsonContent.contributes.commands[1].command Write-Host "Replacing $LocalIdentity by $vsixName" Write-Host "Replacing $localDisplayName by $vsixDisplayName" Write-Host "Replacing $localVersionNumber by $versionNumber" + Write-Host "Replacing $localwizardLaunchCommand by $wizardLaunchCommand" + Write-Host "Replacing $localdeployAppCommand by $deployAppCommand" $content = (Get-Content -path $vsixPackageJson -Raw) @@ -41,16 +62,73 @@ if($vsixName){ $content = $content -replace [regex]::Escape("$localDisplayName") , "$vsixDisplayName" $content = $content -replace "$localVersionNumber" , "$versionNumber" $content = $content -replace "$localAiKey" , "$aikey" + $content = $content -replace "$localwizardLaunchCommand" , "$wizardLaunchCommand" + $content = $content -replace "$localdeployAppCommand" , "$deployAppCommand" [System.IO.File]::WriteAllLines($vsixPackageJson, $content, [System.Text.UTF8Encoding]($False)) - Write-Host "$resolvedPath - Version, Name & DisplayName applied ($versionNumber, $vsixName, $vsixDisplayName)" + Write-Host "$resolvedPath - Version, Name, DisplayName and commands applied ($versionNumber, $vsixName, $vsixDisplayName, $wizardLaunchCommand, $deployAppCommand)" } - else{ + else { throw "No VSIX package json file found." } + + # REPLACE command category IN package.nls.json + if (Test-Path($vsixPackageNlsJson)) { + + $jsonFile = Get-Content $vsixPackageNlsJson | ConvertFrom-Json + $localCommandCategory = $jsonFile.'webTemplateStudioExtension.commands.wts' + Write-Host "Replacing $localCommandCategory command category by $commandCategory in package.nls.json" + + $content = (Get-Content -path $vsixPackageNlsJson -Raw) + $content = $content -replace [regex]::Escape("$localCommandCategory") , "$commandCategory" + + [System.IO.File]::WriteAllLines($vsixPackageNlsJson, $content, [System.Text.UTF8Encoding]($False)) + Write-Host "$resolvedPath - category applied ($commandCategory)" + } + else { + throw "No VSIX package.nls.json file found." + } + + # REPLACE command category IN package.i18n.json + if (Test-Path($vsixPackagei18nJson)) { + + $jsonFile = Get-Content $vsixPackagei18nJson | ConvertFrom-Json + $localCommandCategory = $jsonFile.'webTemplateStudioExtension.commands.wts' + Write-Host "Replacing $localCommandCategory command category by $commandCategory in package.i18n.json" + + $content = (Get-Content -path $vsixPackagei18nJson -Raw) + $content = $content -replace [regex]::Escape("$localCommandCategory") , "$commandCategory" + + [System.IO.File]::WriteAllLines($vsixPackagei18nJson, $content, [System.Text.UTF8Encoding]($False)) + Write-Host "$resolvedPath - category applied ($commandCategory)" + } + else { + throw "No VSIX package.i18n.json file found." + } + + # REPLACE commands IN extension.ts + if (Test-Path($vsixExtensionTsFile)) { + + $localWizardLaunchCommand = "webTemplateStudioExtension.wizardLaunch.local" + $localdeployAppCommand = "webTemplateStudioExtension.deployApp.local" + + Write-Host + Write-Host "Replacing $localWizardLaunchCommand by $wizardLaunchCommand in extension.ts" + Write-Host "Replacing $localdeployAppCommand by $deployAppCommand in extension.ts" + + $content = (Get-Content -path $vsixExtensionTsFile -Raw) + $content = $content -replace [regex]::Escape("$localWizardLaunchCommand") , "$wizardLaunchCommand" + $content = $content -replace [regex]::Escape("$localdeployAppCommand") , "$deployAppCommand" + + [System.IO.File]::WriteAllLines($vsixExtensionTsFile, $content, [System.Text.UTF8Encoding]($False)) + Write-Host "$resolvedPath - Commands applied ($localWizardLaunchCommand, $localdeployAppCommand)" + } + else { + throw "No VSIX extension.ts file found." + } } -else{ +else { throw "Identity is mandatory." } diff --git a/_build/build-all.sh b/_build/build-all.sh index 431015acab..d42a428593 100644 --- a/_build/build-all.sh +++ b/_build/build-all.sh @@ -7,10 +7,10 @@ red='\033[0;31m' nc='\033[0m' # Build the client -sh ./build-client.sh +bash ./build-client.sh # Build the cli in debug -sh ./build-coretscli.sh "debug" +bash ./build-coretscli.sh "debug" -# Build the extension -sh ./build-extension.sh \ No newline at end of file +# Build the extension +bash ./build-extension.sh \ No newline at end of file diff --git a/_build/build-coretscli-and-client.sh b/_build/build-coretscli-and-client.sh index d4aea077bb..6edf24b294 100644 --- a/_build/build-coretscli-and-client.sh +++ b/_build/build-coretscli-and-client.sh @@ -7,7 +7,7 @@ red='\033[0;31m' nc='\033[0m' # Build the client -sh ./build-client.sh +bash ./build-client.sh # Build the cli in debug -sh ./build-coretscli.sh "debug" +bash ./build-coretscli.sh "debug" diff --git a/docs/README.md b/docs/README.md index 9452c6ab9e..f1bb42ebb9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,5 @@ # Documentation -Web Template Studio (WebTS) documentation is divided into three areas. +*Web Template Studio* (WebTS) documentation is divided into three areas. ## General @@ -11,17 +11,17 @@ Everyone should read these. ## Using WebTS to build apps These will help if you are using WebTS to build apps. -- [Front-end frameworks](docs/generated-apps/frontend-frameworks/readme.md) -- [Back-end frameworks](docs/generated-apps/backend-frameworks/readme.md) -- [Pages](docs/generated-apps/pages/readme.md) -- [Services](docs/generated-apps/services/readme.md) -- [Deployment of the generated apps](docs/generated-apps/deployment.md) +- [Frontend frameworks](/docs/generated-apps/frontend-frameworks) +- [Backend frameworks](/docs/generated-apps/backend-frameworks) +- [Pages](/docs/generated-apps/pages) +- [Services](/docs/generated-apps/services) +- [Deployment of the generated apps](/docs/generated-apps/deployment.md) ## Working on WebTS These will help if you want to know more about WebTS or contribute to the project. -- [Application Arquitecture](docs/contributing/application-architecture.md) +- [Application Arquitecture](/docs/contributing/application-architecture.md) - [Getting started with the codebase](/docs/contributing/getting-started-developers.md) - [Templates](./contributing/templates.md) - [Accessibility](./contributing/accessibility.md) diff --git a/docs/acknowledgments.md b/docs/acknowledgments.md index d35f416319..21e692e1b3 100644 --- a/docs/acknowledgments.md +++ b/docs/acknowledgments.md @@ -1,6 +1,6 @@ # Acknowledgments -Microsoft Web Template Studio was initially built by two great groups of interns from the Microsoft Garage. This full list of individuals that helped build the project. +Microsoft *Web Template Studio* was initially built by two great groups of interns from the Microsoft Garage. This full list of individuals that helped build the project. ## First group (first quarter of 2019): diff --git a/docs/concepts.md b/docs/concepts.md index d8edb420cd..70e1232a7b 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,22 +1,22 @@ # Concepts of Web Template Studio -This section outlines the main concepts and definitions used in Web Template Studio. +This section outlines the main concepts and definitions used in *Web Template Studio*. ## Main concepts -Web Template Studio is divided in the following main elements: +*Web Template Studio* is divided in the following main elements: -- **Extension**: Refers to the Visual Studio Code Extension project, which, once installed, allows users to have an improved experience when creating a new Web Application from the "Web Template Studio: Launch" command. The extension is written in typescript. -- **Wizard**: Refers to the WebTS client project, where all user interaction occurs after launching Web Template Studio. The Wizard guides the user through some steps to create the desired project. It allows the user to select from the available frameworks, pages and Azure Cloud Services. The wizard is created with React Typescript and is displayed through the React Panel. +- **Extension**: Refers to the Visual Studio Code Extension project, which, once installed, allows users to have an improved experience when creating a new Web Application from the `Web Template Studio: Launch` command. The extension is written in typescript. +- **Wizard**: Refers to the WebTS client project, where all user interaction occurs after launching *Web Template Studio*. The Wizard guides the user through some steps to create the desired project. It allows the user to select from the available frameworks, pages and Azure Cloud Services. The wizard is created with React Typescript and is displayed through the React Panel. - **Core Template Studio and Core Template Studio CLI**: Refers to the .NET Core executable that handles all of the template synchronization and code generation (composition, generation + postaction execution). The CLI is the entry point for executing commands on Core Template Studio executable. CoreTS CLI is a self-contained .NET Core 3.1 application. -- **Template** - A template contains code with metadata. The metadata will contain the following template information: name, description, licensing, remarks, programming language, type, etc. The template definition is based on [dotnet Template Engine](https://github.com/dotnet/templating). [More details on templates](/contributing/templates.md) +- **Template**: A template contains code with metadata. The metadata will contain the following template information: name, description, licensing, remarks, programming language, type, etc. The template definition is based on [dotnet Template Engine](https://github.com/dotnet/templating). [More details on templates](../contributing/templates.md) ## Other Terminology -- **WinTS/Windows Template Studio** - Refers to the Visual Studio extension used to generate boilerplate code for UWP applications. -- **Contributing Developer** - A developer who is contributing to this open source project. -- **User** - A developer who is using the WebTS extension. -- **MockUps** - A sample project that contains the code as it will be generated by the engine. MockUps are used to discuss how the generated code should look like before doing the templates. +- **WebTS/Web Template Studio**: Refers to the Visual Studio Code extension used to generate boilerplate code for Web applications. +- **Contributing Developer**: A developer who is contributing to this open source project. +- **User**: A developer who is using the WebTS extension. +- **MockUps**: A sample project that contains the code as it will be generated by the engine. MockUps are used to discuss how the generated code should look like before doing the templates. --- @@ -26,4 +26,4 @@ Web Template Studio is divided in the following main elements: - [Application Arquitecture](./contributing/application-architecture.md) - [Getting started with the WebTS codebase](./contributing/getting-started-developers.md) - [Templates](./contributing/templates.md) -- [All docs](./readme.md) +- [All docs](./README.md) diff --git a/docs/contributing/accessibility.md b/docs/contributing/accessibility.md index 68a2a6f356..f9054443f8 100644 --- a/docs/contributing/accessibility.md +++ b/docs/contributing/accessibility.md @@ -40,3 +40,7 @@ The following test results hold as of July 2, 2020. More than one way is available to locate a web page within a set of web pages except where the Web Page is the result of, or a step in, a process. In order to make the generated code as easy to build off of as possible the only form of navigation included in the generated code is the navbar. Developers who build off of the generated code are encouraged to add a second form of navigation (preferably site search) to ensure that the web app is fully compliant with WCAG 2.0 Level AA Success Criteria. + +## Learn more + +- [All docs](../README.md) \ No newline at end of file diff --git a/docs/contributing/application-architecture.md b/docs/contributing/application-architecture.md index 03a0f79397..a145ba20c8 100644 --- a/docs/contributing/application-architecture.md +++ b/docs/contributing/application-architecture.md @@ -1,59 +1,67 @@ # Application Architecture -Web Template Studio is a [Visual Studio Code Extension](https://code.visualstudio.com/api) that has three major components: +*Web Template Studio* is a [Visual Studio Code Extension](https://code.visualstudio.com/api) that has three major components. All of them are included in *Web Template Studio* **vsix**: - - The extension's backend (referred to as the [extension](https://github.com/Microsoft/WebTemplateStudio/tree/dev/src/extension)), which is written in [Typescript](https://www.typescriptlang.org/). - - The front-end wizard (referred to as the [client](https://github.com/Microsoft/WebTemplateStudio/tree/dev/src/client)), written in [React](https://reactjs.org/) and [Typescript](https://www.typescriptlang.org/). - - Generation engine (referred to as [Core Template Studio](https://github.com/Microsoft/CoreTemplateStudio)) written in [.NET Core](https://dotnet.microsoft.com/download). - -![Architecture Diagram](../resources/webts-architecture-diagram.png) + 1. The [extension's backend](#extension) (referred to as the [extension](../../src/extension)). Written in [Typescript](https://www.typescriptlang.org/). + 1. The [frontend wizard](#client) (referred to as the [client](../../src/client)). Written in [React](https://reactjs.org/) and [Typescript](https://www.typescriptlang.org/). + 1. The [generation engine](#Core-template-studio) (referred to as [Core Template Studio](https://github.com/Microsoft/CoreTemplateStudio)) written in [.NET Core](https://dotnet.microsoft.com/download). + + +Architecture Diagram +
-All three components are included in Web Template Studio vsix. ## Extension -The extension is the main part of Web Template Studio. It has been built using the [Visual Studio Code Extensibility API](https://code.visualstudio.com/api) to build extensions. It is responsible for launching the client in a Visual Studio Code tab and for communication between the wizard client and the Core Template Studio CLI. It is also responsible for creating the Azure Services (App Service and CosmosDB Service) and the deployment the generated applications. +The extension is the main part of *Web Template Studio*. It has been built using the [Visual Studio Code Extensibility API](https://code.visualstudio.com/api) to build extensions. It is responsible for launching the client in a Visual Studio Code tab and for communication between the wizard client and the Core Template Studio CLI. It is also responsible for creating the Azure Services (App Service and CosmosDB Service) and the deployment of the generated applications. It contains two commands that can be called from Visual Studio Code: -- [webTemplateStudioExtension.wizardLaunch](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/extension.ts#L7-L11): This command is executed when we launch the "Web Template Studio: Launch" command from Visual Studio Code. It is responsible to start the Core Template Studio CLI in a `child_process`, synchronizing the templates and opening the wizard in a Visual Studio Code tab. While the wizard is open, it is also responsible for maintaining communication between the wizard client and the Core Template Studio CLI to obtain templates and generate projects. - -- [webTemplateStudioExtension.deployApp](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/extension.ts#L13-L18): This command is executed when we launch the "Web Template Studio: Deploy App" command from Visual Studio Code. It is responsible for deploying a generated application in Azure. Note: For this command to work properly, we need a web application generated with Web Template Studio opened and configured with an App Service. +- [webTemplateStudioExtension.wizardLaunch](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/extension.ts#L7-L11): This command is executed when we launch the `Web Template Studio: Launch` command from Visual Studio Code. It is responsible to start the Core Template Studio CLI in a `child_process`, synchronizing the templates and opening the wizard in a Visual Studio Code tab. While the wizard is open, it is also responsible for maintaining communication between the wizard client and the Core Template Studio CLI to obtain templates and generate projects. + +- [webTemplateStudioExtension.deployApp](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/extension.ts#L13-L18): This command is executed when we launch the `Web Template Studio: Deploy App` command from Visual Studio Code. It is responsible for deploying a generated application in Azure.
+**Note**: For this command to work properly, we need a web application generated with *Web Template Studio* opened and configured with an App Service. ## Client -The wizard client is the visual component of the extension. It is a [React](https://reactjs.org/) app that is compiled into JavaScript that gets injected into html, which then gets served using [VSCode's Webview API](https://code.visualstudio.com/api/extension-guides/webview). It is shown in a Visual Studio Code tab when the user executes the "Web Template Studio: Launch" extension command. +The wizard client is the visual component of the extension. It is a [React](https://reactjs.org/) app that is compiled into JavaScript that gets injected into html, which then gets served using [VSCode's Webview API](https://code.visualstudio.com/api/extension-guides/webview). It is shown in a Visual Studio Code tab when the user executes the `Web Template Studio: Launch` extension command. It is responsible for the interaction with the user and is responsible for collecting the name and route of the project, the selected frameworks, pages and services and sending them to the extension for processing with Core Template Studio. The wizard client keeps track of the state using [Redux](https://react-redux.js.org/). ### Color Themes -Web Template Studio supports Visual Studio Code's **light, dark, and high contrast theme**. You can press `Ctrl + K` in Windows/Linux or `Command ⌘ + K` then `Ctrl + T` in Windows/Linux or `Command ⌘ + T` to choose different color themes in Visual Studio Code. +*Web Template Studio* supports Visual Studio Code's **light, dark, and high contrast theme**. You can press `Ctrl + K` then `Ctrl + T` in Windows/Linux or `Command ⌘ + K` then `Command ⌘ + T` in Mac to choose different color themes in Visual Studio Code. -Example of Light Theme: + #### Example of Light Theme: ![image](../resources/webts-light-theme.png) -To support different color themes, VSCode CSS theme variables are used so that the webview matches the look and feel of a developer’s VSCode. VSCode's documentation on theme color can be found [here](https://code.visualstudio.com/api/references/theme-color). You can also look at the VSCode CSS variables for each theme by pressing `Ctrl + Shift + P` in Windows/Linux or `Shift ⇧ + Command ⌘ + P` in Visual Studio Code and then running the `Developer: Generate Color Theme From Current Settings` command. +#### Example of Dark Theme: +![image](../resources/webts-dark-theme.png) + +To support different color themes, VSCode CSS theme variables are used so that the webview matches the look and feel of a developer’s VSCode. VSCode's documentation on theme color can be found [here](https://code.visualstudio.com/api/references/theme-color). You can also look at the VSCode CSS variables for each theme by pressing `Ctrl + Shift ⇧ + P` in Windows/Linux or `Command ⌘ + Shift ⇧ + P` in Mac and then running the `Developer: Generate Color Theme From Current Settings` command. If you want to use these variables in the client, you have to follow a certain format. For example, if you want to apply VSCode's `"editor.background": "#252526"`, you would convert it to `var(--vscode-editor-background)` in the CSS file. More documentation can be found on the [webview API docs](https://code.visualstudio.com/api/extension-guides/webview#theming-webview-content). When the app is being run in the browser imitates these VSCode themes using `themes.css` and `themeslight.css` for dark and light mode respectively. Otherwise, if it is being ran in the extension, the CSS variables will map to VSCode directly. -## Generation Engine (Core Template Studio) +## Core Template Studio The Generation Engine is responsible for template synchronisation, get frameworks, get templates and generating projects. It consists of a [CLI](https://github.com/microsoft/CoreTemplateStudio/blob/dev/docs/getting-started-developers.md#cli-project) that receives requests from the extension and get processed by [Core Template Studio](https://github.com/microsoft/CoreTemplateStudio/). Once the request is processed, it returns the response in json format to the extension. For more Info see [Core Template Studio Docs](https://github.com/microsoft/CoreTemplateStudio/blob/dev/docs/getting-started-developers.md). + +# Communication + ## Extension and CLI Core Template Studio communication The communication between the extension and the Core Template Studio CLI is defined in the [coreTemplateStudio.ts](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/coreTemplateStudio.ts) file. This static class is responsible for starting/stopping the Core Template Studio CLI in a `child_process`, and managing the Core Template Studio CLI requests and responses (including notifications and errors). -It also exposes public functions to call the Core Template Studio CLI commands. Currently the functions offered by the [coreTemplateStudio](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/coreTemplateStudio.ts) class are: +It also exposes public functions to call the Core Template Studio CLI commands. Some of the main functions offered by the [coreTemplateStudio](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/coreTemplateStudio.ts) class are: ```js - sync(payload: ICommandPayload): Promise @@ -67,13 +75,13 @@ It also exposes public functions to call the Core Template Studio CLI commands. To execute a Core Template Studio CLI command from the extension we have to instantiate the [coreTemplateStudio](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/coreTemplateStudio.ts) class and execute the function that has the command we want to execute. - Example: + #### Example: ```js async getPages(): Promise { const coreTS = CoreTemplateStudio.GetExistingInstance(); const pages = await coreTS.getPages("projectType", "frontendFramework", "backendFramework"); - console.log(pages); + ... }; } ``` @@ -90,7 +98,8 @@ When the client wants to execute an extension command, it will call `vscode.post - command: extension command that should process the request. - payload: data that we send in the request. - Example: + +#### Example: ```js vscode.postMessage({ @@ -108,13 +117,13 @@ When the extension create the webview (that includes the client), the `routingMe The modules inherit from [WizardServant](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/wizardServant.ts) which is the class responsible for executing the function associated with each command, controlling errors and recording telemetry if necessary. -NOTE: In the development environment (running the app in the browser), the Visual Studio Code extension is not available for the client to interact with. The communication is mocked using the [mockVsCodeAPI.ts](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/client/src/mockData/mockVsCodeApi.ts), which uses the native `window.postMessage()` command to send messages to the application. +**Note**: In the development environment - when you run the app in the browser, the Visual Studio Code extension is not available for the client. The communication is mocked using the [mockVsCodeAPI.ts](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/client/src/mockData/mockVsCodeApi.ts), which uses the native `window.postMessage()` command to send messages to the application. ### Client receive from extension Messages sent from the extension are received in the `messageEventsFromExtension()` function in [App.tsx](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/client/src/App.tsx). This function configures an `addEventListener` to listen all messages sent from the extension and through a switch executes the necessary instructions according to the command received. -Example: + #### Example: ```js function messageEventsFromExtension(){ @@ -131,16 +140,16 @@ Example: } ``` -NOTE: currently, we are developing [extensionService.ts](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/client/src/utils/extensionService/extensionService.ts) that will handle communication between client and extension through promises and will offer a simple and centralized way to call extension commands and receive responses. +**Note**: The [extensionService.ts](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/client/src/utils/extensionService/extensionService.ts) file handle communication between the client and extension through promises and offers a simple and centralized way to call extension commands and receive responses. -### Extension to client +### Extension send to client -When the extension needs to send a request to the client, it will call `postMessageWebview()` function in [reactPanel.ts](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/reactPanel.ts). This function communicates with the webview (that contains the client), passing through parameters an object with the following properties: +When the extension needs to send a request to the client, it will call `postMessageWebview()` function in [reactPanel.ts](https://github.com/microsoft/WebTemplateStudio/blob/dev/src/extension/src/reactPanel.ts). This function communicates with the webview that contains the client, passing through parameters an object with the following properties: - command: extension command that processed the request. - payload: data that we send in the request. -Example: + #### Example: ```js reactPanelContext.postMessageWebview({ @@ -153,9 +162,14 @@ reactPanelContext.postMessageWebview({ } ``` +## Separating the UI from the Logic: +One of our main concerns is increasing the speed of the wizard and making it as light as possible.
+Therefore, the wizard does not perform any expensive computations, and does not make any API requests. Most of these actions are done in the extension.
+So as the user navigates through the wizard, the selections are validated in the wizard and stored. When the user clicks generate, these selections will then be sent to the extension, which will deal with them synchronously.
+The extension starts with the templates, which will get sent to the [Engine](https://github.com/Microsoft/CoreTemplateStudio).
+Once it´s generated, the extension will use the Azure SDK to deploy the resources if the user selected any while creating their application. +## Learn more -## Separating the UI from the Logic: - -One of our main concerns is increasing the speed of the wizard and making it as light as possible. Therefore, the wizard does not perform any expensive computations, and does not make any API requests. Most of these actions are done in the extension. So as the user navigates through the wizard, the selections are validated in the wizard and stored. When the user clicks generate, these selections will then be sent to the extension, which will deal with them synchronously. The extension starts with the templates (if any were selected), which will get sent to the Engine (Core Template Studio). After their successful generation, the extension uses Azure SDK to deploy the resources if the user selects any. +- [All docs](../README.md) diff --git a/docs/contributing/getting-started-developers.md b/docs/contributing/getting-started-developers.md index 9258956227..2ff5e56ce2 100644 --- a/docs/contributing/getting-started-developers.md +++ b/docs/contributing/getting-started-developers.md @@ -1,6 +1,7 @@ -# Getting started developers (to contribute to Web Template Studio) +# Getting started developers +To contribute to *Web Template Studio*. -If you are authoring templates for Web Template Studio, or interested in contributing to this repo, then you are likely interested in how to use the latest version of this code. +If you are authoring templates for *Web Template Studio*, or interested in contributing to this repo, then you are likely interested in how to use the latest version of this code. This document covers: - [Prerequisites](#prerequisites) @@ -9,101 +10,120 @@ This document covers: - [How to run the extension locally](#how-to-run-the-extension-locally) - [How to develop the client](#how-to-develop-the-client) - [How to built a local vsix](#how-to-built-a-local-vsix) +- [Tests](#tests) +- [Under the hood](#under-the-hood) Before starting make sure you read the [Web Template Studio arquitecture](application-architecture.md) document. -If you just want to take advantage from Web Template Studio extension, check the [Web Template Studio Installation Instructions page](../install.md). +If you just want to take advantage from *Web Template Studio* extension, check the [Web Template Studio Installation Instructions page](../install.md). ## Prerequisites 1. Install [Node.js](https://nodejs.org/en/download/) -2. Install [Gulp](https://gulpjs.com/) -3. Install [Git](https://git-scm.com/downloads) -4. Install [.NET Core SDK](https://dotnet.microsoft.com/download/dotnet-core/3.1) -5. Install [Visual Studio Code](https://code.visualstudio.com/) -6. Install [Yarn](https://yarnpkg.com/en/docs/install). You will need to finish installing Node.js before you install Yarn. -7. Run the command `npm config set scripts-prepend-node-path true`. This tells VSCode which Node version to run during the extension compilation (otherwise you'll get an error during the build process). +1. Install [Gulp](https://gulpjs.com/) +1. Install [Git](https://git-scm.com/downloads) +1. Install [.NET Core SDK](https://dotnet.microsoft.com/download/dotnet-core/3.1) +1. Install [Visual Studio Code](https://code.visualstudio.com/) +1. Install [Yarn](https://yarnpkg.com/en/docs/install). You will need to finish installing Node.js before you install Yarn. +1. Run the command `npm config set scripts-prepend-node-path true`. This tells VSCode which Node version to run during the extension compilation (otherwise you'll get an error during the build process). -_Note: If using Windows, use Git Bash_. +**Note**: If using Windows, use Git Bash. + +At some point you may also need to install [React-scripts](https://yarnpkg.com/package/react-scripts) and [Typescript](https://www.typescriptlang.org/). ## Project folder structure -### src folder -This folder contains the source code for the different components of Web Template Studio. +### `src` folder +This folder contains the source code for the different components of *Web Template Studio*. -- client: This folder contains the client or wizard code. - - src: - - Assets: Assets directory contains all the SVGs used for the front-end. - - Components: Components contains all React components that are not connected to the Redux store. - - Containers: Containers are React components that are connected to the Redux store. This is the only difference between components and containers. - - CSS: CSS contains styling that is global. - - Store: Store contains the folder structure of the final store, each folder contains the next files - - Reducer: Reducers for the Redux store are defined here. - - Selector: Selectors contain helper methods which takes the Redux store as an argument and returns a specific field. - - Action: Actions for the Redux store - - Model: Interfaces for actions, reducers and selectors. +- [`client`](../../src/client): This folder contains the client or wizard code. + - `src`: + - `assets`: contains all the SVGs used for the frontend. + - `components`: contains all React components that are reusable. + - `css`: CSS contains styling that is global. + - `mockData`: mocked data to be able to use from the browser while developing. + - `modals`: React components and its subcomponents displayed as modals. + - `pages`: React components and its subcomponents displayed as main pages on the Wizard. + - `store`: contains reducers, actions, interfaces and selectors for the Redux store. + - `utils`: contains helper functions, constants and others. + *For example*: validation, routes and extensionService. + - `extensionService`: allows client-extension communication. -- extension: This folder contains the Visual Studio extensions code. - - src: - - Azure: contains all functionality related to azure services - - client-modules: contains the client-modules that allow client-extension communication - - telemetry: contains all functionality related to telemetry - - utils: contains helper functions as logger and validators +- [`extension`](../../src/extension): This folder contains the Visual Studio extensions code. + - `src`: + - `azure`: contains all functionality related to azure services. + - `client-modules`: contains the client-modules that allow client-extension communication. + - `telemetry`: contains all functionality related to telemetry. + - `utils`: contains helper functions as logger and validators. -- CoreTemplateStudio: This solution contains the Core Template Studio code. +- `CoreTemplateStudio`: This solution contains the Core Template Studio code. For more information on internal structure, see [Core Template Studio docs](https://github.com/microsoft/CoreTemplateStudio/blob/dev/docs/getting-started-developers.md). -### _build folder +### `_build` folder This folder contains scripts for local development and usage from the build pipeline. -### templates folder +### `dist` folder +This folder will contain the .vsix if generated. + +### `templates` folder This folder contains the templates that are used to generate the code. For more info on templates see [Understanding the Templates](templates.md). +### `template-test` folder +This folder will contain all the combination of possible generated applications when running the script "**template-tests**" existing on the extension. + ## Core Template Studio Submodule -Web Template Studio relies on Core Template Studio for template synchronization and template composition, generation and postaction. Core Template Studio has its [own Github repository](github.com/Microsoft/CoreTemplateStudio) as it is shared with the sister project [Windows Template Studio](github.com/Microsoft/WindowsTemplateStudio). +*Web Template Studio* relies on Core Template Studio for template synchronization and template composition, generation and postaction. Core Template Studio has its [own Github repository](https://github.com/Microsoft/CoreTemplateStudio) as it is shared with the sibling project [Windows Template Studio](https://github.com/Microsoft/WindowsTemplateStudio). -Core Template Studio is integrated into Web Template Studio using a git submodule under the folder [CoreTemplateStudio](../src/CoreTemplateStudio). The submodule points to a specific commit in Core Template Studio, that you can see in github: +Core Template Studio is integrated into *Web Template Studio* using a git submodule under the folder `/src/CoreTemplateStudio`. The submodule points to a specific commit in Core Template Studio, that you can see in github: -![Core Template Studio Submodule](../resources/corets-submodule.png) +Core Template Studio Submodule ### Init /update -When you clone Web Template Studio you have to run two commands: `git submodule init` and `git submodule update` to fetch all the data from Core Template Studio. When fetching changes, also execute `git submodule update` after doing git fetch to be sure you're submodule is up to date. +When you clone *Web Template Studio* you have to run two commands: `git submodule init` and `git submodule update` to fetch all the data from Core Template Studio. When fetching changes, also execute `git submodule update` after doing git fetch to be sure you're submodule is up to date. ### Update with remote changes Changes on Core Template Studio should be done on the Core Template Studio repos. In WebTS, to update the submodule to the most recent commit, you have to run the command: `git submodule update --remote`. ## How to run the extension locally -1. Run `./build-all.sh` from the _build folder. This script installs dependencies and compiles the client and core template studio and copies it to the extension. It also builds and installs the extension. There are also separate scripts for building the client (build-client.sh), the Core Template Studio Cli (build-coretscli.sh), or the extension (build-extension.sh) available. +1. Run `./build-all.sh` from the `_build` folder. This script installs dependencies and compiles the client and core template studio and copies it to the extension. It also builds and installs the extension. + + There are also separate scripts: + - For building the client (`build-client.sh`). + - For the Core Template Studio Cli (`build-coretscli.sh`). + - For the extension (`build-extension.sh`). 2. Open the `src/extension` folder using `VSCode`. 3. Start the debugger by pressing `F5`. This should open the Extension Development Host in a new Visual Studio Code window. -4. In the Extension Development Host, press `Ctrl + Shift + P` on Windows/Linux or `Command ⌘ + Shift + P` to open the Command Palette. -5. In the Command Palette, type `Web Template Studio: Launch` and press `Enter` to launch the extension. Make sure that you don't have the Web Template Studio from the marketplace installed, concurrent installation is nor yet supported. +4. In the Extension Development Host, press `Ctrl + Shift ⇧ + P` in Windows/Linux or `Command ⌘ + Shift ⇧ + P` in Mac to open the Command Palette. +5. In the Command Palette, type `Web Template Studio (local): Launch` and press `Enter` to launch the extension. We recently added concurrent installation support. + - `Web Template Studio: Launch`: this would launch the marketplace version. + - `Web Template Studio (nightly): Launch`: this would launch an installed instance of the extension. ## How to develop the client -As the client is injected as a static web app in the webview of the extension, debugging inside the extension can be challenging. Running the client in a browser is useful for quickly testing HTML or CSS changes and for debugging since you can use Chrome extensions such as React and Redux developer tools. +As the client is injected as a static web app in the webview of the extension, debugging inside the extension can be challenging. Running the client in a browser is useful for quickly testing HTML or CSS changes and for debugging since you can use **Chrome extensions** such as `React and Redux developer tools`. -When running in the browser communication with the extension is done agains the mock mockVsCodeApi.ts in the mockData folder. Note that the behavior of on the browser may differ from the behavior in the extension so make sure to test out both. +When running in the browser, communication with the extension is done against the mock `mockVsCodeApi.ts` in the `mockData` folder. Note that the behaviour of the client on the browser may differ from the behaviour in the extension, so make sure to test out both. +Styles are mocked in the Browser using the file [`mockThemes.css`](../../src/client/src/css/mockThemes.css). 1. Run `./build-client.sh` from the _build folder. 2. Open the `src/client` folder using `VSCode`. 3. Start the client using `yarn start` to begin development in the browser. We recommend using a chromium based browser such as Chrome. -More info: -- React Developer Tools: https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi -- Redux DevTools: https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd +#### More info: +- [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) +- [Redux Developer Tools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd) ### To debug from Visual Studio Code: Install [Debugger for Chrome extension](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) in Visual Studio Code debug Wizard Client. -After starting the client using `yarn start` in VSCode Debug View (Ctrl+Shift+D) select "Debug WebTS Client" and start debugging (F5) +After starting the client using `yarn start` in VSCode Debug View (`Ctrl + Shift ⇧ + D` (Windows/Linux) or `Shift ⇧ + Command ⌘ + D` (Mac) in Visual Studio Code) select "*Debug WebTS Client*" and start debugging (`F5`). -More info: -- https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome -- https://code.visualstudio.com/docs/editor/debugging +#### More info: +- [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) +- [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) ## How to built a local vsix -Run `./createLocalVsix.sh` from the _build folder. +Run `./createLocalVsix.sh` from the `_build` folder. The script will compile the client, CoreTS (in release mode) and the extension and package the extension into the root directory `/dist` folder. The vsix package can be distributed and installed by anyone who has VSCode using the command in the extension directory: @@ -113,34 +133,40 @@ code --install-extension [extensionName].vsix `webts-0.0.0-UNTRACKEDVERSION.vsix` is the default extensionName. -Alternatively, the extension can be installed from the context menu of the extension section in Visual Studio code using the "install from VSIX..." command. The installed vsix package can be found in the extensions folder. For _Windows_, it is `%USERPROFILE%\.vscode\extensions`. For _Mac/Linux_, it is `~/.vscode/extensions` (By Default). +Alternatively, the extension can be installed from the context menu of the extension section in Visual Studio code using the "**install from VSIX...**" command. The installed vsix package can be found in the extensions folder. For *Windows*, it is `%USERPROFILE%\.vscode\extensions`. For *Mac/Linux*, it is `~/.vscode/extensions` (By Default). -After installation, use `ctrl+shift+p (Windows)` or `cmd+shift+p (Mac)` to open the Extension Launcher and select `Web Template Studio: Launch` to run the extension. +After installation, use `Ctrl + Shift ⇧ + P` (Windows/Linux) or `Command ⌘ + Shift ⇧ + P` (Mac) in Visual Studio Code to open the Extension Launcher and select `Web Template Studio: Launch` to run the extension. ## Tests ### Client Tests -Currently, we use Jest and React Testing Library for our unit tests which was set up by create-react-app. +Currently, we use *Jest and React Testing Library* for our unit tests which was set up by `create-react-app`. -To run the client tests, go to src/client and run `yarn test` to run all the tests. Running this execute tests in files that end with *.{spec,test}.{js,jsx,ts,tsx}. +To run the client tests, go to `src/client` and run `yarn test` to run all the tests. Running this execute tests in files that end with *.{spec,test}.{js,jsx,ts,tsx}. -More info: -- Jest: https://jestjs.io/ -- React Testing Library: https://testing-library.com/docs/react-testing-library/intro +#### More info: +- [Jest](https://jestjs.io/) +- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) ### Template Tests -Currently we use scripts to test the generated code. The scripts are located in the folder ..\src\extension\src\scripts. -Ther genrate-tests script generates all the different permutations of a fullstack project (without azure services). -Afterwards the run-tests script installes the dependencies for the generated project, runs yarn start, yarn lint and yarn test on all the generated projects. +Currently we use scripts to test the generated code. The scripts are located in [src/extension/src/scripts](../../src/extension/src/scripts). +The **generate-tests** script generates all the different permutations of a Fullstack project (without azure services). +Afterwards the **run-tests** script *installs the dependencies* for the generated project, runs *yarn start*, *yarn lint* and *yarn test* on all the generated projects. -To run the template tests go to src/extension and run `yarn template-test` to run the tests. +To run the template tests go to the [`extension` folder](../../src/extension) and run `yarn template-tests` to run the tests. ## Under the Hood -The following notes are inspired by the [vscode-webview-react](https://github.com/rebornix/vscode-webview-react) +The Architecture of this app was inspired by the [vscode-webview-react](https://github.com/rebornix/vscode-webview-react) + +Find some notes about it below if you wish to get started with it: repository by [rebornix](https://github.com/rebornix): -- We inline `index.html` content in `src/extension/src/extension.ts` when creating the webview +- We inline the initial html ` ... ` content in `src/extension/src/reactPanel.ts` when creating the webview - For all resources going to the webview, their scheme is `vscode-resource` - We add a baseUrl `` and then all relative paths work. + +## Learn more + +- [All docs](../README.md) diff --git a/docs/contributing/templates.md b/docs/contributing/templates.md index 9d3f2d1add..88afd2b64c 100644 --- a/docs/contributing/templates.md +++ b/docs/contributing/templates.md @@ -1,17 +1,17 @@ # Understanding the Templates -Templates are used to generate the code. In Web Template Studio we have the following kinds of templates: Frameworks, Projects Types, Pages and Features. +Templates are used to generate the code. In *Web Template Studio* we have the following kinds of templates: Frameworks, Projects Types, Pages and Features. For example, consider the following scenarios: -- **Scenario #1**: you want to generate a project to create a target web app which uses the React on the frontend and Node on the backend, with some pages (Home, Products -a master detail page-, Todo -a list page-, etc. ) and including some extra features like Azure App Service and Cosmos DB... +- **Scenario #1**: you want to generate a project to create a target web app which uses the *React* on the frontend and *Node* on the backend, with some pages (Home, Products -a master detail page-, Todo -a list page-, etc. ) and including some extra features like Azure App Service and Cosmos DB... - **Scenario #2**: you want to create as in *Scenario #1* but with Angular as frontend framework and without CosmosDB support. -The Web Template Studio allow you to combine different templates to generate the project you want, using your preferred framework, and using the features you most like. Moreover, the templates available in Web Template Studio are extensible. +The *Web Template Studio* allow you to combine different templates to generate the project you want, using your preferred framework, and using the features you most like. Moreover, the templates available in *Web Template Studio* are extensible. ## Interested in contributing -Do you want to contribute? Here are our [contribution guidelines](../CONTRIBUTING.md). +Do you want to contribute? Here are our [contribution guidelines](../../CONTRIBUTING.md). ## Anatomy of Templates and Template Authoring @@ -24,12 +24,12 @@ The [Templates Repository](../../templates) has the following structure: - [Web](../../templates/Web): this folder contains all templates used for Web projects - [_catalog](../../templates/Web/_catalog): this folder contains the catalog of available Frameworks and Project Types, including the required information and metadata (descriptions, icons, images, etc.) to be displayed in the Wizard. - [_composition](../../templates/Web/_composition): this folder contains the partial code templates that will be generated when certain constraints are met, including framework specific templates. - - [Projects](../../templates/Web/Projects): Project templates which define the actual folder structure, source files and auxiliary files to create a base project. - - [Pages](../../templates/Web/Pages): Page templates define the source files needed to create a page of a certain type. - [Features](../../templates/Web/Features): Feature templates with the sources required to add different features and / or capabilities to the target web app. + - [Pages](../../templates/Web/Pages): Page templates define the source files needed to create a page of a certain type. + - [Projects](../../templates/Web/Projects): Project templates which define the actual folder structure, source files and auxiliary files to create a base project. ## Learn more -- [Templates doc in Core Template Studio](https://github.com/microsoft/CoreTemplateStudio/tree/dev/docs/tenmplates.md) -- [All docs](./readme.md) +- [Templates doc in Core Template Studio](https://github.com/microsoft/CoreTemplateStudio/tree/dev/docs/templates.md) +- [All docs](../README.md) diff --git a/docs/generated-apps/backend-frameworks/flask.md b/docs/generated-apps/backend-frameworks/flask.md index 57d5a1a37e..2766c15545 100644 --- a/docs/generated-apps/backend-frameworks/flask.md +++ b/docs/generated-apps/backend-frameworks/flask.md @@ -1,4 +1,4 @@ -Flask is a python microframework with a small core for building web applications. It is based on [Werkzeug](https://www.palletsprojects.com/p/werkzeug/) and [Jinja](https://www.palletsprojects.com/p/jinja/). It is licensed under [BSD](https://github.com/pallets/flask/blob/master/LICENSE) license. +Flask is a python microframework with a small core for building web applications. It is based on [Werkzeug](https://www.palletsprojects.com/p/werkzeug/) and [Jinja](https://www.palletsprojects.com/p/jinja/). It is licensed under [BSD](https://github.com/pallets/flask/blob/master/LICENSE.rst) license. It is developed and supported by Pallets organization. More information on Flask can be found [here](http://flask.pocoo.org/) diff --git a/docs/generated-apps/backend-frameworks/readme.md b/docs/generated-apps/backend-frameworks/readme.md index 1ad26a8df7..9bec5abcb0 100644 --- a/docs/generated-apps/backend-frameworks/readme.md +++ b/docs/generated-apps/backend-frameworks/readme.md @@ -2,7 +2,7 @@ The following backend frameworks are supported: +- [Node.js](./nodejs.md) - [Asp.NET](./aspnet.md) - [Flask](./flask.md) -- [Moleculer](./moleculer.md) -- [Node.js](./nodejs.md) \ No newline at end of file +- [Moleculer](./moleculer.md) \ No newline at end of file diff --git a/docs/generated-apps/deployment.md b/docs/generated-apps/deployment.md index 21052ab7bf..9a3832e5be 100644 --- a/docs/generated-apps/deployment.md +++ b/docs/generated-apps/deployment.md @@ -5,60 +5,62 @@ Deploying your website to the cloud allows people to view your website by visiti ## Azure App Service -One way to deploy is using Azure App Service. This service will allow you to deploy and scale web, mobile and API apps. +One way to deploy is using *Azure App Service*. This service will allow you to deploy and scale web, mobile and API apps. ## Web Template Studio: Deploy App command -NOTE: Make sure that the [Web Template Studio](https://marketplace.visualstudio.com/items?itemName=WASTeamAccount.WebTemplateStudio-dev-nightly) and [Azure App Service](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extensions are installed in Visual Studio Code. +**Note**: Make sure that the [Web Template Studio](https://marketplace.visualstudio.com/items?itemName=WASTeamAccount.WebTemplateStudio-dev-nightly) and [Azure App Service](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice) extensions are installed in Visual Studio Code. -The easiest way to deploy an application generated with Web Template Studio is to use the `Web Template Studio: Deploy Application` command. To execute this command, follow these steps: +The easiest way to deploy an application generated with *Web Template Studio* is to use the `Web Template Studio: Deploy Application` command. To execute this command, follow these steps: + +1. Open the application generated with *Web Template Studio* in Visual Studio Code. + +2. Press `Ctrl + Shift ⇧ + P` (Windows/Linux) or `Command ⌘ + Shift ⇧ + P` (Mac) to open the Command Palette. -1. Open the application generated with Web Template Studio in Visual Studio Code. - -2. Press `Ctrl + Shift + P` on Windows/Linux or `Command ⌘ + Shift + P` to open the Command Palette. - 3. In the Command Palette, type `Web Template Studio: Deploy App` and press `Enter` to launch the deploy. -![Web Template Studio Deploy App Command](../resources/select-webts-deploy-command.png) +Web Template Studio Deploy App Command + +*Web Template Studio* will begin preparing the application for deployment. You can see the progress in the Visual Studio Code output. In addition, a notification will be launched for each step executed. + +It will run the tasks to install all the necessary dependencies for the frontend and the backend apps. + +Install Dependencies
+ +Create a Production Build: This step will creates a publish directory with a production build of your frontend and backend apps. -Web Template Studio will begin preparing the application for deployment. You can see the progress in the Visual Studio Code output. In addition, a notification will be launched for each step executed. +Build project
- - It will run the `npm install` command to install all the necessary dependencies for the frontend and the backend apps. +This folder will contain all the necessary frontend and backend files for the deployment. -![Install Dependencies](../resources/preparing-deploy-install-dependencies.png) - - - Create a Production Build: This step will creates a build directory with a production build of your frontend app. +Build directory
-![Build project](../resources/preparing-deploy-build-project.png) - - - Copy the build directory to: - - `server/build` if Node, Flask or Moleculer backend framework is selected. - - `publish/ClientApp/build` if ASP.NET backend framework is selected. -- This folder will contain all the necessary frontend and backend files for the deployment. +*Web Template Studio* will then automatically launch the command `Azure App Service: Deploy to Web App...`, which will be in charge of deploying the application to an *Azure App Service*. -![Build directory](../resources/deploy-build-directory.png) - - - Web Template Studio will then automatically launch the command `Azure App Service: Deploy to Web App...`, which will be in charge of deploying the application to an Azure App Service. + - If you have added an *Azure App Service* when creating your application with *Web Template Studio*, the application already has a deployment configuration, so it will use the created *Azure App Service*. - - If you have added an Azure App Service when creating your application with Web Template Studio, the application already has a deployment configuration, so it will use the created Azure App Service. + - Otherwise, the *Azure App Service* extension will ask you for the configuration settings to create a new *Azure App Service*: + - The folder that contains the app to deploy to the App Service. Select the `publish` folder for deployment to be successful. + - Select `Create New Web App...` + - Enter your web app name + - Select Linux as your OS + - Select Node.js 12 LTS for a Node/Express application, Python 3.7 for a Flask application or .Net Core Latest runtime for ASP .NET application. - - Otherwise, Visual Studio Code will ask you for the deployment directory and if you want to create a new Azure App Service or use a previously created. - - **IMPORTANT**:exclamation: - Remember to select the `server` (or `publish` if ASP.NET backend framework is selected) folder for deployment to be successful. - -![Select deploy directory](../resources/select-folder-to-deploy.png) - - - Start the application deployment to Azure App Service. We can see the progress of the deployment in the output of the Azure App Service extension. - -![Deploying app service](../resources/deploying-azure-app-service.png) - - - At the end of the deployment, Visual Studio Code shows us a notification that the deployment has been successful. - -![Deploying app service finished](../resources/deploying-azure-app-service-finished.png) +Start the application deployment to *Azure App Service*. We can see the progress of the deployment in the output of the *Azure App Service* extension. +Deploying app service
-More info on Azure App Service and deployment: +At the end of the deployment, Visual Studio Code shows us a notification that the deployment has been successful. + +Deploying app service finished
+ +### More info on Azure App Service and deployment: - [Deploy the app to Azure](https://docs.microsoft.com/en-us/azure/app-service/app-service-web-get-started-nodejs#deploy-the-app-to-azure) - [Azure App Service for Visual Studio Code](https://github.com/Microsoft/vscode-azureappservice) - [Azure App Service documentation](https://docs.microsoft.com/en-us/azure/app-service/) + + +## Learn more + +- [All docs](../README.md) \ No newline at end of file diff --git a/docs/generated-apps/services/azure-appservice.md b/docs/generated-apps/services/azure-appservice.md index 1c249bb499..745dff922c 100644 --- a/docs/generated-apps/services/azure-appservice.md +++ b/docs/generated-apps/services/azure-appservice.md @@ -1,50 +1,50 @@ # Azure App Service -Azure App Service is an HTTP-based service for hosting web applications, REST APIs, and mobile back ends. You can develop in your favorite language, be it .NET, .NET Core, Java, Ruby, Node.js, PHP, or Python. Applications run and scale with ease on both Windows and Linux-based environments. For more info about Azure App Service click [here](https://docs.microsoft.com/azure/app-service/overview). +*Azure App Service* is an HTTP-based service for hosting web applications, REST APIs, and mobile backends. You can develop in your favorite language, be it .NET, .NET Core, Java, Ruby, Node.js, PHP, or Python. Applications run and scale with ease on both Windows and Linux-based environments. For more info about *Azure App Service* click [here](https://docs.microsoft.com/azure/app-service/overview). -Web Template Studio offers you the functionality to create and deploy your application to Azure App Service from the wizard quickly and easly. +*Web Template Studio* offers you the functionality to create and deploy your application to *Azure App Service* from the wizard quickly and easily. ## Getting started -To create an Azure App Service using Web Template Studio: +To create an *Azure App Service* using *Web Template Studio*: -- Navigate to the "Add Optional Cloud Services" step. Click the "Add to my project" button in App Service card. +Navigate to the "**Add Optional Cloud Services**" step. Click the "**Add to my project**" button in the **App Service card**. -![azure-appservice-card](../../resources/azure-appservice-card.png) +Azure App Service Card -- Select a _Subscription_ from the _Create App Service_ tab that just opened. Use the _Create New_ - option if you want to create a new _Subscription_. _**Note:**_ Create new will take you to Azure portal to create a subscription. +Select a **Subscription** from the **Create App Service** modal that just opened. Use the **Create New** option if you want to create a new *Subscription*. -- Enter a _Name_ for your azure web app. Enter a unique app name that includes only the valid characters, those are a-z, A-Z, 0-9, and -. Alternatively, you can accept the automatically generated unique name. The URL of the web app is `http://.azurewebsites.net`, where `` is your app name. +**Note**: **Create New** will take you to your Azure portal in the browser, so you can create a subscription. -![azure-appservice-card](../../resources/azure-appservice-createappservice.png) +Enter a **Web App Name** for your azure web app. It must be a unique app name that follows the Azure naming convention, for example it should include only the valid characters [a-z, A-Z, 0-9, and -]. Alternatively, you can accept the automatically generated unique name. The URL of the web app is `http://.azurewebsites.net`, where `` is your app name. + +Azure Create App Service ### Advanced mode -By default, Web Template Studio deploys the App Service in the location Central US and creates a Resource Group with the same name as the web app. It will also create the free BASIC App Service Plan that hosts the web app. [More info for App Service Plans](https://azure.microsoft.com/en-us/pricing/details/app-service/plans/). +By default, *Web Template Studio* deploys the App Service in the location Central US and creates a Resource Group with the same name as the web app. It will also create the *free BASIC App Service Plan* that hosts the web app. [More info for App Service Plans](https://azure.microsoft.com/en-us/pricing/details/app-service/plans/). -We can change these settings using the advanced mode. To display the advanced mode, click on the "advanced mode" button and the App Service modal will show two new configuration options. +We can change these settings using the *advanced mode*. To display it, click on the "**Advanced mode**" link and the App Service modal will show two new configuration options: -![azure-appservice-card](../../resources/azure-appservice-createappservice-advanced-mode.png) +- **Location**: Azure region where the App Service will be deployed. Central US is selected by default. [More info about Azure Locations](https://azure.microsoft.com/en-us/global-infrastructure/regions/). -- Location: Azure region where the App Service will be deployed. Central US is selected by default. [More info about Azure Locations](https://azure.microsoft.com/en-us/global-infrastructure/regions/). +- **Resource Group**: A resource group is a container that holds related resources for an Azure solution. If we want to deploy the App Service in any resource group that you have created in the Azure Subscription previously, we can select it in the dropdown. If you don't select any resource group, it will be created in a new Resource Group with the same name as the web app. -- Resource Group: A resource group is a container that holds related resources for an Azure solution. If we want to deploy the App Service in any resource group that you have created in the Azure Subscription previously, we can select it in the dropdown. If you don't select any resource group, it will be created in a new Resource Group with the same name as the web app. +Azure Create App Service in Advanced Mode ## Creating App Service -Once you hit generate on the summary page, Web Template Studio will create an Azure App Service that will be accessible from `http://.azurewebsites.net`. +Once you hit generate on the summary page, *Web Template Studio* will create an *Azure App Service* that will be accessible from `http://.azurewebsites.net`. -Web Template Studio uses an arm-template for Azure App Services (generated under the arm-templates directory). This template contains the definitions and parameters for all resources that need to deploy. Once Azure receives your template, it takes about 2-3 minutes to create the App Service and the App Service Plan. The app service initially contains an empty web app. +*Web Template Studio* uses an arm-template for *Azure App Services* (generated under the arm-templates directory). This template contains the definitions and parameters for all resources that need to deploy. Once Azure receives your template, it takes about 2-3 minutes to create the App Service and the App Service Plan. The app service initially contains an empty web app. -_**Note:**_ For advanced users, the _arm templates_ -used to deploy your application are also available under the _arm-templates_ directory (in your generated project). +**Note for advanced users**: The *arm templates* used to deploy your application, are also available under the *arm-templates* directory in your generated project. ## How to deploy -When we create a Azure App Service, it initially contains an empty web app. To learn how to deploy your generated application to the created Azure App Service, read the [Web Template Studio deployment documentation](../deployment.md). +When we create a *Azure App Service*, it initially contains an empty web app. To learn how to deploy your generated application to the created *Azure App Service*, read the [Web Template Studio deployment documentation](../deployment.md). ## VSCode Extension for Azure App Service -To manage Azure App Service you can use the [Azure App Service extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice), which is automatically installed with Web Template Studio. +To manage *Azure App Service* you can use the [Azure App Service extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice), which is automatically installed with *Web Template Studio*. This extension helps you create, manage, and deploy your websites quickly. diff --git a/docs/generated-apps/services/azure-cosmos.md b/docs/generated-apps/services/azure-cosmos.md index 9302713f0f..f8f0705d52 100644 --- a/docs/generated-apps/services/azure-cosmos.md +++ b/docs/generated-apps/services/azure-cosmos.md @@ -1,63 +1,69 @@ # Azure Cosmos DB -Azure Cosmos DB is Microsoft’s proprietary globally-distributed, multi-model database service for managing data on a +*Azure Cosmos DB* is Microsoft’s proprietary globally-distributed, multi-model database service for managing data on a global scale. It offers a variety of APIs for your database including Azure Table, Core (SQL), MongoDB and Gremlin -(GraphQL). Web Template Studio offers you the functionality to deploy a Cosmos DB instance from the wizard itself +(GraphQL). + +*Web Template Studio* offers you the functionality to deploy a *Cosmos DB* instance from the wizard itself and select an initial location to deploy your database with the ability to scale it to multiple locations at a future -time. As an added feature, deploying with the MongoDB API enables you to quickly connect the project Web Template Studio +time. As an added feature, deploying with the MongoDB API enables you to quickly connect the project *Web Template Studio* generates to your database instance. ## Getting started -To deploy Cosmos DB using Web Template Studio: +To deploy *Cosmos DB* using *Web Template Studio*: + +Navigate to the "**Add Optional Cloud Services**" step. Click the "**Add to my project**" button in **CosmosDB card**. -- Navigate to the "Add Optional Cloud Services" step. Click the "Add to my project" button in CosmosDB card. +Azure Cosmos Card -![azure-cosmos-card](../../resources/azure-cosmos-services-card.png) +Select a **Subscription** from the **Create Cosmos DB Account** modal that just opened. Use the **Create New** option if you want to create a new **Subscription**. -- Select a _Subscription_ from the _Create Cosmos DB Account_ tab that just opened. Use _Create New_ - option if you want to create a new _Subscription_. _**Note:**_ Create new will take you to Azure portal to create a subscription. +**Note**: **Create New** will take you to the Azure portal website, so you can create a subscription. -- Enter a _Name_ for your cosmos account. This name is globally unique since your database will be available as +Enter an **Account Name** for your cosmos account. This name is globally unique since your database will be available as `.documents.azure.com`. -- Select an API for your database. _**Note:**_ Web Template Studio only supports MongoDB API and SQL API. +Select an API for your database. + +**Note**: *Web Template Studio* only supports MongoDB API and SQL API. -![azure-cosmos-modal](../../resources/azure-cosmos-modal.png) +Azure Cosmos Create Modal ### Advanced mode -By default, Web Template Studio deploys the Cosmos DB in the location Central US and creates a Resource Group with the same name as the web app. +By default, *Web Template Studio* deploys the *Cosmos DB* in the location Central US and creates a Resource Group with the same name as the web app. -We can change these settings using advanced mode. To display the advanced mode, click on the "advanced mode" button and the Cosmos DB modal will show two new configuration options. +We can change these settings using the *advanced mode*. To access those, click on the "**Advanced mode**" link and the *Cosmos DB* modal will show two new configuration options. -![azure-cosmos-modal](../../resources/azure-cosmos-modal-advanced-mode.png) +- **Location**: Azure region where the *Cosmos DB* will be deployed. Central US is selected by default. [More info about Azure Locations](https://azure.microsoft.com/en-us/global-infrastructure/regions/). -- Location: Azure region where the Cosmos DB will be deployed. Central US is selected by default. [More info about Azure Locations](https://azure.microsoft.com/en-us/global-infrastructure/regions/). +- **Resource Group**: A resource group is a container that holds related resources for an Azure solution. If you want to deploy the *Cosmos DB* in any resource group that you have created in the Azure Subscription previously, you can select it in the dropdown. If you don't select any resource group, it will be created a new Resource Group with the same name as the web app. -- Resource Group: A resource group is a container that holds related resources for an Azure solution. If you want to deploy the Cosmos DB in any resource group that you have created in the Azure Subscription previously, you can select it in the dropdown. If you don't select any resource group, it will be created a new Resource Group with the same name as the web app. +Azure Cosmos Create Modal in Advanced Mode ## Creating Cosmos DB -Once you hit generate on the summary page, Web Template Studio will deploy your database and display a popup with your +Once you hit **Create Project**, *Web Template Studio* will deploy your database and display a popup with your database connection string once it's available (usually within 5-6 minutes). This will prompt you to replace the -connection string in your configuration file with the new connection string. _**Note:**_ For advanced users, the _arm templates_ -used to deploy your application are also available under the _arm-templates_ directory (in your generated project). +connection string in your configuration file with the new connection string. + +***Note for advanced users***: The *arm templates* used to deploy your application are also available under the *arm-templates* directory (in your generated project). ## Protecting Your Keys -Never make your API keys public or check in your API keys in to version control. The generated project stores API keys in the .env file (appsettings.json for ASP.NET). The .env/appsettings.json file is excluded from version control in the `.gitignore`. +**Never make your API keys public or check in your API keys in to version control** . + +The generated project stores API keys in the `.env` file (`appsettings.json` for ASP.NET). The `.env/appsettings.json` file is excluded from version control in the `.gitignore`. ## How this works -Web Template Studio uses an arm-template for Cosmos (generated under the _arm-templates_ directory) to deploy -your Cosmos DB instance. This template contains the definitions and parameters for all resources and storage -accounts that need to be created for your database. Once Azure receives your template, it takes about 5-6 minutes to -assign VMs for your database account, get them up and running with your selected API and have the database connection -string available for you to connect to your database. +*Web Template Studio* uses an arm-template for Cosmos to deploy your *Cosmos DB* instance. This is generated under the `arm-templates` directory. +This template contains the definitions and parameters for all resources and storage accounts that need to be created for your database. Once Azure receives your template, it takes about 5-6 minutes to assign VMs for your database account, get them up and running with your selected API and have the database connection string available for you to connect to your database. + +Once the connection string is available, *Web Template Studio* will prompt you to replace the variables in your `.env/appsettings.json` file with this string and your keys. -Once the connection string is available, Web Template Studio will prompt you to replace the variables in your _.env_ or _appsettings.json_ file -with this string and your keys. _**Warning:**_ Accepting this prompt will override your current _.env/appsettings.json_. If you have made +**Warning**: Accepting this prompt will override your current `.env/appsettings.json`. If you have made any changes to this file, consider saving them! You will also need to restart your server to sync changes on your configuration file! @@ -66,19 +72,18 @@ file! ![azure-cosmos-portal](../../resources/azure-cosmos-portal.png) You can access and modify your database instance through the [Azure portal](https://portal.azure.com). Once you login to -the portal, select Azure Cosmos DB from the menu bar on the left side. This will list different database +the portal, select *Azure Cosmos DB* from the menu bar on the left side. This will list different database accounts owned by you under different resource groups. Select the account you want to edit and it will bring up a menu -(_Settings_ in the image above) to configure your account. This can be anything from: scaling your database, adding new +(**Settings** in the image above) to configure your account. This can be anything from: scaling your database, adding new collections, setting up firewalls, viewing metrics for your deployment etc. ## VSCode Extension for Azure Cosmos DB -![azure-cosmos-extension](../../resources/azure-cosmos-extension.png) +Azure CosmosDB in the Extension -If you would like to manage your Cosmos DB environment from VSCode itself, we recommend you install the +If you would like to manage your *Cosmos DB* environment from VSCode itself, we recommend you install the [Azure Databases](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) extension for VSCode. Select Azure from the activity bar. From the Cosmos menu, you can create a new database account (as shown in the image above) or attach a previously created database account. From here, you can create/view/edit/delete accounts, collections and documents etc. or execute commands (such as SQL or mongo shell commands). Read the extension [documentation](https:// -marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) -for full features and usage! +marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb) for full features and usage! diff --git a/docs/install.md b/docs/install.md index 9b6c961587..e8114a738a 100644 --- a/docs/install.md +++ b/docs/install.md @@ -2,32 +2,29 @@ ## Prerequisites -Web Template Studio runs as a VSCode extension and hence you'll need to have _VScode_ version 1.38 or above installed. -Also, you'll need [_Node_](https://nodejs.org/en/download/),[_Python_](https://www.python.org/downloads/) or [_ASP.NET_](https://dotnet.microsoft.com/download) and _npm_/[_yarn_](https://yarnpkg.com/en/docs/install) to run the generated templates. +*Web Template Studio* runs as a VSCode extension and hence you'll need to have *VScode* version 1.38 or above installed. +Also, you'll need [node](https://nodejs.org/en/download/), [python](https://www.python.org/downloads/) or [ASP.NET](https://dotnet.microsoft.com/download) and [npm](https://www.npmjs.com/get-npm)/[yarn](https://yarnpkg.com/en/docs/install) to run the generated templates. -## Where is the offical release? -We are currently early in our development phase and only have a dev nightly on Visual Studio Marketplace. - -## Installing the nightly dev branch build _preferred_ -Head over to [Visual Studio Marketplace’s Web Template Studio page](https://marketplace.visualstudio.com/items?itemName=WASTeamAccount.WebTemplateStudio-dev-nightly) and click "[install](vscode:extension/WASTeamAccount.WebTemplateStudio-dev-nightly)" 😊. +## Installing the official release +Head over to [Visual Studio Marketplace’s Web Template Studio page](https://marketplace.visualstudio.com/items?itemName=WASTeamAccount.WebTemplateStudio-dev-nightly) and click "[install](vscode:extension/WASTeamAccount.WebTemplateStudio-dev-nightly)" 😊. ## Installing the latest Microsoft Web Template Studio release manually 1. Head over to [Visual Studio Marketplace’s Web Template Studio page](https://marketplace.visualstudio.com/items?itemName=WASTeamAccount.WebTemplateStudio-dev-nightly) 2. In the right panel, section Resources, click on "Download Extension" and download the `.vsix` file - -![VSIX Download](./resources/vsix-download.png) + +VSIX Download 3. Open VSCode 4. Open the extensions menu from VSCode sidebar 5. Click on the ellipsis in the upper right hand corner -6. Choose _Install from VSIX_ -7. Select the `.vsix` you downloaded earlier. Web Template Studio is now ready to use +6. Choose *Install from VSIX* +7. Select the `.vsix` you downloaded earlier. *Web Template Studio* is now ready to use -![VSIX Install Instructions](./resources/vsix-install-instructions.png) +VSIX Install Instructions #### Run the Release - Open **VSCode** -- Press `ctrl+shift+p`to open VSCode's extension launcher +- Press `Ctrl + Shift ⇧ + P` (Windows/Linux) or `Command ⌘ + Shift ⇧ + P` (Mac) to open VSCode's extension launcher - Type/Select `Web Template Studio: Launch` and press `Enter` to launch the extension diff --git a/docs/resources/azure-appservice-add.png b/docs/resources/azure-appservice-add.png deleted file mode 100644 index a27c357f48..0000000000 Binary files a/docs/resources/azure-appservice-add.png and /dev/null differ diff --git a/docs/resources/azure-appservice-application-settings.png b/docs/resources/azure-appservice-application-settings.png deleted file mode 100644 index 4d2bb647a7..0000000000 Binary files a/docs/resources/azure-appservice-application-settings.png and /dev/null differ diff --git a/docs/resources/azure-appservice-click-create.png b/docs/resources/azure-appservice-click-create.png deleted file mode 100644 index 479897a142..0000000000 Binary files a/docs/resources/azure-appservice-click-create.png and /dev/null differ diff --git a/docs/resources/azure-appservice-click-webapp.png b/docs/resources/azure-appservice-click-webapp.png deleted file mode 100644 index 186f89d728..0000000000 Binary files a/docs/resources/azure-appservice-click-webapp.png and /dev/null differ diff --git a/docs/resources/azure-appservice-createadd.png b/docs/resources/azure-appservice-createadd.png deleted file mode 100644 index 0ebc557ab1..0000000000 Binary files a/docs/resources/azure-appservice-createadd.png and /dev/null differ diff --git a/docs/resources/azure-appservice-createresource.png b/docs/resources/azure-appservice-createresource.png deleted file mode 100644 index 8d0d706e31..0000000000 Binary files a/docs/resources/azure-appservice-createresource.png and /dev/null differ diff --git a/docs/resources/azure-appservice-deploy-button.png b/docs/resources/azure-appservice-deploy-button.png deleted file mode 100644 index 3aa2579aa0..0000000000 Binary files a/docs/resources/azure-appservice-deploy-button.png and /dev/null differ diff --git a/docs/resources/azure-appservice-notification.png b/docs/resources/azure-appservice-notification.png deleted file mode 100644 index 9d5c53d20e..0000000000 Binary files a/docs/resources/azure-appservice-notification.png and /dev/null differ diff --git a/docs/resources/azure-appservice-portal.png b/docs/resources/azure-appservice-portal.png deleted file mode 100644 index 75326cb2cc..0000000000 Binary files a/docs/resources/azure-appservice-portal.png and /dev/null differ diff --git a/docs/resources/azure-appservice-rootdirectory.png b/docs/resources/azure-appservice-rootdirectory.png deleted file mode 100644 index 9e4b53151c..0000000000 Binary files a/docs/resources/azure-appservice-rootdirectory.png and /dev/null differ diff --git a/docs/resources/azure-appservice-update-build-notification.png b/docs/resources/azure-appservice-update-build-notification.png deleted file mode 100644 index 1def608e23..0000000000 Binary files a/docs/resources/azure-appservice-update-build-notification.png and /dev/null differ diff --git a/docs/resources/azure-functions-extension.png b/docs/resources/azure-functions-extension.png deleted file mode 100644 index b37670e343..0000000000 Binary files a/docs/resources/azure-functions-extension.png and /dev/null differ diff --git a/docs/resources/azure-functions-modal.png b/docs/resources/azure-functions-modal.png deleted file mode 100644 index eabb417cf2..0000000000 Binary files a/docs/resources/azure-functions-modal.png and /dev/null differ diff --git a/docs/resources/azure-functions-portal.png b/docs/resources/azure-functions-portal.png deleted file mode 100644 index 6ea68b93fc..0000000000 Binary files a/docs/resources/azure-functions-portal.png and /dev/null differ diff --git a/docs/resources/cosmos-db-extension.png b/docs/resources/cosmos-db-extension.png deleted file mode 100644 index e83880e2d0..0000000000 Binary files a/docs/resources/cosmos-db-extension.png and /dev/null differ diff --git a/docs/resources/deploy-build-directory.png b/docs/resources/deploy-build-directory.png deleted file mode 100644 index 7bd56226fe..0000000000 Binary files a/docs/resources/deploy-build-directory.png and /dev/null differ diff --git a/docs/resources/deploy-publish-directory.png b/docs/resources/deploy-publish-directory.png new file mode 100644 index 0000000000..ba5f554f23 Binary files /dev/null and b/docs/resources/deploy-publish-directory.png differ diff --git a/docs/resources/readme-app-azure-screenshot.png b/docs/resources/readme-app-azure-screenshot.png index 4f58ae38fa..059cfc1097 100644 Binary files a/docs/resources/readme-app-azure-screenshot.png and b/docs/resources/readme-app-azure-screenshot.png differ diff --git a/docs/resources/select-folder-to-deploy.png b/docs/resources/select-folder-to-deploy.png deleted file mode 100644 index 0ae8e972e3..0000000000 Binary files a/docs/resources/select-folder-to-deploy.png and /dev/null differ diff --git a/docs/resources/vsix-download.png b/docs/resources/vsix-download.png index b4a9c8d564..c4b836bdea 100644 Binary files a/docs/resources/vsix-download.png and b/docs/resources/vsix-download.png differ diff --git a/docs/resources/webts-dark-theme.png b/docs/resources/webts-dark-theme.png new file mode 100644 index 0000000000..2f5c9a1a31 Binary files /dev/null and b/docs/resources/webts-dark-theme.png differ diff --git a/docs/resources/webts-light-theme.png b/docs/resources/webts-light-theme.png index c7af65e4d6..d2e5100941 100644 Binary files a/docs/resources/webts-light-theme.png and b/docs/resources/webts-light-theme.png differ diff --git a/docs/telemetry.md b/docs/telemetry.md index 8db0ec16e8..5eb55f11fd 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -1,10 +1,10 @@ # Web Template Studio Telemetry -Web Template Studio logs usage data and diagnostics telemetry through [Application Insights](https://azure.microsoft.com/en-us/services/monitor/). +*Web Template Studio* logs usage data and diagnostics telemetry through [Application Insights](https://azure.microsoft.com/en-us/services/monitor/). The class [TelemetryService](../src/extension/src/telemetry/telemetryService.ts), within the extension code, isolates the telemetry service implementation details and offers a smooth and easy way to invoke telemetry events. -Apart from the data logged in Web Template Studio, Core Template Studio tracks telemetry data on generation. For more info see [Core Template Studio Telemetry](https://github.com/microsoft/CoreTemplateStudio/blob/dev/docs/telemetry.md) +Apart from the data logged in *Web Template Studio*, Core Template Studio tracks telemetry data on generation. For more info see [Core Template Studio Telemetry](https://github.com/microsoft/CoreTemplateStudio/blob/dev/docs/telemetry.md) ## Trends @@ -12,7 +12,7 @@ Please head to our [Telemetry Data](telemetryData.md) where we show trends from ## Telemetry Gathered -The wizard for Web Template Studio collects basic diagnostics telemetry and usage data: +The wizard for *Web Template Studio* collects basic diagnostics telemetry and usage data: - **Diagnostics telemetry:** Unhandled error and exceptions that happened while running the wizard are logged with Application Insights. This includes the stack trace of the error @@ -20,7 +20,7 @@ The wizard for Web Template Studio collects basic diagnostics telemetry and usag ## Usage Telemetry -Through the Application Insights API, telemetry events are collected to gather basic information regarding Web Template Studio extension usage. The following table describes the Telemetry Events we collect: +Through the Application Insights API, telemetry events are collected to gather basic information regarding *Web Template Studio* extension usage. The following table describes the Telemetry Events we collect: |Event Name Tracked |Notes | |:-------------:|:-----| @@ -29,7 +29,7 @@ Through the Application Insights API, telemetry events are collected to gather b |**Sync-Engine**|Track the time it takes to synchronize the templates in the extension| |**Create-New-Project**|Track the start of creating a new project. Save the entry-point of this action (Launch wizard or Create New Project button).| |**Wizard-To-Generate-Session-Time**|Track the time that elapses since the extension is launched until the start generation a new project.| -|**Wizard-Page-Change**|Track the total time the user views a Web Template Studio extension page.| +|**Wizard-Page-Change**|Track the total time the user views a *Web Template Studio* extension page.| |**login**|Track the time it takes for a user to log in to Azure.| |**logout**|Track the time it takes for a user to log out of their Azure account.| |**get-user-status**|Track the time it takes for the extension to obtain the data of a user logged in to Azure.| @@ -75,7 +75,7 @@ To send telemetry from the extension code we must use the `telemetryService` cla Communication between the client and the extension is done using sending requests with the method `vscode.postmessage` ([more info](https://code.visualstudio.com/api/extension-guides/webview#passing-messages-from-an-extension-to-a-webview)), passing through parameters the module and the extension command that have to process this request. If we want to track the client request, send the property `track: true`. -Example: +### Example: ```javascript vscode.postMessage({ diff --git a/docs/telemetryData.md b/docs/telemetryData.md index fbdd5dd552..4a2604b80e 100644 --- a/docs/telemetryData.md +++ b/docs/telemetryData.md @@ -1,3 +1,36 @@ -# Telemetry for Web Template Studio - DATE +# Telemetry for Web Template Studio - 2020.10 As new features and pages roll out, percentages will adjust. + +## Frontend Frameworks + +|Framework Type|Percentage| +|:---|:---:| +|React|57.7%| +|Vue|22.1%| +|Angular|20.3%| + +## Backend Frameworks + +|Framework Type|Percentage| +|:---|:---:| +|Node|59.9%| +|AspNet|17.8%| +|Flask|15%| +|Moleculer|7.3%| + +## Pages + +|Pages|Percentage| +|:---|:---:| +|Blank|38%| +|Grid|21.7%| +|Master Detail|20.8%| +|List|19.5%| + +## Services + +|Services|Percentage| +|:---|:---:| +|App Service|51.5%| +|Cosmos DB|48.5%| diff --git a/sha256-staging-weekly.md b/sha256-staging-weekly.md index d52a1fece6..7eaa948962 100644 --- a/sha256-staging-weekly.md +++ b/sha256-staging-weekly.md @@ -1,3 +1,3 @@ -Version: 0.3.2012502 +Version: 0.4.2020202 -sha256: 182ED257C14D635AEFBE6A1941A3D075387D4B74FF2570C5EF2D34A4EBFAD9A9 +sha256: 74210F5BEDD4B108250AE867F3D114B83CA29A993533DAFC501D958F9B77A51D diff --git a/src/CoreTemplateStudio b/src/CoreTemplateStudio index 8773aa2dbc..901f137e87 160000 --- a/src/CoreTemplateStudio +++ b/src/CoreTemplateStudio @@ -1 +1 @@ -Subproject commit 8773aa2dbc1ca3b97e95229f405bd48921e5933c +Subproject commit 901f137e87182664ada3c4220a0f06d81f4fae61 diff --git a/src/client/package.json b/src/client/package.json index b9bbcf1868..91196d5607 100644 --- a/src/client/package.json +++ b/src/client/package.json @@ -23,10 +23,8 @@ "classnames": "^2.2.6", "focus-visible": "^5.1.0", "global": "^4.4.0", - "latest-version": "^5.1.0", "lodash": "^4.17.19", - "node-fetch": "^2.6.0", - "npm": "^6.14.6", + "node-fetch": "^2.6.1", "react": "^16.13.1", "react-dom": "^16.13.1", "react-intl": "^2.8.0", @@ -42,7 +40,7 @@ "reselect": "^4.0.0", "rewire": "^5.0.0", "rxjs": "^6.5.5", - "typescript": "3.2.4", + "typescript": "^3.7.2", "typescript-react-intl": "^0.3.0" }, "scripts": { diff --git a/src/client/src/App.tsx b/src/client/src/App.tsx index 7e1ecdc239..c7781e26d9 100644 --- a/src/client/src/App.tsx +++ b/src/client/src/App.tsx @@ -3,98 +3,79 @@ import * as React from "react"; import { connect, useDispatch } from "react-redux"; import { ReactComponent as SummarySplashSVG } from "./assets/summarySplash.svg"; import { ReactComponent as HomeSplashSVG } from "./assets/homeSplash.svg"; -import { - EXTENSION_COMMANDS, - ROUTES, - DEVELOPMENT -} from "./utils/constants"; - +import { DEVELOPMENT } from "./utils/constants/constants"; import appStyles from "./appStyles.module.css"; import { AppState } from "./store/combineReducers"; import { IOption } from "./types/option"; -import PageDetails from "./containers/PageDetails"; +import PageDetails from "./pages/PageDetails"; import { NAVIGATION_MODAL_TYPES } from "./store/navigation/typeKeys"; -import RightSidebar from "./containers/RightSidebar"; +import RightSidebar from "./components/RightSidebar"; import TopNavBar from "./components/TopNavBar"; -import { setOutputPathAction } from "./store/userSelection/app/action"; import { loadAction } from "./store/config/config/action"; import loadable from '@loadable/component' - -const PageSelectFrameworks = loadable(()=> import(/* webpackChunkName: "PageSelectFrameworks" */ "./containers/PageSelectFrameworks")); -const PageAddPages = loadable(()=> import(/* webpackChunkName: "PageAddPages" */ "./containers/PageAddPages")); -const PageReviewAndGenerate = loadable(() => import(/* webpackChunkName: "PageReviewAndGenerate" */ "./containers/PageReviewAndGenerate")); -const PageAddServices = loadable(() => import(/* webpackChunkName: "PageAddServices" */ "./containers/PageAddServices")); -const GenerationModal = loadable(() => import(/* webpackChunkName: "GenerationModal" */ "./containers/GenerationModal")); -const CosmosDbModal = loadable(() => import(/* webpackChunkName: "CosmosDbModal" */ "./containers/CosmosDbModal")); -const AppServiceModal = loadable(() => import(/* webpackChunkName: "AppServiceModal" */ "./containers/AppServiceModal")); -const ViewLicensesModal = loadable(() => import(/* webpackChunkName: "ViewLicensesModal" */ "./containers/ViewLicensesModal")); -const AzureLoginModal = loadable(() => import(/* webpackChunkName: "AzureLoginModal" */ "./containers/AzureLoginModal")); +import { ROUTE } from "./utils/constants/routes"; +import { getSelectedRoute } from "./store/userSelection/app/wizardSelectionSelector/wizardSelectionSelector"; + +const PageSelectFrameworks = loadable(()=> import(/* webpackChunkName: "PageSelectFrameworks" */ "./pages/PageSelectFrameworks")); +const PageAddPages = loadable(()=> import(/* webpackChunkName: "PageAddPages" */ "./pages/PageAddPages")); +const PageReviewAndGenerate = loadable(() => import(/* webpackChunkName: "PageReviewAndGenerate" */ "./pages/PageReviewAndGenerate")); +const PageAddServices = loadable(() => import(/* webpackChunkName: "PageAddServices" */ "./pages/PageAddServices")); +const GenerationModal = loadable(() => import(/* webpackChunkName: "GenerationModal" */ "./modals/GenerationModal")); +const CosmosDbModal = loadable(() => import(/* webpackChunkName: "CosmosDbModal" */ "./modals/CosmosDbModal")); +const AppServiceModal = loadable(() => import(/* webpackChunkName: "AppServiceModal" */ "./modals/AppServiceModal")); +const ViewLicensesModal = loadable(() => import(/* webpackChunkName: "ViewLicensesModal" */ "./modals/ViewLicensesModal")); +const AzureServicesModal = loadable(() => import(/* webpackChunkName: "AzureServicesModal" */ "./modals/AzureServicesModal")); if (process.env.NODE_ENV === DEVELOPMENT) { - require("./css/themes.css"); + require("./css/mockThemes.css"); } interface IStateProps { frontendOptions: IOption[]; modalState: any; selectedRoute: string; + isDetailPageVisible: boolean; } type Props = IStateProps; const App = (props: Props) => { - const { modalState, selectedRoute } = props; + const { modalState, selectedRoute, isDetailPageVisible } = props; const dispatch = useDispatch(); - const Header = loadable(() => import(/* webpackChunkName: "Header" */ "./containers/Header")); - const Footer = loadable(() => import(/* webpackChunkName: "Footer" */ "./containers/Footer")); - const PageNewProject = loadable(() => import(/* webpackChunkName: "PageNewProject" */ "./containers/PageNewProject")); + const Header = loadable(() => import(/* webpackChunkName: "Header" */ "./components/Header")); + const Footer = loadable(() => import(/* webpackChunkName: "Footer" */ "./components/Footer")); + const PageNewProject = loadable(() => import(/* webpackChunkName: "PageNewProject" */ "./pages/PageNewProject")); React.useEffect(()=>{ dispatch(loadAction()); - messageEventsFromExtension(); },[]); - function messageEventsFromExtension(){ - window.addEventListener("message", event => { - const message = event.data; - switch (message.command) { - case EXTENSION_COMMANDS.GET_OUTPUT_PATH: - if (message.payload !== null && message.payload.outputPath !== undefined) { - dispatch(setOutputPathAction(message.payload.outputPath)); - } - break; - } - }); - } - return (
-
{(modalState.modalType === NAVIGATION_MODAL_TYPES.VIEW_LICENSES_MODAL) && ()} {(modalState.modalType === NAVIGATION_MODAL_TYPES.APP_SERVICE_MODAL) && ()} {(modalState.modalType === NAVIGATION_MODAL_TYPES.COSMOS_DB_MODAL) && ()} - {(modalState.modalType === NAVIGATION_MODAL_TYPES.AZURE_LOGIN_MODAL) && ()} + {(modalState.modalType === NAVIGATION_MODAL_TYPES.AZURE_LOGIN_MODAL) && ()} {(modalState.modalType === NAVIGATION_MODAL_TYPES.GEN_MODAL) && ()}
- {selectedRoute === ROUTES.NEW_PROJECT ? ( + {selectedRoute === ROUTE.NEW_PROJECT ? ( ) : null} - {selectedRoute === ROUTES.REVIEW_AND_GENERATE ? ( + {selectedRoute === ROUTE.REVIEW_AND_GENERATE ? ( { /> ) : null} - {(selectedRoute === ROUTES.PAGE_DETAILS) && ()} - {(selectedRoute === ROUTES.ADD_SERVICES) && ()} - {(selectedRoute === ROUTES.REVIEW_AND_GENERATE) && ()} - {(selectedRoute === ROUTES.SELECT_FRAMEWORKS) && ()} - {(selectedRoute === ROUTES.SELECT_PAGES) && ()} - {(selectedRoute === ROUTES.NEW_PROJECT) && ()} + {isDetailPageVisible && ()} + {(!isDetailPageVisible && selectedRoute === ROUTE.ADD_SERVICES) && ()} + {(!isDetailPageVisible && selectedRoute === ROUTE.REVIEW_AND_GENERATE) && ()} + {(!isDetailPageVisible && selectedRoute === ROUTE.SELECT_FRAMEWORKS) && ()} + {(!isDetailPageVisible && selectedRoute === ROUTE.ADD_PAGES) && ()} + {(!isDetailPageVisible && selectedRoute === ROUTE.NEW_PROJECT) && ()}
-