Manifesto del componente
La configurazione del manifesto di un componente è un passaggio essenziale nella creazione di un componente di codice. Il file ControlManifest.Input.xml viene inizializzato con alcune scelte dell'utente, quali il nome e il tipo di componente, quando si usa il comando pac pcf init. È tuttavia necessario personalizzare il file per specificare le proprietà e le risorse che si usano e per abilitare le funzionalità del framework usate nel componente.
Proprietà del componente
Le proprietà definiscono un contratto tra il componente di codice e l'applicazione di hosting. Dovrebbero astrarre l'autore dal modo in cui si implementa il componente, ma fornire comunque funzionalità configurabili per l'autore che usa il componente. Di seguito sono riportati alcuni tipi comuni di proprietà che potrebbe essere necessario aggiungere a un componente:
- Permettere il passaggio dei dati aziendali nel e dal componente di codice. Ad esempio, passando una georilevazione nel componente, quest'ultimo potrebbe mostrare una mappa che evidenzia una posizione specifica.
- Consentire il controllo delle funzionalità e dei comportamenti del componente. Proviamo con una mappa di esempio: è possibile aggiungere una proprietà che indica se l'utente può fare zoom avanti o indietro della mappa.
- Consentire la personalizzazione di alcuni aspetti dello stile del componente. Ad esempio, sulla mappa, il componente potrebbe consentire di personalizzare il colore del segnaposto fornendo una proprietà che l'autore può configurare.
Lo screenshot seguente è un manifesto di esempio che mostra le proprietà definite per un componente indicatore di avanzamento.
Quando un autore configura un componente di codice, le proprietà definite nel manifesto sono disponibili per la configurazione. Questa immagine mostra come si presenta a un autore il manifesto precedente per un componente indicatore di avanzamento nella finestra di progettazione dell'applicazione. Gli consente di vedere e personalizzare le proprietà disponibili.
Attributi delle proprietà
Vi sono vari attributi in una proprietà che è possibile configurare in base alle esigenze. Di seguito sono riportati i più comuni da considerare:
of-type: questo attributo definisce il tipo di dati della proprietà. Esistono molti tipi tra cui scegliere, da SingleLine.Text a Enum. Alcuni tipi, come Enum, offrono all'autore un'esperienza di configurazione più ricca e forniscono un elenco fisso da cui scegliere. Altri limitano il contenuto dei dati in base al tipo che può passare dall'app di hosting. Alcuni sono più appropriati per l'associazione dei dati, come Lookup.Simple. Evitare sempre di modificare i tipi di dati dopo aver pubblicato il componente.
usage: questo attributo identifica se la proprietà è di input, output o bound. È destinato alle app basate su modello. L'opzione bound prevede la presenza di una colonna dati della tabella associata per fornire il valore dei dati.
required: indica se un valore per la proprietà è richiesto. Quando si aggiungono nuove proprietà dopo la pubblicazione di un componente, considerare l'impatto di rendere la proprietà obbligatoria per le app esistenti che usano il componente.
default-value: questo attributo contiene il valore predefinito fornito al componente. Nelle app basate su modello questa proprietà è consentita solo sulle proprietà con tipo di utilizzo input. Fornire un valore predefinito può essere utile per offrire ai creatori un'idea di come si intende impostare la proprietà. Quando si aggiunge una nuova proprietà a un componente esistente, il valore predefinito è spesso impostato sul valore che il componente usava prima di diventare configurabile a causa della proprietà.
Ecco alcune cose da considerare quando si valutano le proprietà da aggiungere:
- Evitare che siano presenti troppe proprietà nel componente, affinché l'autore non debba vedere un lungo elenco di opzioni.
- Usare nomi significativi per le proprietà. Laddove possibile, fornire nella descrizione dettagli sufficienti per informare l'autore sullo scopo.
- Valutare se aggiungere alcune proprietà per dare modo ai creatori di modellare il componente. Queste proprietà possono essere importanti quando è possibile usare il componente in un'ampia gamma di applicazioni.
- Evitare di rinominare o rimuovere le proprietà dopo aver pubblicato il componente, poiché queste modifiche potrebbero causare interruzioni nelle app esistenti che lo usano.
Risorse dei componenti
Il nodo della risorsa nel manifesto identifica i file di risorse richiesti dal componente. In un nuovo componente, inizialmente contiene solo l'elemento code. È possibile aggiungere altre risorse richieste dal componente. Le più comuni sono css e resx.
L'elemento css permette di identificare un file CSS (Cascading Style Sheets) da caricare. In caso ve ne sia più di uno, è possibile specificare l'ordine in cui caricarli. Il codice seguente è un esempio di caricamento di due file CSS.
<css path="css/ComponentCommon.css" order="1" />
<css path="css/ProgressIndicator.css" order="2" />
Il nodo resx nel manifesto identifica il file usato per gestire le stringhe localizzate che si definiscono. Se si prevede la localizzazione, è più semplice aggiungerlo in un nuovo componente e aggiornarlo quando si aggiungono proprietà. Le proprietà nel valore del manifesto degli attributi display-name-key e description-key sono usate per cercare il valore localizzato se non si trova in un file di risorse resx caricato.
Ad esempio, rivedere la definizione della proprietà seguente e come sono definiti gli attributi.
<property name="PercentComplete" description-key="PercentComplete_Desc" display-name-key="PercentComplete" required="true" usage="input" of-type="Whole.None" default-value="40" />
In un file resx (file XML che usa Microsoft ResX Schema) si definiscono i seguenti elementi di dati per le chiavi proprietà.
<data name="PercentComplete" xml:space="preserve">
<value>Percent Complete</value>
</data>
<data name="PercentComplete_Desc" xml:space="preserve">
<value>Percent Complete is the current value for how much has been completed.</value>
</data>
Quindi si crea un file resx separato per ogni lingua supportata.
Successivamente, nel nodo della risorsa del manifesto si aggiungono i seguenti nodi resx per caricare i file quando il componente viene usato.
<resx path="strings/ProgressIndicator.1033.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.1035.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.3082.resx" version="1.0.0" />
Utilizzo delle funzionalità del componente
Le funzionalità di dispositivo, utilità e WebAPI del framework sono disponibili per l'uso da parte dei componenti usati in un'app basata su modello. Per usare una di queste funzionalità, è necessario dichiararla nel manifesto nel nodo feature-usage aggiungendo un nodo uses-feature. Il codice seguente è un esempio di abilitazione dell'uso della funzionalità WebAPI.
<feature-usage>
<uses-feature name="WebAPI" required="true" />
</feature-usage>