Merge pull request #249696 from HeidiSteen/heidist-js

[azure search] Search web appt tutorial (workaround for SWA YML path issue)

Author: v-ccolin

articles/search/includes/tutorial-add-search-website-create-app.md

@@ -1,6 +1,6 @@
 ---
 ms.topic: include
-ms.date: 07/18/2023
+ms.date: 08/29/2023
 author: HeidiSteen
 ms.author: heidist
 ms.service: cognitive-search
@@ -12,73 +12,108 @@ The static web app pulls the information and files for deployment from GitHub us
 
 ## Create a Static Web App in Visual Studio Code
 
-1. Select **Azure** from the Activity Bar, then open **Resources** from the Side bar. 
+1. In Visual Studio Code, open a folder at the repository root (`azure-search-javascript-samples`).
 
-1. Right-click **Static Web Apps** and then select **Create Static Web App (Advanced)**.
+1. Select **Azure** from the Activity Bar, then open **Resources** from the side bar. 
+
+1. Right-click **Static Web Apps** and then select **Create Static Web App (Advanced)**. If you don't see this option, verify that you have the Azure Functions extension for Visual Studio Code.
 
     :::image type="content" source="../media/tutorial-javascript-create-load-index/visual-studio-code-create-static-web-app-resource-advanced.png" alt-text="Screenshot of Visual Studio Code, with the Azure Static Web Apps explorer showing the option to create an advanced static web app.":::
 
-1. If you see a pop-up window in VS Code asking which branch you want to deploy from, select the default branch, usually **master** or **main**. 
+1. If you see a pop-up window in Visual Studio Code asking which branch you want to deploy from, select the default branch, usually **main**. 
 
     This setting means only changes you commit to that branch are deployed to your static web app. 
 
 1. If you see a pop-up window asking you to commit your changes, don't do this. The secrets from the bulk import step shouldn't be committed to the repository. 
 
-    To roll back the changes, in VS Code select the Source Control icon in the Activity bar, then select each changed file in the Changes list and select the **Discard changes** icon.
+    To roll back the changes, in Visual Studio Code select the Source Control icon in the Activity bar, then select each changed file in the Changes list and select the **Discard changes** icon.
 
-1. Follow the prompts to provide the following information:
+1. Follow the prompts to create the static web app:
 
     |Prompt|Enter|
     |--|--|
-    |Select a resource group for new resources.|Use the resource group you created for this tutorial.|
-    |Enter the name for the new Static Web App.|Create a unique name for your resource. For example, you can prepend your name to the repository name such as, `joansmith-azure-search-dotnet-samples`. |
-    |Select a SKU| Select the free SKU for this tutorial.|
-    |Select a location for new resources.|For Node.js: Select `West US 2` during the Azure Function programming model (PM) v4 preview. For C# and Python, select a region near you.|
-    |Choose build preset to configure default project structure.|Select **Custom**|
-    |Select the location of your application code|`search-website-functions-v4/client-v4`<br><br>This is the path, from the root of the repository, to your static web app. |
-    |Select the location of your Azure Functions code|`search-website-functions-v4/api-v4`<br><br>This is the path, from the root of the repository, to your static web app. |
-    |Enter the path of your build output...|`build`<br><br>This is the path, from your static web app, to your generated files.|
+    |Select a resource group for new resources. | Use the resource group you created for this tutorial.|
+    |Enter the name for the new Static Web App. | Create a unique name for your resource. For example, you can prepend your name to the repository name such as, `my-demo-static-web-app`. |
+    |Select a SKU | Select the free SKU for this tutorial.|
+    |Select a location for new resources. | For Node.js: Select `West US 2` during the Azure Function programming model (PM) v4 preview. For C# and Python, select a region near you. |
+    |Choose build preset to configure default project structure. |Select **Custom**. |
+    |Select the location of your client application code | `search-website-functions-v4/client-v4`<br><br>This is the path, from the root of the repository, to your static web app. |
+    |Select the location of your Azure Functions code | `search-website-functions-v4/api-v4`<br><br>This is the path, from the root of the repository, to your static web app. If there are no other functions in the repository, you won't be prompted for the function code location. Currently, you'll need to perform extra steps to ensure the function code location is correct. These steps are performed after the resource is created and are documented in this article. |
+    |Enter the path of your build output... | `build`<br><br>This is the path, from your static web app, to your generated files.|
+
+    If you get an error about an incorrect region, make sure the resource group and static web app resource are in one of the supported regions listed in the error response. 
+
+1. When the static web app is created, a GitHub workflow YML file is also created locally and on GitHub in your fork. This workflow executes in your fork, building and deploying the static web app and functions.
+
+   Check the status of static web app deployment using any of these approaches:
+
+   * Select **Open Actions in GitHub** from the Notifications. This opens a browser window pointed to your forked repo.
+   * Select the **Actions** tab in your forked repository. You should see a list of all workflows on your fork.
+   * Select the **Azure: Activity Log** in Visual Code. You should see a message similar to the following screenshot.
+
+     :::image type="content" source="../media/tutorial-javascript-static-web-app/visual-studio-code-azure-activity-log.png" alt-text="Screenshot of the Activity Log in Visual Studio Code." border="true":::
+
+1. Currently, the YML file is created with erroneous path syntax for the Azure function code. Use this workaround to correct the syntax. You can perform this step as soon as the YML file is created. A new workflow will launch as soon as you push the updates:
 
-    If you get an error about an incorrect region, make sure the resource group and Static web app resource are in one of the supported regions listed in the error response. 
+   1. In Visual Studio Code explorer, open the `./.github/workflows/` directory.
 
-1. The resource is created and a notification window appears. 
+   1. Open the YML file.
 
-     When the resource is created, it creates a GitHub action file on GitHub.
+   1. Scroll to the `api-location` path (on or near line 31).
 
-1. Select **Open Actions in GitHub** from the Notifications. This opens a browser window pointed to your forked repo. 
+   1. Change the path syntax to use a forward slash (only `api_location` needs editing, other locations are here for context):
 
-    Wait until the _workflow_ completes before continuing. This may take a minute or two to finish. 
+      ```yml
+      app_location: "search-website-functions-v4/client-v4" # App source code path
+      api_location: "search-website-functions-v4/api-v4" # Api source code path - optional
+      output_location: "build" # Built app content directory - optional
+      ```
 
-1. Pull the new GitHub action file to your local computer by synchronizing your local fork with your remote fork:
+   1. Save the file.
+
+   1. Open an integrated terminal and issue the following GitHub commands to send the updated YML to your fork:
+
+      ```bash
+      git add -A
+      git commit -m "fix path"
+      git push origin main
+      ```
+
+     :::image type="content" source="../media/tutorial-javascript-static-web-app/git-yml-path-workaround.png" alt-text="Screenshot of the GitHub commands in Visual Studio Code." border="true":::
+
+    Wait until the workflow execution completes before continuing. This may take a minute or two to finish. 
+
+<!-- 1. Pull the new GitHub action file to your local computer by synchronizing your local fork with your remote fork:
 
     ```bash
     git pull origin main
     ```
 
     * _origin_ refers to your forked repo. 
     * _main_ refers to the default branch.
+ -->
 
-1. In Visual Studio file explorer, find and open the workflow file in the `./.github/workflows/` directory. The file path and name looks _something_ `.github\workflows\azure-static-web-apps-lemon-mushroom-0e1bd060f.yml`.
+<!-- 1. In Visual Studio file explorer, find and open the workflow file in the `./.github/workflows/` directory. The file path and name looks _something_ `.github\workflows\azure-static-web-apps-lemon-mushroom-0e1bd060f.yml`.
 
     The _part_ of the YAML file relevant to the static web app is shown below:
 
-    :::code language="yml" source="~/azure-search-javascript-samples/search-website-functions-v4/example-github-action-v4.yml":::
+    :::code language="yml" source="~/azure-search-javascript-samples/search-website-functions-v4/example-github-action-v4.yml"::: -->
 
 ## Get Cognitive Search query key in Visual Studio Code
 
 1. In Visual Studio Code, open a new terminal window.
 
-1. Get the Query Key with this Azure CLI command:
+1. Get the query API key with this Azure CLI command:
 
     ```azurecli
     az search query-key list --resource-group cognitive-search-demo-rg --service-name my-cog-search-demo-svc
     ```
 
-1. Keep this query key, you'll need to use it in the next section. The query key is able to query your Index. 
+1. Keep this query key to use in the next section. The query key authorizes read access to a search index. 
 
 ## Add configuration settings in Azure portal
 
-The Azure Function app won't return Search data until the Search secrets are in settings. 
+The Azure Function app won't return search data until the search secrets are in settings. 
 
 1. Select **Azure** from the Activity Bar. 
 1. Right-click on your Static Web Apps resource then select **Open in Portal**.
@@ -93,21 +128,22 @@ The Azure Function app won't return Search data until the Search secrets are in
 
     |Setting|Your Search resource value|
     |--|--|
-    |SearchApiKey|Your Search query key|
-    |SearchServiceName|Your Search resource name|
+    |SearchApiKey|Your search query key|
+    |SearchServiceName|Your search resource name|
     |SearchIndexName|`good-books`|
     |SearchFacets|`authors*,language_code`|
 
     Azure Cognitive Search requires different syntax for filtering collections than it does for strings. Add a `*` after a field name to denote that the field is of type `Collection(Edm.String)`. This allows the Azure Function to add filters correctly to queries.
 
 1. Select **Save** to save the settings. 
 
-    :::image type="content" source="../media/tutorial-javascript-static-web-app/save-new-application-setting-to-static-web-app-in-portal.png" alt-text="Screenshot of browser showing Azure portal with the button to save the settings for your app..":::
+    :::image type="content" source="../media/tutorial-javascript-static-web-app/save-new-application-setting-to-static-web-app-in-portal.png" alt-text="Screenshot of browser showing Azure portal with the button to save the settings for your app.":::
+
+1. Return to Visual Studio Code. 
 
-1. Return to VS Code. 
-1. Refresh your static web app to see the application settings. 
+1. Refresh your static web app to see the application settings and functions.
 
-    :::image type="content" source="../media/tutorial-javascript-static-web-app/visual-studio-code-extension-fresh-resource.png" alt-text="Screenshot of Visual Studio Code showing the Azure Static Web Apps explorer with the new application settings.":::
+    :::image type="content" source="../media/tutorial-javascript-static-web-app/visual-studio-code-extension-fresh-resource-2.png" alt-text="Screenshot of Visual Studio Code showing the Azure Static Web Apps explorer with the new application settings." border="true":::
 
 ## Use search in your static web app
 
@@ -121,7 +157,6 @@ The Azure Function app won't return Search data until the Search secrets are in
 1. In the website search bar, enter a search query such as `code`, so the suggest feature suggests book titles. Select a suggestion or continue entering your own query. Press enter when you've completed your search query. 
 1. Review the results then select one of the books to see more details. 
 
-
 ## Troubleshooting
 
 [!INCLUDE [tutorial-troubleshooting](tutorial-add-search-website-troubleshooting.md)]

articles/search/includes/tutorial-add-search-website-fork-and-clone.md

@@ -10,12 +10,14 @@ If the web app didn't deploy or work, use the following list to determine and fi
 
 * **Did the deployment succeed?** 
 
-    In order to determine if your deployment succeeded, you need to go to _your_ fork of the sample repo and review the success or failure of the GitHub action. There should be only 1 action and it should have static web app settings for the  `app_location`, `api_location`, and `output_location`. If the action didn't deploy successfully, dive into the action logs and look for the last failure. 
+    In order to determine if your deployment succeeded, you need to go to _your_ fork of the sample repo and review the success or failure of the GitHub action. There should be only one action and it should have static web app settings for the  `app_location`, `api_location`, and `output_location`. If the action didn't deploy successfully, dive into the action logs and look for the last failure. 
 
 * **Does the client (front-end) application work?**
 
-    You should be able to get to your web app and it should successfully display. If the deployment succeeded but the website doesn't display, this may be an issue with how the static web app is configured for rebuilding the app, once it is on Azure.
+    You should be able to get to your web app and it should successfully display. If the deployment succeeded but the website doesn't display, this may be an issue with how the static web app is configured for rebuilding the app, once it is on Azure. 
 
 * **Does the API (serverless back-end) application work?**
 
-    You should be able to interact with the client app, searching for books and filtering. If the form doesn't return any values, open the browser's developer tools, and determine if the HTTP calls to the API were successful. If the calls weren't successful, the most likely reason if the static web app configurations for the API endpoint name and Search query key are incorrect. 
+    You should be able to interact with the client app, searching for books and filtering. If the form doesn't return any values, open the browser's developer tools, and determine if the HTTP calls to the API were successful. If the calls weren't successful, the most likely reason if the static web app configurations for the API endpoint name and Search query key are incorrect.
+
+    If the path to the Azure function code (`api_location`) isn't correct in the YML file, the application loads but won't call any of the functions that provide integration with Cognitive Search. Revisit the workaround in the deployment section for help with correcting the path.

articles/search/includes/tutorial-add-search-website-troubleshooting.md

@@ -7,10 +7,12 @@ ms.service: cognitive-search
 ---
 This sample website provides access to a catalog of 10,000 books. A user can search the catalog by entering text in the search bar. While the user enters text, the website uses the search index's suggest feature to complete the text. Once the query finishes, the list of books is displayed with a portion of the details. A user can select a book to see all the details, stored in the search index, of the book. 
 
-:::image type="content" source="../media/tutorial-javascript-overview/cognitive-search-enabled-book-website.png" alt-text="This sample website provides access to a catalog of 10,000 books. A user can search the catalog by entering text in the search bar. While the user enters text, the website uses the search index's suggest feature to complete the text. Once the search finishes, the list of books is displayed with a portion of the details. A user can select a book to see all the details, stored in the search index, of the book.":::
+:::image type="content" source="../media/tutorial-javascript-overview/cognitive-search-enabled-book-website-2.png" alt-text="Screenshot of the sample app in a browser window.":::
 
-The search experience includes: 
+The search experience includes:
 
 * Search – provides search functionality for the application.
 * Suggest – provides suggestions as the user is typing in the search bar.
+* Facets and filters - provides a faceted navigation structure that filters by author or language.
+* Paginated results - provides paging controls for scrolling through results.
 * Document Lookup – looks up a document by ID to retrieve all of its contents for the details page.