La direttiva ng-include in AngularJS consente di includere, nella vista corrente, del codice HTML esterno cioè codice che si trova in un altro file, come nel seguente esempio:
<div ng-include="'dati/documento.html'"></div>Il contenuto del file documento.html sarà caricato, interpretato da Angular e iniettato nel <div>.
Nota: È importante sottolineare che il codice contenuto nel file esterno viene interpretato da Angular prima di effettuare il rendering sulla pagina. Questo vuol dire che il file esterno può a sua volta contenere direttive Angular.
Un'altro aspetto a cui prestare attenzione è la modalità con cui viene indicato l'URL del file da caricare: il valore associato alla direttiva è una stringa e deve essere racchiusa tra virgolette e tra apici. Cioè, oltre alle virgolette che delimitano il valore dell'attributo ("...") vanno specificati gli apici che indicano che si tratta di una stringa JavaScript ('...').
Come per qualsiasi direttiva, il valore associato può essere una qualsiasi espressione. Possiamo ad esempio specificare il caricamento condizionale di contenuti esterni tramite un'espressione come la seguente:
<p>Età: <input type="text" ng-model="utente.eta"></p>
<div ng-include="utente.eta >= 18? 'dati/docMaggiorenni.html' : 'dati/docMinorenni.html'"></div>Usando l'operatore ternario (?:) di JavaScript carichiamo dinamicamente il documento opportuno in base all'età specificata dall'utente. Possiamo anche indicare una funzione che restituisce la stringa che rappresenta il documento da caricare:
<p>Età: <input type="text" ng-model="utente.eta"></p>
<div ng-include="caricaDocumento(utente.eta)"> </div>Naturalmente alla direttiva si applica la same origin policy, cioè la restrizione per cui è possibile caricare soltanto documenti esterni provenienti dallo stesso dominio dell'applicazione corrente.
È inoltre possibile specificare un inline template come codice da caricare, cioè una porzione di codice già contenuta nella pagina corrente ed identificata come blocco <script>, come nel seguente esempio:
<div ng-include="'/doc.html'"></div>
<script type="text/ng-template" id="/doc.html">
Corpo del documento
</script>come possiamo vedere dal codice, il tipo di script deve essere text/ng-template e l'identificatore rappresenta all'URL del documento. Dal punto di vista della direttiva ng-include non c'è differenza se l'URL indicato fa riferimento ad un documento esterno o ad un inline template.
Segnaliamo infine che ng-include è una di quelle direttive che prevedono la possibilità di essere utilizzate come elemento, come attributo o come classe, come possiamo vedere dai seguenti esempio del tutto equivalenti:
<ng-include src="'documento.html'"></ng-include>
<div ng-include="'documento.html'"></div>
<div class="ng-include:'documento.html'"></div>