docs(vue): show complete code context in the "Your First App" tutorial #4197

soundproofboot · 2025-07-16T17:56:47Z

resolves #4165

Changes:

Update code blocks and text for the Vue Photo App tutorial to show additional context for each step with comments to indicate new lines.

Preview

…t in your first app page 1

…g text

vercel · 2025-07-16T17:56:51Z

@soundproofboot is attempting to deploy a commit to the Ionic Team on Vercel.

A member of the Team first needs to authorize it.

vercel · 2025-07-16T19:48:10Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
ionic-docs	Ready	Preview	Comment	Nov 6, 2025 10:36pm

thetaPC

Minor nitpick

docs/vue/your-first-app/3-saving-photos.md

thetaPC

I noticed that some method names from the Angular version and Vue version do not match even though they have the same code. For example, addNewToGallery from Angular and usePhotoGallery from Vue. Let's also sync those to match Angular as close as possible.

The same goes for the <title>. Let's match it to Angular.

Lastly, some of the content also doesn't match each other. A good example, Angular Build Your First App mentions:

We put the visual aspects of our app into <ion-content>. In this case, it’s where we’ll add a button that opens the device’s camera as well as displays the image captured by the camera. Start by adding a [floating action button](https://ionicframework.com/docs/api/fab) (FAB) to the bottom of the page and set the camera image as the icon.

While Vue states:

We put the visual aspects of our app into <ion-content>. In this case, it’s where we’ll add a button that opens the device’s camera as well as displays the image captured by the camera. But first, remove both the ExploreContainer component and its import statement:

It should match the steps of Angular.

Co-authored-by: Maria Hutt <[email protected]>

…h new Angular docs

…onic-docs into yourFirstAppVue

soundproofboot · 2025-10-04T22:55:28Z

@thetaPC Hi Maria, I tried to make the titles match in Vue and added some <head> content that was in the Angular pages but not Vue. I changed the name of the takePhoto method to addNewGallery to match the Angular method that is comparable. One thing worth noting is these tutorials link to repos so I was trying to not change the code too much and leave the documentation not matching the repo.

On making the steps match Angular, there are more steps required for Vue in that specific case so I think they are slightly reordered to clarify what's being removed and added in Vue (as in remove these two things before we add these other several things) vs. Angular, where I was able to clearly indicate what to remove and add in one code block. I have not looked at this in a while so it may take me a minute to familiarize myself with the frameworks and changes but I'm willing to keep working on this if there are other suggestions.

thetaPC · 2025-10-22T00:33:35Z

@soundproofboot thank you so much! To ensure that all 'Your First App' PRs are merged more quickly, I will be assisting to push them to completion. The main obstacle is synchronizing all three frameworks. Please bear with me as I make the necessary changes.

brandyscarney

Requested some changes on v8 that will also apply to v7. 🙂

brandyscarney · 2025-11-06T20:22:34Z

docs/vue/your-first-app.md

 Next, create an Ionic Vue app that uses the "Tabs" starter template and adds Capacitor for native functionality:

 ```shell
 ionic start photo-gallery tabs --type vue


Why does Angular pass --capacitor but we don't here?

Honestly not sure. This command was here before the edits so I figured that there was a reason for it. Do you think we can remove it from Angular?

The CLI sets it automatically for all of them (except if cordova is passed for Angular), so it looks like we can remove it for Angular and React too:

if (this.schema.type === 'react' || this.schema.type === 'vue') { options['capacitor'] = true; } if ( (this.schema.type === 'angular' || this.schema.type === 'angular-standalone') && options['cordova'] === null ) { options['capacitor'] = true; }

docs/vue/your-first-app.md

brandyscarney · 2025-11-06T20:28:00Z

docs/vue/your-first-app.md


-```html
+```vue
 <ion-title>Photo Gallery</ion-title>


This may be confusing if people interpret it to change the large title to this:

-<ion-title size="large">Tab 2</ion-title> +<ion-title>Photo Gallery</ion-title>

I realize this is the same as the Angular example, just pointing it out because I didn't notice it until this review.

Made the change for Angular: c19dbea

It looks like the v7 version for vue got missed: https://github.com/ionic-team/ionic-docs/pull/4197/files#diff-caf0d45c0315d4fb3d8a52d48018965b3d06ba16af64aad7496ad5c99f3a9a64R174

docs/vue/your-first-app.md

brandyscarney · 2025-11-06T20:33:30Z

docs/vue/your-first-app.md

  IonGrid,
  IonRow,
  IonCol,
  IonImg,


A lot of these imports are unused:

They seem to be used later on. Do we want to show the imports being added when they're actually used?

I was leaning towards showing them as they get added but I ended up working on this too much that I decided to leave it in as is.

Hmmm okay. I think it would be a better user experience if they didn't have errors in their IDE while going through the steps. Maybe we can make a follow-up task for this?

docs/vue/your-first-app/4-loading-photos.md

brandyscarney · 2025-11-06T21:06:10Z

docs/vue/your-first-app/5-adding-mobile.md

+When running on mobile, set `filepath` to the result of the `writeFile()` operation - `savedFile.uri`. When setting the `webviewPath`, use the special `Capacitor.convertFileSrc()` method ([details on the File Protocol](../../core-concepts/webview.md#file-protocol)). To use this method, we'll need to import Capacitor into `usePhotoGallery.ts`.
+
+```ts
+import { Capacitor } from '@capacitor/core';


Wasn't this already done here: https://ionic-docs-git-fork-soundproofboot-yourfirstappvue-ionic1.vercel.app/docs/vue/your-first-app/adding-mobile#import-platform-api

The previous sentence (before the code block) also needs to be removed:

brandyscarney · 2025-11-06T21:08:14Z

docs/vue/your-first-app/5-adding-mobile.md

+
+Then update `savePicture()` to look like the following:
+
+```ts


Looking at this from a broader perspective, I think this example is much easier to follow. When we're updating an existing function, it makes more sense to show only that function. When we're adding a new function, then it's helpful to include the surrounding code for context.

In other examples we show the surrounding code even when nothing in it changes, but that isn't necessary if the updates apply only to one function:

(Above screenshot taken from Platform-specific Logic section)

Ah, the reason I did this was because the examples with the surrounding code were shown at the beginning of the tutorial. As the developer progresses, I expect them to feel comfortable with what they've done so we don't need to have the surrounding code as they would know where in the file is the update function. Thoughts?

Sorry I don't think I was clear. I like that you are only showing the function itself and not the surrounding code when the changes are limited to that function. I was just saying, in general, I think we should do it this way in more places. It's less confusing.

docs/vue/your-first-app/7-live-reload.md

Co-authored-by: Brandy Smith <[email protected]>

docs/vue/your-first-app/4-loading-photos.md

brandyscarney · 2025-11-07T15:27:02Z

docs/vue/your-first-app.md


-```html
+```vue
 <ion-title>Photo Gallery</ion-title>


It looks like the v7 version for vue got missed: https://github.com/ionic-team/ionic-docs/pull/4197/files#diff-caf0d45c0315d4fb3d8a52d48018965b3d06ba16af64aad7496ad5c99f3a9a64R174

docs/vue/your-first-app/7-live-reload.md

brandyscarney · 2025-11-07T15:34:25Z

docs/vue/your-first-app.md

  IonGrid,
  IonRow,
  IonCol,
  IonImg,


Hmmm okay. I think it would be a better user experience if they didn't have errors in their IDE while going through the steps. Maybe we can make a follow-up task for this?

brandyscarney · 2025-11-07T15:36:15Z

docs/vue/your-first-app/5-adding-mobile.md

+When running on mobile, set `filepath` to the result of the `writeFile()` operation - `savedFile.uri`. When setting the `webviewPath`, use the special `Capacitor.convertFileSrc()` method ([details on the File Protocol](../../core-concepts/webview.md#file-protocol)). To use this method, we'll need to import Capacitor into `usePhotoGallery.ts`.
+
+```ts
+import { Capacitor } from '@capacitor/core';


The previous sentence (before the code block) also needs to be removed:

Co-authored-by: Brandy Smith <[email protected]>

soundproofboot added 7 commits July 14, 2025 09:55

docs(vue): add context to code blocks small change to surrounding tex…

c152d58

…t in your first app page 1

docs(vue): add context to code blocks and small changes to surroundin…

59cef22

…g text

docs(vue): add context to code blocks and small changes to surroundin…

2233653

…g text

docs(vue): add context to code blocks and small changes to surroundin…

6a21dbf

…g text

docs(vue): add context to code blocks and small changes to surroundin…

3635891

…g text

docs(vue): add context to code blocks and small changes to surroundin…

6fb72c4

…g text

docs(vue): run linter

bc40cfb

soundproofboot requested a review from a team as a code owner July 16, 2025 17:56

soundproofboot requested a review from christian-bromann July 16, 2025 17:56

vercel bot deployed to Preview July 16, 2025 19:50 View deployment

thetaPC requested changes Sep 24, 2025

View reviewed changes

docs/vue/your-first-app/3-saving-photos.md Outdated Show resolved Hide resolved

thetaPC requested changes Sep 24, 2025

View reviewed changes

soundproofboot and others added 5 commits October 4, 2025 16:02

Update docs/vue/your-first-app/3-saving-photos.md

1cc3efe

Co-authored-by: Maria Hutt <[email protected]>

docs(vue): change name of takePhoto method to addNewToGallery to matc…

c29ede6

…h new Angular docs

docs(vue): add missing title and head tags to match Angular pages

b2926ff

docs(vue): add title to page 7

c0caf4b

Merge branch 'yourFirstAppVue' of https://github.com/soundproofboot/i…

05a1aff

…onic-docs into yourFirstAppVue

docs(vue): update your first app page

1907917

vercel bot deployed to Preview October 22, 2025 00:51 View deployment

docs(vue): update your first app page

e9971d9

vercel bot had a problem deploying to Preview October 22, 2025 22:37 Failure

docs(vue): update your first app page

6fe3e0a

vercel bot deployed to Preview October 22, 2025 22:59 View deployment

docs(vue): update taking photos page

be5b3a6

vercel bot deployed to Preview October 23, 2025 20:32 View deployment

docs(vue): update saving photos page

1f92946

vercel bot deployed to Preview October 29, 2025 19:27 View deployment

thetaPC added 5 commits November 6, 2025 11:02

docs(vue): remove first header

504f0e1

docs(vue): remove exclamation marks

ecf302c

docs(vue): add Camera

3b15eb1

docs(vue): change wording

2414d2f

docs(vue): update existing code comment

34fdce3

vercel bot deployed to Preview November 6, 2025 19:46 View deployment

thetaPC added 6 commits November 6, 2025 12:11

docs(vue): remove period at the end of comments

5bc6bd2

docs(vue): update method string

a179341

docs(vue): update repo url note

a0d3257

docs(vue): add deployment text

6132931

docs(vue): switch to important note

60659ef

docs(vue): update close text

ee3d5e6

brandyscarney reviewed Nov 6, 2025

View reviewed changes

thetaPC and others added 8 commits November 6, 2025 13:32

docs(vue): use readFile

98c520d

docs(vue): use slice

b59639b

Update docs/vue/your-first-app.md

233761a

Co-authored-by: Brandy Smith <[email protected]>

docs(vue): use better title example

ce98715

docs(vue): add missing comment

940c1bb

docs(vue): add file path

5945f1a

docs(vue): remove change comment

d3cbf40

docs(vue): remove import

a9c2c52

vercel bot deployed to Preview November 6, 2025 22:26 View deployment

docs(vue): add surrounding code

81db1c3

vercel bot deployed to Preview November 6, 2025 22:31 View deployment

docs(vue): add styles comment

cef88ca

vercel bot deployed to Preview November 6, 2025 22:36 View deployment

thetaPC requested a review from brandyscarney November 7, 2025 00:51

brandyscarney reviewed Nov 7, 2025

View reviewed changes

Update docs/vue/your-first-app/4-loading-photos.md

eb865fe

Co-authored-by: Brandy Smith <[email protected]>


		Then update `savePicture()` to look like the following:

		```ts

docs(vue): show complete code context in the "Your First App" tutorial #4197

Are you sure you want to change the base?

docs(vue): show complete code context in the "Your First App" tutorial #4197

Conversation

soundproofboot commented Jul 16, 2025 • edited by thetaPC Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Jul 16, 2025

Uh oh!

vercel bot commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thetaPC left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thetaPC left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soundproofboot commented Oct 4, 2025

Uh oh!

thetaPC commented Oct 22, 2025

Uh oh!

brandyscarney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

soundproofboot commented Jul 16, 2025 •

edited by thetaPC

Loading

vercel bot commented Jul 16, 2025 •

edited

Loading

thetaPC left a comment •

edited

Loading