Feature: Style Guide Snippets

[joshwiens]

Issue for tracking the creation of snippets for popular editors based on the recommendations in the guide.

List of planned snippets will grow as their styling recommendations are solidified.

Supported Editors

• Atom - https://github.com/d3viant0ne/angular2-atom-snippets by @d3viant0ne
• VS Code - https://github.com/d3viant0ne/angular2-vscode-snippets by @d3viant0ne
• Sublime Text 3 - https://github.com/evanplaice/angular2-snippets by @evanplaice
• WebStorm - https://github.com/d3viant0ne/angular2-webstorm-snippets by @d3viant0ne

Planned JS / TS Snippets

• Components
• Directives
• Pipes
• Services
• RouteConfig
• Route
• Test

Planned HTML Snippets

• ngFor
• ngIF
• ngSwitch
• ngSwitchWhen
• ngSwitchDefault
• ngClass
• ngModel
• ngForm

Completion Categories

• Annotations
• Decorators
• Lifecycle
• Routing
• Directives
• Attributes
• Pipes

[evanplaice]

Repo for Sublime Text snippets/completions:
https://github.com/evanplaice/angular2-snippets

[joshwiens]

Repo for Atom snippets/completions:
https://github.com/d3viant0ne/angular2-atom-snippets

[evanplaice]

I spent some time digging through the Angular2 API and expanded the list of snippets.

Here's what I've come up with so far.

Snippet Categories:

• Component

  The @component class decorator w/ multiple variations.

• Directive

  The @directive class decorator w/ multiple variations.

• Service

  Service snippet w/ @Injectable. Are there other variations?

• Pipe

  Pipe snippet w/ @pipe and transform() function. Are there other variations?

• RouteConfig

  @RouteConfig snippets including one empty and a basic sample with one default route.

• Route

  Route snippets. Route will contain many variations such as aux route, route /w params, default route, parent route, etc.

• Test

  I don't really have much experience with creating tests. Input would be appreciated.

---

Completion Categories:

• Annotations

  Class decorator properties such as selector, inputs, providers, etc.

• Decorators

  Property decorators such as @Input, @Inject, @ViewChildren. Maybe these should be renamed to 'variables' to match the API docs. There are a lot of variables to cover.

• Lifecycle

  Lifecycle hooks such as constructor(), OnInit(), AfterContentChecked().

• Routing

  Router hooks such as routerOnActivate(), and routerOnDeactivate(),

• Directives

  Template directives such as <router-outlet>, and <template>.

• Attributes

  Template attributes such as routerLink, *ngIf.

• Pipes

  Template pipes such as async and currency

---

There may be additional categories that I haven't covered yet. Feedback is welcome.

[deeleman]

Lifecycle and routing hooks are coupled with interface implementations. Let's bear that in mind when creating snippet variations for components, so one can rapidly create a component already implementing the most common interfaces (being probably OnInit the most usual) with a single snippet shortcut.

Pipe snippet w/ @pipe and transform() function. Are there other variations?

Nope, to my knowledge, but Pipes should implement the PipeTransform interface in the resulting snippet.

[joshwiens]

@evanplaice - List up top has been updated with the list of snippets & completion categories in your repo.

[evanplaice]

@deeleman Interfaces are only supported in Typescript. Either way, it's not feasible to add a completions that cover both the interface and the lifecycle hook. Instead, I think it would be best to add an interfaces category to completions.

[deeleman]

it's not feasible to add a completions that cover both the interface and the lifecycle hook

@evanplaice I'm afraid I'm not following. What's wrong with creating snippets like this (Atom, I chose coi as a shortener for component on init vs co for a simpler component for argument's sake):

'.source.ts':
  'Component implementing OnInit hook':
    'prefix': 'coi'
    'body': """
    @Component({
        selector: '${1:selector-name}',
        template: '${2:template}'
    })
    class ${2:Name}Component implements OnInit {
        constructor() {}

        ngOnInit() {

        }
    }
    """

[joshwiens]

@evanplaice - Does it makes sense to maintain snippets for typescript & es6 separately or are we going to try and wedge everything into a single repo?

I can see the merits of both approaches, separate repos may be the simpler approach & people are either going to go one way or the other. Usability may suffer if we try to cover both use cases in a single set up snippets.

[joshwiens]

@deeleman - Not everyone is going to be writing Angular2 using Typescript which is @evanplaice 's point ( i think )

[evanplaice]

@deeleman

Two issues:

• implements will throw an error for users that are developing NG2 apps in ES6
• that sample is too specific, if you create snippets for every variation of interface/hook + metadata properties the snippet collection becomes too complex to be useful.

@d3viant0ne It's not difficult to cover both. Ideally, the ES6 transpiler should be configured to support class and property decorators (which are already covered in the comment above). Otherwise, code like @Inject has to fall back to using weird workarounds.

Aside from implements, ES6 code is nearly identical to TS code. The difference being the presence of types in variable definitions and function parameters. Types can't really be inferred beforehand so there isn't much utility in adding placeholders in the snippets.

[deeleman]

implements will throw an error for users that are developing NG2 apps in ES6

Evan, we all know ES6 and TS here, thanks ;)

And this brings us back to the question raised by @d3viant0ne. Do we aim to create ES6-only snippets? If so I see your point, but IMO that might lead to a more cumbersome coding when in TypeScript: First, creating the snippet, then editing it.

I see the value of the two repos approach, specially when it comes to TS-specific stuff (which is likely to become the most widespread syntax in use for NG2 BTW). That way the ES6 snippets repo does not get polluted with useless snippets. :)

that sample is too specific, if you create snippets for every variation of interface/hook + metadata properties the snippet collection becomes too complex to be useful

While we do not need to cover all the use cases, the one pointed out is precisely pretty common. A good snippet repository has to go beyond the pure basics to be useful IMO.

[joshwiens]

which is likely to become the most widespread syntax in use for NG2 BTW

That's an assumption. Until the data supports which way people are leaning, TS & ES6 JavaScript need to be supported equally.

Given the deference between TS & JS, it probably makes sense to separate them. It would also give us a way to gauge the usage of them over time. If the ES6 snippets aren't downloaded, we know we can stop supporting them in time.

[evanplaice]

@deeleman Take a minute to consider where Typescript-specific features are used. I can only think of 3 cases.

For Interfaces

class SampleComponent implements OnInit {
  ngOnInit();
}

For variable definitions

export interface Hero {
  id: number;
  name: string;
}

For method parameters

constructor(private _heroService: HeroService, private _router: Router) { }

Interfaces will require separate code completion definitions anyway. Variable definitions and method params aren't really good candidates for code completion.

The point being, there is no difference between TS and ES6 snippets.

[joshwiens]

@evanplaice - So we are going with single set of snippets then? Really makes no difference to me either way.

[deeleman]

Until the data supports which way people are leaning, TS & ES6 JavaScript need to be supported equally.

Agreed @d3viant0ne. Assumptions aside, nobody here is stating the contrary.

Take a minute to consider where Typescript-specific features are used.

Minute taken and point given, @evanplaice. ;)

Still, even with a single set of snippets we can take advantage of the source differentiation provided by Atom (and ST I guess) when creating snippets in very specific use cases, creating enhanced syntax-specific versions wherever makes sense, as long as it doesn't hinder the overall maintainability. TS-specific snippets for Pipes implementing the PipeTransform interface or Components implementing OnInit might be good examples and will not burden the snippets set by the end of the day. However I have to recognize it is more of a matter of personal preference, though.

[evanplaice]

@deeleman Pipe is a rare exception. It's the only ES6 snippet I've come across so far.

when creating snippets in very specific use cases

This is a straw man. Snippets aren't intended to cover 'very specific use cases'. Too much specificity is bad for composition and inevitably leads to bloat.

@d3viant0ne Yes, unless we reach a point where we're forced to create duplicates of everything to cover edge cases; and, it makes sense to create an ES6-specific forks of the snippet libs.

[deeleman]

This is a straw man.

Dude, calm down, you do not need to overthink everything that is written here. ;D By use cases I meant precisely case-scenarios like pipes and the like, where we can create ES6 along with TS-enhanced snippets with no effort: one regular Pipe snippet for ES6 and its counterpart implementing the PipeTransform interface for TS. And that's it! :)

May be the words specific use cases is unfortunate here but, yay! you get my point I guess. By no means I meant to create uber-specific code snippets for this or that extremely-edgy use case :)

[deeleman]

And now, back to the discussion: I miss in the list HTML-specific snippets for directives and the like, so we can insert code autocompletion for ngIf, ngFor and ngSwitch, and so on so forth.

Shall we include it?

[joshwiens]

@deeleman - Throw out a list of html snippets for discussion. As we agree on stuff, it's going into the spec at the top.

Initially I had planned to do ngFor, ngIf, ngSwitch, ngClass, ngModel

[deeleman]

I had planned to do ngFor, ngIf, ngSwitch, ngClass, ngModel

Same here, I do believe that's pretty much all, unless we want to go crazy with ngModelChanges, ngSubmit and a generic/agnostic NgStyle binding.

[evanplaice]

HTML-specific snippets should be covered already under 'Attributes' or 'Directives' completions. I'm not sure where to draw the distinction between 'Attributes' and 'Directives'. We could probably just remove 'Attributes' from the list altogether.

As for determining which directives should get snippets, I would probably be best to provide completions for all those included in COMMON_DIRECTIVES

So:

• NgClass
• NgIf
• NgFor
• NgSwitch
• NgSwitchWhen
• NgSwitchDefault
• NgModel
• NgForm

[evanplaice]

@RouteConfig should be added to the list before Route

[joshwiens]

Done

[joshwiens]

@mgechev @nareshbhatia - Any thoughts before I lock this down as an initial spec?

[mgechev]

@d3viant0ne looks good to me.

[joshwiens]

@mgechev @evanplaice - I've been working on the seed & work stuff. In your opinion, is the style guide principals in a stable enough state to warrant the development of snippets?

If not, what do we need to flesh out?

[mgechev]

I think it is quite stable now. There are a few more sections to be polished and more practices to be added.

However, until Angular team releases its final RC we can't remove the disclaimer.

[joshwiens]

Cool. I'll work on snippets this weekend then.

[evanplaice]

FYI, I'm almost done with the Sublime Text snippets. I ran into a bug where completions don't work properly in HTML (ie NG2 template) source files but I can implement those as snippets instead.

As soon as those are done I can see about getting the lib submitted to Package Control so others can easily install/use them.

Here's a link to the the Progress Tracker

[joshwiens]

@evanplaice - I'm actually working on them right now as well. Hoping to get WebStorm out of the way this weekend. I ran into the same issue with inline templates in Atom so I went for the low hanging WebStorm fruit :)

[joshwiens]

@evanplaice Also for the sake of a consistent offering across platforms, my intent is to keep the snippets / templates inline as much as is allowed by the platform.

Given you are way out in front here, I will create the templates with the above in mind and we can discuss any possible changes after the fact if needed.

[joshwiens]

Components / Directives / Routing / HTML Built-ins / Pipe all done and documented for Webstorm - https://github.com/d3viant0ne/angular2-webstorm-templates

[joshwiens]

Beginning work on the Atom package.

@mgechev @evanplaice @nareshbhatia @ludohenin - Do we know someone that uses VSCode who may be interested in picking up the snippets project?

I think maintaining two of these is going to be more than enough work and to be completely honest, I have no love for VSCode.

[mgechev]

@d3viant0ne I am trying out VSCode recently but I'm a bit overloaded as well. Here are some snippets by John https://github.com/johnpapa/vscode-angular2-snippets. I see only three of them but I guess he's planning to extend the set.

[joshwiens]

I'll see if I can get to it this coming weekend.

[ludohenin]

@d3viant0ne I'm using VSCode (and I'm in love :p) but not sure to have time for that. Let see

[joshwiens]

@ludohenin - You have colab access to the repo. I'll do the heavy lifting to get it going, once I get an alpha set of snippets your feedback would be invaluable.

[evanplaice]

@d3viant0ne I wonder if I should rename mine to angular2-sublime-snippets. I was going for a simple name on Package Control but I don't think the PC package name has to be the same as the repository name.