diff --git a/docs/05-Workspace/02-find-in-files.md b/docs/05-Workspace/02-find-in-files.md index 1cbcb425..d309a9e8 100644 --- a/docs/05-Workspace/02-find-in-files.md +++ b/docs/05-Workspace/02-find-in-files.md @@ -1,62 +1,164 @@ --- slug: "/Features/find-in-files" +description: Use the magnifying glass in Phoenix Code to find words across your project, preview matching lines, and open the file you need. Includes folder and file-type filters. +toc_max_heading_level: 2 --- +import TutorialIcon from '@site/src/components/TutorialIcon'; +import TutorialVideo from '@site/src/components/Video/TutorialVideo'; + # Find In Files -The Find in Files feature in Phoenix Code is a powerful tool to quickly search for specific text across multiple files within a project. This feature is useful for developers working on large codebases to find references, variable names, or specific lines of code. +Looking for a word on your website but unsure which file contains it? **Find in Files** searches the text in your project and takes you to the matching lines. + +You'll open a project, search for some words, and open a file from the results. These steps work in **Community (free)** and **Phoenix Pro**. + +## 1. Open your project + +A **project** is the folder containing the files you are working on, such as your website's pages, pictures, and stylesheet. + +**Need files to try this with?** [Download the optional practice website](/tutorials/first-website.zip) and extract the ZIP. Use its `first-website` folder in the next step. + +If your project is already open, keep using it. Otherwise: + +1. Click the in the **top-left corner** of Phoenix Code. This opens the **Start Project** window. +2. Click **Open Folder**. +3. Select the folder containing your files and confirm the selection. For the practice website, select the extracted `first-website` folder. + +You can also open a project through **File → Open Folder…**. + +Check the folder name and files in the **sidebar**, the panel on the left. The screenshots below use a project named `first-website`; yours can have a different name. + +If Live Preview fills the app, click its to show the editor and sidebar. + +### Watch the walkthrough + +The video starts with the project already open. + + + + + Watch the Find in Files walkthrough. + + +## 2. Click the magnifying glass {#use-the-magnifying-glass} + +Look at the small toolbar **above the file list**. Click the just to the right of the . Hovering over the magnifying glass shows **Find in Files**. + +![The first-website folder in the sidebar, with the magnifying glass at the top beside the binoculars](../images/find/magnifier-toolbar.png) + +A search bar labeled **Find in project** opens above the code editor. + +You can also choose **Find → Find in Files**, or press **Ctrl+Shift+F** on Windows/Linux or **Cmd+Shift+F** on macOS. Use the menu if your browser or operating system handles the shortcut instead. + +## 3. Type the words you want to find + +1. Click the search box under **Find in project**. +2. Type a word or phrase that appears in your files. This example searches for `Trail Notes`; use words from your own project. +3. For a search across the project, leave the filter on **No Files Excluded**. Leave **Regular Expression** (`.*`) off when searching for ordinary words. + +[![The Find in project search bar with Trail Notes entered, the Aa and regular-expression buttons off, and No Files Excluded selected](../images/find/magnifier-search.png)](../images/find/magnifier-search.png) + +**Search Results** appears at the bottom of the editor as you type. Drag the panel's top edge upward if you need more room. -To search across your project files, use `Ctrl-Shift-F` on Windows/Linux or `Cmd-Shift-F` on Mac, or select `Find > Find in Files` from the menu. This feature searches for your term throughout the project's files and displays each occurrence with its file name, line number, and a snippet of the code for context. +## 4. Preview a match and open its file -![Alt text](../images/find/fif.png) +A **match** is one place where your search text appears. The results group matches by filename and show the line number beside each matching line. + +[![Search Results showing eight matches for Trail Notes across three files, with about.html line 21 selected and its code preview on the right](../images/find/magnifier-results.png)](../images/find/magnifier-results.png) + +1. Find a filename in the results. Click its small **▸ triangle** if the matching lines are hidden. +2. **Click a matching line once** to preview its code on the right side of Search Results. +3. **Double-click the matching line** to open that file in the main code editor, with the matching words selected. + +In this example, opening the paragraph match under `about.html` takes you to **line 21**. You have now found the file and the exact place containing your text. Searching and opening results leave the file contents unchanged. + +Click either wide screenshot to view it full size. + +## Need help? + +
+Where is the magnifying glass if I can't see it? + +If the sidebar is hidden, choose **View → Show Sidebar**. If Live Preview fills the app, click its first. + +You can also open the search directly with **Find → Find in Files**. + +
+ +
+What does the binoculars button do? + +The is **Show in File Tree**: it locates the file you currently have open in the sidebar. Use the to search for words inside your project files. + +
+ +
+Why are there no results? + +Check the project name on the left and try a word you can see in one of its files. Check spelling, spaces, and punctuation. + +Turn off **Match Case** (`Aa`) to find both capital and lowercase letters. Leave **Regular Expression** (`.*`) off for ordinary text. These buttons appear highlighted when on. + +To remove a file filter, open its dropdown and choose **Don't Exclude Files**. The button will read **No Files Excluded**. If you started a search in a subfolder, click the magnifying glass again to search the whole project. + +
+ +
+How do I change the text I found? + +Follow [Replace text in one file](/docs/tutorials/find-and-replace) to edit the open file, or [Replace text across files](/docs/tutorials/replace-in-files) to review and apply changes throughout a project. + +
## Searching Within a Folder -To search within a specific folder in Phoenix: +Once you're comfortable searching the whole project, you can narrow the search to one folder: -1. Right-click on the folder in the Files panel where you want to perform the search. -1. From the context menu that appears, select "Find in...". - - ![Alt text](../images/find/folder.png) +1. Right-click the folder in the sidebar's file list. +2. Choose **Find in…**. +3. Enter your search text. The search bar shows the selected folder, and results come from that folder and its subfolders. -3. The find bar will now appear with search restricted to that folder (See `in y/` in the below image). - - ![Alt text](../images/find/inFolder.png) +Click the to return to a search across the whole project. ## Using File Filters -By default, Find in Files searches all files in your project folder. You can exclude or include files, file types, whole folders, or other patterns: - -* Click the "No Files Excluded" dropdown from the search bar. +A **file filter** limits which files Phoenix Code searches. For example, you can search just your HTML pages or skip a folder. - ![Alt text](../images/find/new-exclusion.png) +Open the **No Files Excluded** dropdown beside the search box: -Phoenix Code allows you to specify which files and folders should be excluded or included during project searches. +- Choose **Search in files** to search only files whose names or paths match your filter. Enter `*.html` to search HTML files, or `*.html,*.css` to search HTML and CSS files. +- Choose **Exclude files** to skip matching files. Enter `*.json` to skip JSON files. +- Choose **Don't Exclude Files** to clear the restriction. -### For searching only within files matching pattern +Enter the filter in the extra field that appears. Keep the words you want to find in the original search box. -When you select `Search in files` option from the above dropdown, the filter will search only within files and folders that match the entered patterns. Entering `*.json,*.css` will include only JSON and css files in your search results, or just enter `json` to select any files having charecters `json` in its path. See more patterns below. +### Search only matching files {#for-searching-only-within-files-matching-pattern} -![Alt text](../images/find/search_in_files.png) +With **Search in files** selected, `*.html` includes files such as `index.html` and `pages/about.html`. Plain text also works: `css` includes any file with `css` in its path, such as `styles.css` or `css/theme.txt`. -### For Excluding files +### Exclude matching files {#for-excluding-files} -When you select `Exclude files` option from the above dropdown, the filter will ignore files and folders that match the patterns you enter. For instance, typing `*.json` in the text area will exclude all JSON files from your search results. See more patterns below. +With **Exclude files** selected, the same patterns skip files instead. For example, `**/node_modules/**` skips files inside any folder named `node_modules`. ## The filter pattern -This section describes the format of the exclusion/search within files glob pattern. - -1. Each pattern should be entered as a comma seperated text. You can specify multiple patterns: - ```txt - *.js,*.json - ``` -1. To fuzzy search, just enter text. Eg. entering `css` will match all filenames that has the letters `css` in its path name like `x/st.css` and `cssFile.md`. -1. To match all JavaScript files in any directory, use `*.js`. This matches files like `a/b/x.js` and `xyz.js`. -1. To match JavaScript files only in the project root, use `./*.js`. This matches `x.js` in the root but not `y/x.js` in a subdirectory. -1. To match css files only in a folder `search/folder`, use `search/folder/*.css`. This matches `search/folder/x.css` but not `y/x.css`. -1. `?.js` will match only `a/b/x.js` and not `xyx.js` -1. `**/some_folder/**` will match `some_folder` anywhere. -1. `[]` to declare a range of characters to match (`example.[0-9]` to match on `example.0`, `example.1`, …) -1. To search for files names with `,` in it, use escape char `\`. Eg. To match a file with name `hello,world.js`, the filter string to use is `hello\,world.js`. -1. More complex glob patterns can be provided. See: https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns/ +Patterns describe filenames or paths. Use them in either **Search in files** or **Exclude files**. Separate multiple patterns with commas, such as `*.js,*.json`. + +| Pattern | Files it matches | +| --- | --- | +| `css` | Any path containing `css`, such as `styles.css` or `css/theme.txt`. | +| `*.js` | JavaScript files anywhere in the project. | +| `./*.js` | JavaScript files directly inside the project folder, excluding subfolders. | +| `search/folder/*.css` | CSS files directly inside a folder at a path ending in `search/folder`. | +| `?.js` | JavaScript files with a one-character name, such as `x.js`. | +| `**/some_folder/**` | Files inside a folder named `some_folder`, wherever it appears. | +| `example.[0-9]` | Files named `example.0` through `example.9`. | +| `hello\,world.js` | A filename containing a comma, `hello,world.js`. The backslash keeps the comma inside one pattern. | diff --git a/docs/10-Tutorials/06-find-and-replace.md b/docs/10-Tutorials/06-find-and-replace.md new file mode 100644 index 00000000..fec61f66 --- /dev/null +++ b/docs/10-Tutorials/06-find-and-replace.md @@ -0,0 +1,93 @@ +--- +title: Replace text in one file +slug: /tutorials/find-and-replace +description: Find and replace a word or phrase in the file you have open in Phoenix Code. Review each match, replace the text, and save your changes. +image: /tutorials/media/find-replace-one-file.png +toc_max_heading_level: 2 +--- + +import TutorialIcon from '@site/src/components/TutorialIcon'; +import TutorialVideo from '@site/src/components/Video/TutorialVideo'; + +Use **Find → Replace** to change a heading or correct a word in the file you have open. Enter the old text and the words you want to use in its place. + +You'll open a file, find the text, replace it, and save. These steps work in **Community (free)** and **Phoenix Pro**. + +## 1. Open your file + +If Live Preview fills the app, click its to show the editor and sidebar, the file list on the left. + +If the file you want to edit is already open, go to step 2. If its project is open, start at item 3 below. + +**Need a sample file?** [Download the optional practice website](/tutorials/first-website.zip) and extract the ZIP. Use its `first-website` folder and `index.html` file in the steps below. + +1. Click the in the **top-left corner** of Phoenix Code. The **Start Project** window opens. +2. Click **Open Folder**, select the folder containing your files, and confirm. This folder is your **project**. +3. In the sidebar, **double-click the file** you want to change. Its contents open in the code editor. Check the filename above the code. + +![The first-website project in the sidebar, with index.html selected and the folder-with-plus button at the top left](../images/find/magnifier-toolbar.png) + +This example uses `index.html` in the `first-website` project. You can follow the steps with your own file. + +### Watch the walkthrough {#watch-the-steps-in-26-seconds} + +The video starts with the project already open. + + Replace to change a heading, review the highlighted match, and save the file. A 26-second walkthrough using features available in Community and Pro.', + duration: 'PT26S', + dateCreated: '2026-11-10', + }} + poster="/tutorials/media/find-replace-one-file-poster.png" width="1120" height="800" style={{width: '100%', height: 'auto'}} aria-label="26-second walkthrough: find and replace a heading in one file"> + + + Watch the single-file replacement walkthrough. + + +## 2. Enter the old and new text + +1. Open the **Find** menu at the top of the code editor and click **Replace**. Two text boxes appear above the code. +2. In **Find…**, enter the word or phrase you want to change. Use text that appears in this file. +3. In **Replace with…**, enter the new text. +4. Leave the **Regular Expression** (`.*`) button off for an ordinary text search. + +[![Replace in index.html, with A little time outside. in Find, My weekend walks. in Replace with, and the original heading highlighted in the code](/tutorials/media/find-replace-one-file.png)](/tutorials/media/find-replace-one-file.png) + +This example changes `A little time outside.` to `My weekend walks.` Use your own words when following the steps. Click the screenshot to view it full size. + +A **match** is one place where the old text appears. Phoenix Code highlights a match in the editor and shows a count in the search box. **1 of 1** means it found one match in this file. + +## 3. Replace and save + +1. Check the highlighted match in the editor. Use the **◀** and **▶** buttons to move between matches. +2. Click **Replace** to change the highlighted match, or **Replace All** to change every match in this file. +3. Press **Esc** to close the search bar. +4. Choose **File → Save File**, or press **Ctrl+S** on Windows/Linux or **Cmd+S** on macOS. + +**Check that the new text appears where you expected.** In the example, the heading in `index.html` should now read `My weekend walks.` + +**Shortcut:** open Replace with **Ctrl+H** on Windows/Linux or **Cmd+Option+F** on macOS. Use **Find → Replace** if your browser or operating system handles the shortcut instead. + +## Need help? + +
+Why can't I find the text? + +Check that the intended file is open. Copy the text directly from that file to avoid differences in spacing or punctuation. + +Leave **Regular Expression** (`.*`) off. The **Match Case** (`Aa`) button makes capital and lowercase letters matter; turn it off if you want to find both. + +If you don't know which file contains the text, first use [Find in Files](/docs/Features/find-in-files#use-the-magnifying-glass) to locate and open it. + +
+ +
+How do I undo a replacement? + +Choose **Edit → Undo** in the same file, check the result, then save again. + +
+ +To change several files, follow [Replace text across files](/docs/tutorials/replace-in-files). To search across a project, see [Find in Files](/docs/Features/find-in-files). diff --git a/docs/10-Tutorials/07-replace-in-files.md b/docs/10-Tutorials/07-replace-in-files.md new file mode 100644 index 00000000..5f027ed3 --- /dev/null +++ b/docs/10-Tutorials/07-replace-in-files.md @@ -0,0 +1,120 @@ +--- +title: Replace text across files +slug: /tutorials/replace-in-files +description: Find text across your project with the magnifying glass, then use Replace in Files in Phoenix Code to review, replace, and save your changes. +image: /tutorials/media/find-replace-review.png +toc_max_heading_level: 2 +--- + +import TutorialIcon from '@site/src/components/TutorialIcon'; +import TutorialVideo from '@site/src/components/Video/TutorialVideo'; + +Use **Find → Replace in Files** to change the same text on several pages, such as your website's name. Review the matching lines before applying your changes. + +You'll open the project, enter the old and new text, choose the changes to apply, and save. These steps work in **Community (free)** and **Phoenix Pro**. + +## 1. Open your project + +A **project** is the folder containing the files you are working on. If the correct project is already open, keep using it. + +If Live Preview fills the app, click its to show the editor and sidebar, the file list on the left. + +**Need a sample project?** [Download the optional practice website](/tutorials/first-website.zip) and extract the ZIP. Use its `first-website` folder in the steps below. + +To open a project: + +1. Click the in the **top-left corner** of Phoenix Code. The **Start Project** window opens. +2. Click **Open Folder**, select the folder containing your files, and confirm. +3. Check the project name and file list in the sidebar. These are the files you are about to search. + +![The first-website project in the sidebar, showing its three HTML files and the folder-with-plus button at the top left](../images/find/magnifier-toolbar.png) + +The example uses a project named `first-website`. Your project can have a different name. + +### Watch the walkthrough {#watch-the-steps-in-28-seconds} + +The video starts with the project already open. + + + + + Watch the project replacement walkthrough. + + +## 2. Enter the old and new text + +1. Click the above the file list to open **Find in Files**. +2. In **Find…**, enter the text you want to change. Matching lines appear in **Search Results** below the editor. +3. Open the **Find** menu at the top of the code editor and click **Replace in Files**. Your search text stays in **Find…**, and a **Replace with…** box appears. +4. In **Replace with…**, enter the new text. +5. Leave **Regular Expression** (`.*`) off for an ordinary text search. +6. Check the file filter in the search bar. Leave it on **No Files Excluded** to search across the project. +7. Click **Replace…** to open the review list. + +[![Replace in project with Trail Notes in Find, Weekend Notes in Replace with, No Files Excluded selected, and the Replace button that opens the review](/tutorials/media/find-replace-project-fields.png)](/tutorials/media/find-replace-project-fields.png) + +This example changes `Trail Notes` to `Weekend Notes`. Use text from your own project when following the steps. + +**Your files haven't changed yet.** A **match** is one place where the old text appears. The matches are grouped by filename in **Search Results** at the bottom of the editor. Drag the panel's top edge upward if you need more room. + +## 3. Choose which matches to replace + +[![The replacement review lists checked matches across three HTML files, with a Replace button in the results toolbar](/tutorials/media/find-replace-review.png)](/tutorials/media/find-replace-review.png) + +Your review will show the words and files you chose. Click either wide screenshot to view it full size. + +1. Check the old and new text in the review heading. +2. Read the matching lines. Click the small **▸ triangle** beside a filename if its matches are hidden. +3. Keep only the changes you want checked. Clear a match's checkbox to skip it, or clear the checkbox beside a filename to skip the whole file. +4. Click **Replace** in the **results toolbar** to apply the checked changes. + +**Replace…** opens the review; **Replace** in that review applies your selection. + +## 4. Save and check + +1. Choose **File → Save All** to save every changed file. +2. Double-click a changed file in the sidebar and check that the new text appears where you expected. +3. Click the above the file list again to open **Find in Files**. +4. Search for the original text again, keeping the same project and file filters. + +If you replaced every match in that search, you should get **No results**. If you skipped some matches, check that the remaining results are the ones you meant to keep. + +For the practice website, replacing all eight matches updates `index.html`, `about.html`, and `contact.html`. A search for `Trail Notes` should then return **No results**. + +**Shortcut:** open Replace in Files with **Ctrl+Shift+H** on Windows/Linux or **Cmd+Option+Shift+F** on macOS. Use the **Find** menu if your browser or operating system handles the shortcut instead. + +## Need help? + +
+Can I limit the replacement to a folder or file type? + +Right-click a folder in the file list and choose **Replace in…** to work within that folder. To search only HTML files, choose **Search in files** in the filter dropdown and enter `*.html`. + +See [Find in Files filtering](/docs/Features/find-in-files#using-file-filters) for more examples. + +
+ +
+Why is the file count different from the files listed? + +The review header can overcount files in the current web app. Check the filename groups and their matching lines. In the sample screenshot, the eight matches belong to three files, even though the header says six. + +
+ +
+Can I undo the replacements? + +Open each changed file and choose **Edit → Undo** there, then choose **File → Save All**. One Undo does not revert every file in the project. + +On larger projects, Phoenix Code may show **Replace Without Undo**. That option can change unopened files on disk without an undo history. Cancel and make a backup of your project before continuing. + +
+ +For a change in just one file, follow [Replace text in one file](/docs/tutorials/find-and-replace). For search instructions, see [Find in Files](/docs/Features/find-in-files). diff --git a/docs/10-Tutorials/index.md b/docs/10-Tutorials/index.md index 58c08879..344c2382 100644 --- a/docs/10-Tutorials/index.md +++ b/docs/10-Tutorials/index.md @@ -24,8 +24,13 @@ The guides open with **Phoenix Pro**, using Design Mode for visual editing. Choo - **[Build a page with Bootstrap](/docs/tutorials/bootstrap):** open a ready-made page, change its button color, and try it at a phone-sized width. - **[Run your first Python program](/docs/tutorials/run-python):** create a file and make it print a message in the desktop app. +## Work with text + +- **[Find in Files](/docs/Features/find-in-files):** search across your project and open a matching line. +- **[Replace text in one file](/docs/tutorials/find-and-replace):** change a word or phrase in the file you have open. +- **[Replace text across files](/docs/tutorials/replace-in-files):** review matches and apply selected changes across your project. + ## Get help with the editor -- [Find text across your project](/docs/Features/find-in-files) - [Open or create a project](/docs/quick-start-project) - [Install extensions and themes](/docs/extensions) diff --git a/docs/images/find/magnifier-results.png b/docs/images/find/magnifier-results.png new file mode 100644 index 00000000..977fb52f Binary files /dev/null and b/docs/images/find/magnifier-results.png differ diff --git a/docs/images/find/magnifier-search.png b/docs/images/find/magnifier-search.png new file mode 100644 index 00000000..32ea35d8 Binary files /dev/null and b/docs/images/find/magnifier-search.png differ diff --git a/docs/images/find/magnifier-toolbar.png b/docs/images/find/magnifier-toolbar.png new file mode 100644 index 00000000..21ec2378 Binary files /dev/null and b/docs/images/find/magnifier-toolbar.png differ diff --git a/scripts/tutorial-media-manifest.json b/scripts/tutorial-media-manifest.json index 562b915b..ca9eba89 100644 --- a/scripts/tutorial-media-manifest.json +++ b/scripts/tutorial-media-manifest.json @@ -1,5 +1,5 @@ { - "captured_at": "2026-11-10", + "captured_at": "2026-11-11", "product": "Phoenix Code for the web", "product_url": "https://web.phcode.dev/", "projects": { @@ -40,6 +40,42 @@ 980 ], "caption_placement": "Above the screen recording, clear of player controls" + }, + { + "file": "static/tutorials/media/find-replace-one-file.mp4", + "project": "first-website", + "workflow": "Project already open: double-click index.html, choose Find > Replace, enter the old heading and new text, check the highlighted match, replace it, and choose File > Save File", + "on_screen_instructions": true, + "highlighted_controls": true, + "system_file_picker_recorded": false, + "duration_seconds": 26, + "duration_limit_seconds": 30, + "frame_size": [1120, 800], + "caption_placement": "Above the screen recording, clear of player controls" + }, + { + "file": "static/tutorials/media/replace-in-files.mp4", + "project": "first-website", + "workflow": "Project already open: click the magnifying glass to open Find in Files, search Trail Notes, switch through Find > Replace in Files while keeping that query, enter Weekend Notes, review and select matches, apply replacements, choose Save All, then click the magnifying glass again and search the old name to confirm no results", + "on_screen_instructions": true, + "highlighted_controls": true, + "system_file_picker_recorded": false, + "duration_seconds": 28, + "duration_limit_seconds": 30, + "frame_size": [1120, 800], + "caption_placement": "Above the screen recording, clear of player controls" + }, + { + "file": "static/tutorials/media/find-in-files.mp4", + "project": "first-website", + "workflow": "Project already open: click the magnifying glass to open Find in Files, search Trail Notes, read the results grouped by filename, click a matching line once to preview its code, double-click it to open about.html at line 21, and close Search Results to see the selected text in the editor", + "on_screen_instructions": true, + "highlighted_controls": true, + "system_file_picker_recorded": false, + "duration_seconds": 24, + "duration_limit_seconds": 30, + "frame_size": [1120, 800], + "caption_placement": "Above the screen recording, clear of player controls" } ], "sample_photo": { @@ -65,7 +101,12 @@ "Pro link text and contact.html destination edited and saved in Design Mode", "Phoenix Pro is first and selected for fresh readers; explicit Community choices remain remembered across guides", "Complete Attributes screenshot renders all four rows without cropping on mobile", - "Pro recording closes the gallery and scrolls Element Properties until src, alt, width, and height are all fully visible" + "Pro recording closes the gallery and scrolls Element Properties until src, alt, width, and height are all fully visible", + "Single-file replacement recording saves the changed heading in first-website/index.html", + "Project replacement recording saves eight names across three HTML files and verifies that the old name returns no results", + "Replacement videos are 26 and 28 seconds, with timed instruction captions and highlighted controls", + "Project replacement video starts with the magnifying glass opening Find in Files, preserves the query when switching to Replace in Files, and uses the magnifying glass again for the final check", + "Workspace Find in Files recording finds eight matches across three files, previews a match with one click, and opens about.html at line 21 with a double-click while leaving the practice files unchanged" ], "attributes_screenshot": { "file": "static/tutorials/media/pro-image-description-complete.png", @@ -77,6 +118,6 @@ "height" ] }, - "presentation": "One complete walkthrough per edition, with screenshots and native video controls", + "presentation": "Separate walkthroughs for each tutorial task or edition, with screenshots and native video controls", "playback": "Muted inline autoplay when visible; pauses offscreen and in hidden tabs, preserves the reader's pause, and starts manually for reduced-motion preferences" } diff --git a/scripts/verify-tutorials.cjs b/scripts/verify-tutorials.cjs index 7121e31d..07f6cf1e 100644 --- a/scripts/verify-tutorials.cjs +++ b/scripts/verify-tutorials.cjs @@ -11,7 +11,8 @@ const {PUBLICATIONS_PATH, validatePublications} = require('../plugins/tutorial-m const SITE = path.join(__dirname, '..'); const ORIGIN = 'https://docs.phcode.dev'; const GUIDES = ['tutorials', 'tutorials/add-images', 'tutorials/link-pages', - 'tutorials/share-website', 'tutorials/bootstrap', 'tutorials/run-python']; + 'tutorials/share-website', 'tutorials/bootstrap', 'tutorials/run-python', + 'tutorials/find-and-replace', 'tutorials/replace-in-files', 'Features/find-in-files']; function videoDuration(file) { const data = fs.readFileSync(file); @@ -109,26 +110,32 @@ function verify(build, release = false) { assert.equal(imagePage('article details').length, 5, 'Expected five image FAQs'); const captures = JSON.parse(fs.readFileSync(path.join(SITE, 'scripts/tutorial-media-manifest.json'), 'utf8')); const publications = validatePublications(JSON.parse(fs.readFileSync(path.join(build, PUBLICATIONS_PATH), 'utf8'))).videos; - const schemas = imagePage('script[type="application/ld+json"]').toArray() - .map(element => JSON.parse(imagePage(element).text())).filter(schema => schema['@type'] === 'VideoObject'); - assert.equal(schemas.length, 2, 'Expected two video metadata entries'); - assert.equal(captures.recordings.length, 2, 'Expected two recorded videos'); - assert.equal(new Set(schemas.map(schema => schema.name)).size, 2, 'Video names must be distinct'); - const attributes = (selector, name) => new Set(imagePage(selector).map((_, element) => imagePage(element).attr(name)).get()); - const sources = attributes('article source', 'src'); - const posters = attributes('article video', 'poster'); - const tracks = attributes('article track', 'src'); - for (const schema of schemas) { + const videos = GUIDES.flatMap(guide => { + const document = page(target('/docs/' + guide)); + const schemas = document('script[type="application/ld+json"]').toArray() + .map(element => JSON.parse(document(element).text())).filter(schema => schema['@type'] === 'VideoObject'); + assert.equal(schemas.length, document('article video').length, `Video metadata missing: ${guide}`); + return schemas.map(schema => ({schema, document})); + }); + assert.equal(videos.length, captures.recordings.length, 'Every recorded video must have a player and metadata'); + assert.equal(new Set(videos.map(({schema}) => schema.contentUrl)).size, videos.length, 'Video sources must be distinct'); + assert.equal(new Set(videos.map(({schema}) => schema.name)).size, videos.length, 'Video names must be distinct'); + for (const {schema, document} of videos) { const source = new URL(schema.contentUrl).pathname; - assert(sources.has(source) && schema.description && schema.name, `Incomplete video metadata: ${source}`); - assert(posters.has(new URL(schema.thumbnailUrl[0]).pathname), `Video poster mismatch: ${source}`); - assert(tracks.has(new URL(schema.caption.contentUrl).pathname), `Video captions mismatch: ${source}`); + const player = document('article video').toArray().find(element => document(element).find('source').attr('src') === source); + assert(player && schema.description && schema.name, `Incomplete video metadata: ${source}`); + assert.equal(document(player).attr('poster'), new URL(schema.thumbnailUrl[0]).pathname, `Video poster mismatch: ${source}`); + assert.equal(document(player).find('track[kind="captions"]').attr('src'), new URL(schema.caption.contentUrl).pathname, `Video captions mismatch: ${source}`); for (const url of [schema.contentUrl, schema.thumbnailUrl[0], schema.caption.contentUrl]) target(url); const duration = videoDuration(target(source)); const durationMatch = /^PT(\d+(?:\.\d+)?)S$/.exec(schema.duration); assert(durationMatch && Math.abs(Number(durationMatch[1]) - duration) < 0.02, `Incorrect duration: ${source}`); const captured = captures.recordings.find(record => '/' + record.file.replace(/^static\//, '') === source); assert(captured && Math.abs(captured.duration_seconds - duration) < 0.02, `Capture duration mismatch: ${source}`); + if (captured.duration_limit_seconds !== undefined) { + assert(Number.isFinite(captured.duration_limit_seconds) && captured.duration_limit_seconds > 0, `Invalid duration limit: ${source}`); + assert(duration < captured.duration_limit_seconds, `Video exceeds its duration limit: ${source}`); + } assert.equal(schema.uploadDate, publications[source], `Publication date mismatch: ${source}`); if (release) assert(schema.uploadDate, `Release video has no first-publication date: ${source}`); const captions = fs.readFileSync(target(schema.caption.contentUrl), 'utf8').replace(/\r\n/g, '\n'); @@ -165,7 +172,7 @@ function verify(build, release = false) { assert(Buffer.from(archive[`${project}/${name}`]).equals(content), `Stale practice file: ${project}/${name}`); } } - return `PASS: ${GUIDES.length} guides, local links and anchors, screenshots, 5 FAQs, 2 videos with captions, ${indexLinks} AI-index links, and both practice ZIPs.` + + return `PASS: ${GUIDES.length} guides, local links and anchors, screenshots, 5 image FAQs, ${videos.length} videos with captions, ${indexLinks} AI-index links, and both practice ZIPs.` + (release ? ' Release publication dates are complete.' : ' Preview metadata verified.'); } diff --git a/src/components/TutorialIcon/LICENSE-BOOTSTRAP-ICONS.txt b/src/components/TutorialIcon/LICENSE-BOOTSTRAP-ICONS.txt new file mode 100644 index 00000000..4d24b112 --- /dev/null +++ b/src/components/TutorialIcon/LICENSE-BOOTSTRAP-ICONS.txt @@ -0,0 +1,19 @@ +The MIT License (MIT) + +Copyright (c) 2019-2024 The Bootstrap Authors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/src/components/TutorialIcon/icons.js b/src/components/TutorialIcon/icons.js index 1e3e87ce..4d0c2b60 100644 --- a/src/components/TutorialIcon/icons.js +++ b/src/components/TutorialIcon/icons.js @@ -1,8 +1,11 @@ -// Icon geometry from Phoenix Code and its bundled Font Awesome Free 6.1.2. -// Source paths and attribution are recorded in sources.json and LICENSE-FONT-AWESOME.txt. +// Icon geometry from Phoenix Code, Bootstrap Icons, and bundled Font Awesome Free 6.1.2. +// Source paths and attribution are recorded in sources.json and the adjacent license files. import React from 'react'; export default { + startProject: (), + search: (), + showInTree: (), expand: (), restore: (), pen: (), diff --git a/src/components/TutorialIcon/sources.json b/src/components/TutorialIcon/sources.json index b7942bbc..c961cc91 100644 --- a/src/components/TutorialIcon/sources.json +++ b/src/components/TutorialIcon/sources.json @@ -5,8 +5,16 @@ "license": "CC BY 4.0", "url": "https://fontawesome.com/license/free" }, + "bootstrap_icons": { + "copyright": "2019-2024 The Bootstrap Authors", + "license": "MIT", + "url": "https://github.com/twbs/icons/blob/main/LICENSE" + }, "adaptation": "Original shapes; colors inherit the documentation theme. SVG sprite symbols are isolated from their source sheets.", "icons": { + "startProject": "phoenix/src/styles/images/sprites.svg#newFolder", + "search": "phoenix/src/styles/images/sprites.svg#search", + "showInTree": "phoenix/src/styles/images/sprites.svg#binoculars", "expand": "svgs/solid/expand.svg", "restore": "svgs/solid/compress.svg", "pen": "svgs/solid/pencil.svg", diff --git a/static/tutorials/media/find-in-files-poster.png b/static/tutorials/media/find-in-files-poster.png new file mode 100644 index 00000000..4ee6a869 Binary files /dev/null and b/static/tutorials/media/find-in-files-poster.png differ diff --git a/static/tutorials/media/find-in-files.mp4 b/static/tutorials/media/find-in-files.mp4 new file mode 100644 index 00000000..1669a465 Binary files /dev/null and b/static/tutorials/media/find-in-files.mp4 differ diff --git a/static/tutorials/media/find-in-files.vtt b/static/tutorials/media/find-in-files.vtt new file mode 100644 index 00000000..68c67c72 --- /dev/null +++ b/static/tutorials/media/find-in-files.vtt @@ -0,0 +1,19 @@ +WEBVTT + +00:00:00.000 --> 00:00:03.000 +1. Click the magnifying glass to open Find in Files. + +00:00:03.000 --> 00:00:07.000 +2. Type Trail Notes to search the project. + +00:00:07.000 --> 00:00:11.000 +3. Results group matching lines by filename. + +00:00:11.000 --> 00:00:16.000 +4. Click a matching line once to preview its code. + +00:00:16.000 --> 00:00:20.000 +5. Double-click the same line to open its file. + +00:00:20.000 --> 00:00:24.000 +6. Close Search Results to see about.html at line 21. diff --git a/static/tutorials/media/find-replace-one-file-poster.png b/static/tutorials/media/find-replace-one-file-poster.png new file mode 100644 index 00000000..4d7e2405 Binary files /dev/null and b/static/tutorials/media/find-replace-one-file-poster.png differ diff --git a/static/tutorials/media/find-replace-one-file.mp4 b/static/tutorials/media/find-replace-one-file.mp4 new file mode 100644 index 00000000..4616e292 Binary files /dev/null and b/static/tutorials/media/find-replace-one-file.mp4 differ diff --git a/static/tutorials/media/find-replace-one-file.png b/static/tutorials/media/find-replace-one-file.png new file mode 100644 index 00000000..7aa4ee6e Binary files /dev/null and b/static/tutorials/media/find-replace-one-file.png differ diff --git a/static/tutorials/media/find-replace-one-file.vtt b/static/tutorials/media/find-replace-one-file.vtt new file mode 100644 index 00000000..3edd09e4 --- /dev/null +++ b/static/tutorials/media/find-replace-one-file.vtt @@ -0,0 +1,26 @@ +WEBVTT + +00:00:00.000 --> 00:00:03.000 +1. Double-click index.html in the file list. + +00:00:03.000 --> 00:00:06.000 +2. Open Find, then choose Replace. + +00:00:06.000 --> 00:00:09.500 +3. Type the words you want to change. + +00:00:09.500 --> 00:00:13.000 +4. Enter the new text in Replace with. + +00:00:13.000 --> 00:00:16.000 +5. Check the highlighted match. Here there is one. + +00:00:16.000 --> 00:00:19.000 +6. Click Replace to change this match. + +00:00:19.000 --> 00:00:22.500 +7. Press Esc, then choose File > Save File. + +00:00:22.500 --> 00:00:26.000 +Saved. The heading now reads: My weekend walks. + diff --git a/static/tutorials/media/find-replace-project-fields.png b/static/tutorials/media/find-replace-project-fields.png new file mode 100644 index 00000000..7f3f2d3e Binary files /dev/null and b/static/tutorials/media/find-replace-project-fields.png differ diff --git a/static/tutorials/media/find-replace-review.png b/static/tutorials/media/find-replace-review.png new file mode 100644 index 00000000..1ffe635e Binary files /dev/null and b/static/tutorials/media/find-replace-review.png differ diff --git a/static/tutorials/media/replace-in-files-poster.png b/static/tutorials/media/replace-in-files-poster.png new file mode 100644 index 00000000..0ca9389b Binary files /dev/null and b/static/tutorials/media/replace-in-files-poster.png differ diff --git a/static/tutorials/media/replace-in-files.mp4 b/static/tutorials/media/replace-in-files.mp4 new file mode 100644 index 00000000..2df096ab Binary files /dev/null and b/static/tutorials/media/replace-in-files.mp4 differ diff --git a/static/tutorials/media/replace-in-files.vtt b/static/tutorials/media/replace-in-files.vtt new file mode 100644 index 00000000..e5c92bf0 --- /dev/null +++ b/static/tutorials/media/replace-in-files.vtt @@ -0,0 +1,29 @@ +WEBVTT + +00:00:00.000 --> 00:00:03.000 +1. Click the magnifying glass to open Find in Files. + +00:00:03.000 --> 00:00:06.000 +2. Type Trail Notes to find the matching lines. + +00:00:06.000 --> 00:00:09.000 +3. To change the text, choose Find > Replace in Files. + +00:00:09.000 --> 00:00:12.000 +4. Enter the new name: Weekend Notes. + +00:00:12.000 --> 00:00:14.500 +5. Click Replace... to review the changes. + +00:00:14.500 --> 00:00:17.500 +6. Keep checked only the changes you want. + +00:00:17.500 --> 00:00:20.000 +7. Click Replace in the review to apply them. + +00:00:20.000 --> 00:00:23.000 +8. Choose File > Save All. + +00:00:23.000 --> 00:00:28.000 +9. Click the magnifying glass. Search again: No results. +