Power Query: Personaliza tus funciones con Metadatos

La semana pasada publiqué un artículo donde explicaba que eran los Metadatos (ver aquí) y para qué servían...
Hoy le daremos un uso peculiar. Un uso que nos permitirá personalizar los textos de ayuda de una función creada por nosotros en nuestro editor de Power Query.

En primer lugar accederemos al editor de Power Query y crearemos una Consulta en blanco, donde insertaremos el siguiente código de una sencilla función (esto no es lo que nos importa):

(texto1 as text, texto2 as text) as text => 
let 
    txtCompleto=Text.Combine({texto1, texto2}, " ")
in 
    txtCompleto

Una vez finalizada la función llamada 'fxFuncionConMetadatos' si la seleccionamos veremos que solo nos despliega los parámetros definidos... ninguna información adicional. Muy simple :'(

Puedes entrar en cualquier otra función estándar de Power Query para comprobar la diferencia... por ejemplo, si accedes a la función Table.ColumnCount veríamos:

Incorporar toda esa información complementaria a nuestra función será el ejercicio de hoy.

Para ello disponemos de ciertos campos tipo Documentation:
- Documentation.Examples: de tipo list. Corresponde a un lista de objetos de registro con el uso de ejemplo de la función.
Solo se muestra como parte de la información de la función.
Cada registro debe contener los siguientes campos de texto opcionales: Description , Code y Result

- Documentation.LongDescription: de tipo text. Descripción completa de lo que hace la función, que se muestra en la información de la función.
Existe también Documentation.Description para descripciones más breves... LongDescription prioriza sobre .Description, es decir, si definimos la primera, NO aparecerá la sencilla y corta.

- Documentation.Name: de tipo text. Texto que se va a mostrar en la parte superior del cuadro de diálogo de invocación de función.


Otros campos asociados a la documentación de nuestras funciones, en concreto a los parámetros de nuestra función, opcionales, serían:
- Documentation.AllowedValues: de tipo list. Lista de valores válidos para este parámetro. Al proporcionar este campo, se cambiará la entrada de un cuadro de texto a una lista desplegable. Ten en cuenta que esto no impide que un usuario edite manualmente la consulta para proporcionar valores alternativos.

- Documentation.FieldCaption: de tipo text. Nombre descriptivo para mostrar que se va a usar para el parámetro.

- Documentation.FieldDescription: de tipo text. Descripción que se va a mostrar junto al nombre para mostrar.

- Documentation.SampleValues: de tipo list. Lista de valores de ejemplo que se van a mostrar (como texto atenuado) dentro del cuadro de texto.

- Formatting.IsMultiLine: de tipo boolean. Permite crear una entrada de varias líneas, por ejemplo, para pegar en consultas nativas.

- Formatting.IsCode: de tipo boolean. Da formato al campo de entrada para el código, normalmente con entradas de varias líneas.


Otras funciones muy importantes que nos permitirán recuperar los anteriores registros comentados (.Name, .LongDescription, .Examples) son:
- Value.Type(value as any) as type: función M que nos devuelve el 'tipo' del valor indicado.

- Value.ReplaceType(value as any, type as type) as any: función M que habilita el cambio de tipo de una dato.

- Value.Metadata(value as any) as any : función M vista en una entrada previa del blog, que nos devuelve un registro que contiene los metadatos del valor dado.

- Value.ReplaceMetadata(value as any, metaValue as any) as any : función M vista en una entrada previa del blog, que nos permite cambiar la información cargada como metadatos.

- Type.FunctionParameters(type as type) as record: interesante función M que retorna un registro con los valores de campo establecidos en el nombre de los parámetros de type y sus valores establecidos en sus tipos correspondientes.

- Type.FunctionRequiredParameters(type as type) as number : Devuelve un número que indica el mínimo de parámetros necesarios para invocar la entrada type definido.

Un poco raras las dos últimas funciones, pero fáciles de comprender cuando las usemos en el contexto adecuado a continuación...

Diría que estamos listos para generar nuestros metadatos e incorporarlos a la documentación de nuestra función.
A partir de nuestra función personalizada tendríamos:

let 
txtCompleto = (texto1 as text, texto2 as text) as text => 

	Text.Combine({texto1, texto2}, " "),

	//asignamos propiedades a visualizar en los parámetros de nuestra función
	ParametrosTexto = type text meta 
		[Documentation.FieldCaption = "Añade solo texto",
		Documentation.FieldDescription = "Texto",
		Documentation.SampleValues = {"Excelforo"}],
	
	//redefinimos los tipos de la función con las características anteriores
	TipoMiFuncion = type function(
					texto1 as ParametrosTexto,
					texto2 as ParametrosTexto) as text,

	//declaramos los metadata asociados a la documentación de nuestra función
	Documentacion_de_Metadatos= [
		Documentation.Name ="fxFuncionConMetadatos",     //debe ser el nombre de la función (para no confundir...)
		Documentation.LongDescription = "Nuestra función concatena cadenas de texto... y bla bla bla",
		Documentation.Examples = { 
				[Description = "La función nos devuelve una cadena de texto a partir de dos elementos.",
				Code = "fxFuncionConMetadatos(Power, Query)",
				Result="Power Query"]
					} ]
in
	Value.ReplaceType(txtCompleto,Value.ReplaceMetadata(TipoMiFuncion, Documentacion_de_Metadatos))

Y veríamos lo siguiente al seleccionar nuestra función:

Con lo que ya dispondremos de una completa ayuda para nuestra función ;-)