Documentation
Documentation
Labels

1Objectif

L’objectif du concept de label est d’étendre dynamiquement certains modèles de données. Les propriétés de ces modèles diffèrent selon le contexte dans lequel ils sont créés ou utilisés. L’infrastructure de labels n’est pertinente que lorsque les informations doivent être traitées par une application tierce ou si les informations supplémentaires doivent être affichées sur une interface utilisateur d’une application tierce. Si ce n’est pas le cas, les labels ne sont généralement pas pertinents.

2Descripteurs de label

Étant donné que nous étendons les modèles de données dynamiquement, nous devons décrire les données que nous renvoyons. Pour chaque label, nous renvoyons également le descripteur de label. Le descripteur fournit la sémantique de l’élément de données. Il fournit également une description et un nom qui peuvent être compris par un utilisateur humain.

De plus, le descripteur contient un type. Le type indique de quel type (string, integer, etc.) est la valeur du label.

3Résoudre les descriptions via l’API du service web

Les descripteurs de label peuvent être récupérés via l’API du service web en utilisant le Label Descriptor Service. Un label est composé d’une value, d’un type et d’un descriptor. L’identifiant du descripteur peut être résolu via l’API du service web pour obtenir les informations supplémentaires.

4Exemple de label

Un objet avec des labels peut ressembler au JSON suivant :

{
	"id": 123141,
	"regularProperty": "A regular property which is not dynamically added.",
	"labels": [
		{
			"content": "Sample Label Value",
			"contentAsString": "Sample Label Value",
			"descriptor": 11001231,
			"displayName": "ID: 58",
			"id":58,
			"version":0
		}
	]
}

Dans cet exemple, nous avons un label avec la valeur Sample Label Value. Les détails concernant le label peuvent être trouvés en interrogeant le descripteur de label. Le descripteur fournira les données suivantes :

{
	"id": 11001231,
	"name": "Sample Label",
	"category": "HUMAN",
	"description":{
		"en-US":"This field will contain a human understandable description of the label in English."
	},
	"type": {
		"description":{
			"en-US":"The string label type indicates that the label value is of the type string."
		},
		"id":1455545848917,
		"name":{
			"en-US":"String"
		}
	},
	...
}

Comme le montre l’exemple, le descripteur fournit une description, un nom, un type et d’autres propriétés. Le type sera également utilisé pour d’autres descripteurs. Pour utiliser correctement cette infrastructure, un handler devrait être implémenté pour chaque type de label. De cette manière, une implémentation générique pour traiter les labels peut être réalisée. Si seuls certains descripteurs de label particuliers sont intéressants, il peut également être judicieux de ne traiter que ces labels.

5Type de label : valeur statique

Le type de label à valeur statique est particulier car le label contient en réalité un identifiant d’un autre objet. L’objet peut être résolu via l’API REST pour les valeurs statiques. Généralement, de telles valeurs représentent des objets qui ne changent pas. Elles sont comparables aux Enums connus dans certains langages de programmation.