anchor.diff:  :marked
     An **Attribute** directive changes the appearance or behavior of a DOM element.
   
  +  Une directive d'**Attribut** modifie l'apparence ou le comportement d'un élément DOM.
  +
   :marked
     In this chapter we will
  +
  +  Dans ce chapitre nous allons
     * [write an attribute directive to change the background color](#write-directive)
  +  * [Écrire une directive d'attribut qui change la couleur de l'arrière-plan](#write-directive)
     * [apply the attribute directive to an element in a template](#apply-directive)
  +  * [Appliquer la directive d'attribut sur un élément d'un template](#apply-directive)
     * [respond to user-initiated events](#respond-to-user)
  +  * [Réagir à un événement de l'utilisateur](#respond-to-user)
     * [pass values into the directive using data binding](#bindings)
  +  * [Transmettre des valeurs à notre directive grâce à la liaison de données](#bindings)
   
     Try the <live-example></live-example>.
   
  +  Essayez la <live-example>démo</live-example>.
  +
     ## Directives overview
  +  ## Aperçu des Directives
     
     There are three kinds of directives in Angular:
  +  
  +  Il y a 3 sortes de directives en Angular :
     1. Components
  +  1. Les composants (_Components_)
     1. Structural directives  
  +  1. Les directives structurelles  
     1. Attribute directives
  +  1. Les directives d'attributs
   
     A *Component* is really a directive with a template. 
     It's the most common of the three directives and we tend to write lots of them as we build applications.
   
  +  Un *Composant* n'est qu'une directive avec un template.
  +  C'est la directive la plus utilisée et nous avons tendance à en écrire beaucoup dans nos applications.
  +
     [*Structural* directives](structural-directives.html) can change the DOM layout by adding and removing DOM elements. 
     [NgFor](template-syntax.html#ngFor) and [NgIf](template-syntax.html#ngIf) are two familiar examples.
  +
  +  [Les directives *Structurelles*](structural-directives.html) peuvent modifier le DOM en ajoutant ou supprimant des éléments DOM.
  +  [NgFor](template-syntax.html#ngFor) et [NgIf](template-syntax.html#ngIf) sont les exemples les plus connus.
     
     An *Attribute* directive can change the appearance or behavior of an element.
     The built-in [NgStyle](template-syntax.html#ngStyle) directive, for example,
     can change several element styles at the same time.
  +
  +  Une directive *d'Attribut* peut changer l'apparence ou le comportement d'un élément.
  +  Par exemple, la directive intégrée (dans le framework) [NgStyle](template-syntax.html#ngStyle)
  +  peut modifier plusieurs styles en même temps.
     
     We are going to write our own attribute directive to set an element's background color
     when the user hovers over that element.
  +
  +  Nous allons écrire notre propre directive d'attribut, qui modifie la couleur de l'arrière-plan,
  +  quand l'utilisateur survolera cet élément.
  +
   .l-sub-section
     :marked
       We don't need *any* directive to simply set the background color.
       We can set it with the special [Style Binding](template-syntax.html#style-binding) like this:
   
  +    Nous n'avons besoin d'*aucune* directive pour modifier la couleur d'arrière-plan.
  +    Nous pouvons la modifier avec [une liaison spéciale de style (Style Binding)](template-syntax.html#style-binding) comme ceci :
     +makeExample('attribute-directives/ts/app/app.component.1.html','p-style-background')
   
     :marked
       That wouldn't be nearly as much fun as creating our own directive.
  +
  +    Ça ne serait pas aussi marrant que de créer notre propre directive.
       
       Besides, we're not just *setting* the color; we'll be *changing* the color
       in response to a user action, a mouse hover.
   
  +    Mais au final, nous ne faisons que *paramétrer* une couleur; nous voulons *changer* la couleur
  +    au travers d'une action de l'utilisateur, par un survol de la souris. 
  +
   .l-main-section
   a#write-directive
   :marked
     ## Build a simple attribute directive
  +  ## Écrire une simple directive d'attribut
  +
     An attribute directive minimally requires building a controller class annotated with 
     `@Directive`, which specifies the selector identifying
     the attribute associated with the directive. 
     The controller class implements the desired directive behavior.
  +  
  +  Une directive d'attribut requiert au minimum de construire un contrôleur annotée avec 
  +  `@Directive`, spécifiant le sélecteur (selector) qui identifie l'attribut associé à notre directive. 
  +  Un contrôleur implémente le comportement de la directive souhaitée.
   
     Let's build a small illustrative example together.
   
  +  Écrivons un petit exemple ensemble.
  +
   :marked
     ### Our first draft
  +  ### Notre premier essai
  +
     Create a new project folder (`attribute-directives`) and follow the steps in the [QuickStart](../quickstart.html).
   
  +  Créez un nouveau dossier (`attribute-directives`) et suivez les étapes du [QuickStart](../quickstart.html).
  +
   include ../_quickstart_repo
   :marked
     Create the following source file in the indicated folder with the given code:
  +
  +  Créez les fichiers suivants dans les dossiers indiqués avec ce code :
  +
   +makeExample('app/highlight.directive.1.ts')
   
   block highlight-directive-1
  
positive.code: .l-main-section
  :marked
    ### Appendix: Input properties
    
    Earlier we declared the `highlightColor` property to be an ***input*** property of our
    `HighlightDirective`
   
    We've seen properties in bindings before. 
    We never had to declare them as anything. Why now?
    
    Angular makes a subtle but important distinction between binding **sources** and **targets**.
    
    In all previous bindings, the directive or component property was a binding ***source***.
    A property is a *source* if it appears in the template expression to the ***right*** of the equals (=).
    
    A property is a *target* when it appears in **square brackets** ([ ]) to the **left** of the equals (=) ...
    as it is does when we bind to the `myHighlight` property of the `HighlightDirective`, 
  +makeExample('attribute-directives/ts/app/app.component.html','pHost')(format=".")
  :marked
    The 'color' in `[myHighlight]="color"` is a binding ***source***.
    A source property doesn't require a declaration.
    
    The 'myHighlight' in `[myHighlight]="color"` *is* a binding ***target***.
    We must declare it as an *input* property.
    Angular rejects the binding with a clear error if we don't.
    
    Angular treats a *target* property differently for a good reason.
    A component or directive in target position needs protection.
    
    Imagine that our `HighlightDirective` did truly wonderous things.
    We graciously made a gift of it to the world. 
    
    To our surprise, some people &mdash; perhaps naively &mdash;
    started binding to *every* property of our directive. 
    Not just the one or two properties we expected them to target. *Every* property.
    That could really mess up our directive in ways we didn't anticipate and have no desire to support.
    
    The *input* declaration ensures that consumers of our directive can only bind to
    the properties of our public API ... nothing else.
  
negative.code:   through its `nativeElement` property.
    That's all we need to set the element's background color using the browser DOM API.
  
    Angular créé une nouvelle instance du contrôleur de la directive pour chaque élement trouvé et injecte un `ElementRef`
    d'Angular.
    `ElementRef` est un service qui nous garantit un accès aux éléments du DOM
    au travers de sa propriété `nativeElement`.
    C'est tout ce dont on a besoin pour modifier l'élément de la couleur de l'arrière-plan avec l'API DOM du navigateur.
  
  .l-main-section
  a#apply-directive
  :marked
    ## Apply the attribute directive
    ## Appliquer la directive d'attribut
    The `AppComponent` in this sample is a test harness for our `HighlightDirective`.
    Let's give it a new template that 
    applies the directive as an attribute to a paragraph (`p`) element.
    In Angular terms, the `<p>` element will be the attribute **host**.
  
    Dans notre exemple, le `AppComponent` a été simplifié pour notre `HighlightDirective`.
    Donnons lui un nouveau template qui appliquera la directive en tant qu'attribut d'un élément de paragraphe (`p`).
    Selon les termes Angular, l'élement `<p>` sera l'attribut **host**.
  p
    | We'll put the template in its own 
    code #[+adjExPath('app.component.html')]
    | file that looks like this:
  p
    | Nous allons ajouter le template dans son propre fichier 
    code #[+adjExPath('app.component.html')]
    | qui ressemble à ceci :
  +makeExample('attribute-directives/ts/app/app.component.1.html',null,'app/app.component.html')(format=".")
  :marked
    A separate template file is clearly overkill for a 2-line template. 
    Hang in there; we're going to expand it later.
    Meanwhile, we'll revise the `AppComponent` to reference this template.
  
    Évidemment, 2 lignes pour un fichier template est exagéré.
    Patience; nous allons le développer plus tard.
    En attendant, nous allons remanier `AppComponent` pour qu'il référence ce template.
  
  +makeExample('attribute-directives/ts/app/app.component.ts',null,'app/app.component.ts')
  :marked
    We've added an `import` statement to fetch the 'Highlight' directive and, 
    added that class to a `directives` component metadata so that Angular 
    will recognize our directive when it encounters `myHighlight` in the template. 
  
    Nous avons ajouté une déclaration `import` pour récupérer la directive 'Highlight' et
    ajouté dans une metadata `directives` du composant pour que Angular
    puisse reconnaître notre directive quand il rencontrera `myHighlight` dans le template.
  
    We run the app and see that our directive highlights the paragraph text.
  
    Nous lançons l'application et constatons que notre directive surbrille le paragraphe.
    
  figure.image-display
    img(src="/resources/images/devguide/attribute-directives/first-highlight.png" alt="First Highlight")
  .l-sub-section
    :marked
      ### Your directive isn't working? 
      ### Votre directive ne fonctionne pas&nbsp;? 
  
      Did you remember to set the `directives` attribute of `@Component`? It is easy to forget!
  
      Avez-vous pensé à définir l'attribut `directives` du `@Component`&nbsp;? C'est facile de l'oublier&nbsp;!
      
      Open the console in the browser tools and look for an error like this:
      
      Ouvrez la console du navigateur et cherchez si vous avez une erreur telle que : 
    code-example(format="nocode").
      EXCEPTION: Template parse errors:
        Can't bind to 'myHighlight' since it isn't a known native property
    :marked
      Angular detects that we're trying to bind to *something* but it doesn't know what.
      We have to tell it by listing `HighlightDirective` in the `directives` metadata array.
  
      Angular détecte que nous essayons de lier *quelque chose* mais il ne sait pas quoi.
      Nous devons le lui préciser en listant `HighlightDirective` dans le tableau de la metadata `directives`.
  :marked
    Let's recap what happened.
  
    Récapitulons ce qu'il se passe.
    
    Angular found the `myHighlight` attribute on the `<p>` element. It created
    an instance of the `HighlightDirective` class, 
    injecting a reference to the element into the constructor 
    where we set the `<p>` element's background style to yellow.
  
    Angular détecte l'attribut `myHighlight` sur l'élément `<p>`. Il créé 
    une instance de la classe `HighlightDirective`, 
    injecte une référence de l'élement dans le constructeur
    où nous appliquons le style d'arrière-plan de l'élement `<p>` à jaune.
  
  .l-main-section
  a#respond-to-user
  :marked
    ## Respond to user action
  
    ## Réagir à un événement de l'utilisateur
  
    We are not satisfied to simply set an element color.
    Our directive should set the color in response to a user action.
    Specifically, we want to set the color when the user hovers over an element.
  
    Nous ne sommes pas satisfait de simplement modifier la couleur de l'élément.
    Notre directive devrait modifier la couleur en réponse à une action de l'utilisateur.
    Plus précisément, nous voulons modifier la couleur quand l'utilisateur survole un élément.
    
    We'll need to
    
    Nous devrons
  
    1. detect when the user hovers into and out of the element,
    1. détecter quand l'utilisateur survole et ne survole plus l'élément,
    2. respond to those actions by setting and clearing the highlight color, respectively.
    2. réagir à ces actions en appliquant/supprimant respectivement la surbrillance.
    
    We apply the `@HostListener` !{_decorator} to methods which are called when an event is raised.
  
    Nous appliquons le !{_décorateur} `@HostListener` aux méthodes lancées quand un événement est levé.
  
  +makeExample('attribute-directives/ts/app/highlight.directive.2.ts','host')(format=".")
  
  .l-sub-section
    :marked
      The `@HostListener` !{_decorator} refers to the DOM element that hosts our attribute directive, the `<p>` in our case.
  
      Le !{_décorateur} `@HostListener` se réfère à l'élément du DOM qui contient (_host_) notre attribut de directive, le `<p>` dans notre cas.
       
      We could have attached event listeners by manipulating the host DOM element directly, but
      there are at least three problems with such an approach:
  
      Nous aurions pu attacher les écoutes d'événements (_event listeners_) en manipulant le DOM du contenant (host) directement, 
      mais il y a au moins trois problèmes avec une telle approche :
      
      1. We have to write the listeners correctly.
      1. Nous devons écrire les écouteurs (_listeners_) correctement.
      1. We must *detach* our listener when the directive is destroyed to avoid memory leaks.
      1. Nous devons *détacher* nos écouteurs quand la directive est détruire afin d'éviter les fuites de mémoire.
      1. We'd be talking to DOM API directly which, we learned, is something to avoid.
      1. Nous communiquerions directement avec l'API du DOM ce qui, nous l'avons appris, est quelque chose à éviter.
  
      Let's roll with the `@HostListener` !{_decorator}. 
  
      Faisons tourner le !{_décorateur} `@HostListener`. 
  :marked
    Now we implement the two mouse event handlers:
  
    À présent nous implémentons les deux fonctions de gestion d'événement (_event handlers_) de la souris :
  +makeExample('attribute-directives/ts/app/highlight.directive.2.ts','mouse-methods')(format=".")
  :marked
    Notice that they delegate to a helper method that sets the color via a private local variable, `#{_priv}el`.
    We revise the constructor to capture the `ElementRef.nativeElement` in this variable.
  
    Remarquez qu'ils délèguent à une méthode d'assistance (helper method) qui définit la couleur au travers de 
    la variable locale privée `#{_priv}el`
    Nous modifions le constructor afin de récupérer `ElementRef.nativeElement` dans cette variable.
  
  +makeExample('attribute-directives/ts/app/highlight.directive.2.ts','ctor')(format=".")
  :marked
    Here's the updated directive:
  
    Voici la directive mise à jour :
  +makeExample('app/highlight.directive.2.ts')
  :marked
    We run the app and confirm that the background color appears as we move the mouse over the `p` and
    disappears as we move out.
  
    Nous lançons l'application et confirmons que la couleur de l'arrière-plan apparaît quand on survole le `p` et 
    disparaît quand on en sort.
  figure.image-display
    img(src="/resources/images/devguide/attribute-directives/highlight-directive-anim.gif" alt="Second Highlight")
  .l-main-section
  a#bindings
  :marked
    ## Configure the directive with binding
    ## Configurer la directive avec des liaisons de données
    
    Currently the highlight color is hard-coded within the directive. That's inflexible.
    We should set the color externally with a binding like this:
  
    Jusqu'à présent, la surbrillance est codée en dur dans la directive. Cette manière de faire est rigide.
    Nous devons définir la couleur de l'extérieur avec une liaison de données comme ceci : 
  +makeExample('attribute-directives/ts/app/app.component.html','pHost')
  :marked
    We'll extend our directive class with a bindable **input** `highlightColor` property and use it when we highlight text.
  
    Nous allons étendre notre classe de directive avec une propriété "liante" **input** `highlightColor` et l'utiliser 
    quand on surbrille le texte.
  
    Here is the final version of the class:
  
    Voici la version finale de la classe :
  +makeExcerpt('app/highlight.directive.ts', 'class')
  a#input
  :marked
    The new `highlightColor` property is called an *input* property because data flows from the binding expression into our directive.
    Notice the `@Input()` #{_decorator} applied to the property.
  
    La nouvelle propriété `highlightColor` est appelée *input* parce que les données sont transmises à notre directive grâce à l'expression de la liaison de données.
    Remarquez que le #{_décorateur} `@Input()` s'applique sur la propriété.
  +makeExcerpt('app/highlight.directive.ts', 'color')
  :marked
    `@Input` adds metadata to the class that makes the `highlightColor` property available for 
    property binding under the `myHighlight` alias. 
    We must add this input metadata or Angular will reject the binding.
    See the [appendix](#why-input) below to learn why.
  
    `@Input` ajoute des metadata à la classe rendant accessible par liaison de données la propriété `highlightColor`
    en dessous de l'alias `myHighlight`.
    Nous devons ajouter cette entrée de metadata ou sinon Angular rejettera la liaison de données.
    Voir l'[annexe](#why-input) ci-dessous pour savoir pourquoi.
  .l-sub-section
    :marked
      ### @Input(_alias_) 
      The developer who uses this directive expects to bind to the attribute name, `myHighlight`.
      The directive property name is `highlightColor`. That's a disconnect.
  
      Le développeur qui utilise cette directive s'attend à lier une valeur avec l'attribut `myHighlight`.
      La nom de propriété de la directive est `highlightColor`. Ce n'est pas très cohérent.
      
      We could resolve the discrepancy by renaming the property to `myHighlight` and define it as follows:
  
      Nous pouvons résoudre cette incohérence en renommant la propriété `myHighlight` ainsi :
  
    +makeExcerpt('app/highlight.directive.ts', 'highlight', '')
    :marked
  