From a602d9aa368d9f4803ddca081c2126283b023c5f Mon Sep 17 00:00:00 2001
From: Ilya Kirillov <ilya.kirillov@onlyoffice.com>
Date: Tue, 27 May 2025 18:24:07 +0300
Subject: [PATCH] [forms] Add methods to work with oform roles

---
 apiBuilder.js | 221 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 221 insertions(+)

diff --git a/apiBuilder.js b/apiBuilder.js
index 99074f1..233bef2 100644
--- a/apiBuilder.js
+++ b/apiBuilder.js
@@ -453,6 +453,212 @@
 			return new AscBuilder.ApiTextForm(contentControl);
 		}, this);
 	};
+	
+	/**
+	 * Class representing a collection of form roles.
+	 * @constructor
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 */
+	function ApiFormRoles(oform)
+	{
+		this.oform = oform;
+	}
+	
+	/**
+	 * Role properties.
+	 * @typedef {FormPrBase | DateFormPrBase} DateFormPr
+	 * @see office-js-api/Examples/Enumerations/DateFormPr.js
+	 */
+	
+	/**
+	 * Role properties.
+	 * @typedef {Object} RoleProperties
+	 * @property {string} color
+	 * @see office-js-api/Examples/Enumerations/RolePr.js
+	 */
+	
+	/**
+	 * Get the collection of form roles.
+	 *
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @returns {ApiFormRoles}
+	 * @see office-js-api/Examples/Forms/ApiDocument/Methods/GetFormRoles.js
+	 */
+	ApiDocument.prototype.GetFormRoles = function()
+	{
+		return new ApiFormRoles(this.Document.GetOFormDocument());
+	};
+	
+	/**
+	 * Add new role.
+	 * @memberof ApiFormRoles
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @param {string} name - The name of role being added.
+	 * @param {RoleProperties} props - Properties for the new role.
+	 * @returns {boolean}
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/Add.js
+	 */
+	ApiFormRoles.prototype.Add = function(name, props)
+	{
+		if (!this.oform || !name || this.oform.getRole(name))
+			return false;
+		
+		let rgba = ParseRoleColor(props && props["color"] ? props["color"] : null);
+		
+		let rolePr = new AscOForm.CRoleSettings();
+		rolePr.Name  = name;
+		rolePr.Color = AscCommon.CreateAscColorCustom(rgba.R, rgba.G, rgba.B);
+		this.oform.addRole(rolePr);
+		return true;
+	};
+	/**
+	 * Remove role.
+	 * @memberof ApiFormRoles
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @param {string} name - The name of role to be removed.
+	 * @param {string} [delegateRole] - The name of the role to which all forms binded to this role will be delegated.
+	 * @returns {boolean}
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/Remove.js
+	 */
+	ApiFormRoles.prototype.Remove = function(name, delegateRole)
+	{
+		if (!this.oform)
+			return false;
+		
+		return this.oform.removeRole(name, delegateRole);
+	};
+	/**
+	 * Get the number of roles.
+	 * @memberof ApiFormRoles
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @returns {number}
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/GetCount.js
+	 */
+	ApiFormRoles.prototype.GetCount = function()
+	{
+		if (!this.oform)
+			return 0;
+		
+		return this.oform.getAllRoles().length;
+	};
+	/**
+	 * List all roles.
+	 * @memberof ApiFormRoles
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @returns {string[]}
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/GetAllRoles.js
+	 */
+	ApiFormRoles.prototype.GetAllRoles = function()
+	{
+		if (!this.oform)
+			return [];
+		
+		let roles = this.oform.getAllRoles();
+		let result = [];
+		for (let i = 0; i < roles.length; ++i)
+		{
+			result.push(roles[i].getRole());
+		}
+		return result;
+	};
+	/**
+	 * Check if a role with the specified name exists.
+	 * @memberof ApiFormRoles
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @param {string} name - The name of role.
+	 * @returns {boolean}
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/HaveRole.js
+	 */
+	ApiFormRoles.prototype.HaveRole = function(name)
+	{
+		return this.oform && this.oform.haveRole(name);
+	};
+	/**
+	 * Get the color of the specified role
+	 * @memberof ApiFormRoles
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @param {string} name - The name of role.
+	 * @returns {null | {r:byte, g:byte, b:byte}}
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/GetRoleColor.js
+	 */
+	ApiFormRoles.prototype.GetRoleColor = function(name)
+	{
+		if (!this.oform || !this.oform.haveRole(name))
+			return null;
+		
+		let color = this.oform.getRoleSettings(name).getColor();
+		if (!color)
+			return null;
+		
+		return {
+			"r" : color.r,
+			"g" : color.g,
+			"b" : color.b
+		};
+	};
+	/**
+	 * Set the color of the specified role
+	 * @memberof ApiFormRoles
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @param {string} name - The name of role.
+	 * @param {string} color - The specified color.
+	 * @returns {boolean}
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/SetRoleColor.js
+	 */
+	ApiFormRoles.prototype.SetRoleColor = function(name, color)
+	{
+		if (!this.oform || !this.oform.haveRole(name))
+			return false;
+		
+		let rgba = ParseRoleColor(color);
+		
+		let rolePr = new AscOForm.CRoleSettings();
+		rolePr.Name  = name;
+		rolePr.Color = AscCommon.CreateAscColorCustom(rgba.R, rgba.G, rgba.B);
+		this.oform.editRole(name, rolePr);
+		return true;
+	};
+	/**
+	 * Move role up in filling order.
+	 * @memberof ApiFormRoles
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @param {string} name - The name of role.
+	 * @returns {boolean}
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/MoveUp.js
+	 */
+	ApiFormRoles.prototype.MoveUp = function(name)
+	{
+		if (!this.oform)
+			return false;
+		
+		return this.oform.moveUpRole(name);
+	};
+	/**
+	 * Move role down in filling order.
+	 * @memberof ApiFormRoles
+	 * @since 9.0.0
+	 * @typeofeditors ["CFE"]
+	 * @param {string} name - The name of role.
+	 * @returns {boolean}
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/MoveUp.js
+	 */
+	ApiFormRoles.prototype.MoveDown = function(name)
+	{
+		if (!this.oform)
+			return false;
+		
+		return this.oform.moveDownRole(name);
+	};
 	////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 	// Private area
 	////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -535,6 +741,10 @@
 		formPr.SetKey(key);
 		form.SetFormPr(formPr);
 	}
+	function ParseRoleColor(color)
+	{
+		return color ? AscCommon.RgbaTextToRGBA(color) : {R : 254, G : 248, B : 229, A : 255};
+	}
 	////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 	// Export
 	////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -545,6 +755,17 @@
 	Api.prototype["CreateComboBoxForm"] = Api.prototype.CreateComboBoxForm;
 	
 	ApiDocument.prototype["InsertTextForm"] = ApiDocument.prototype.InsertTextForm;
+	ApiDocument.prototype["GetFormRoles"]   = ApiDocument.prototype.GetFormRoles;
+	
+	ApiFormRoles.prototype["Add"]          = ApiFormRoles.prototype.Add;
+	ApiFormRoles.prototype["Remove"]       = ApiFormRoles.prototype.Remove;
+	ApiFormRoles.prototype["GetCount"]     = ApiFormRoles.prototype.GetCount;
+	ApiFormRoles.prototype["GetAllRoles"]  = ApiFormRoles.prototype.GetAllRoles;
+	ApiFormRoles.prototype["HaveRole"]     = ApiFormRoles.prototype.HaveRole;
+	ApiFormRoles.prototype["GetRoleColor"] = ApiFormRoles.prototype.GetRoleColor;
+	ApiFormRoles.prototype["SetRoleColor"] = ApiFormRoles.prototype.SetRoleColor;
+	ApiFormRoles.prototype["MoveUp"]       = ApiFormRoles.prototype.MoveUp;
+	ApiFormRoles.prototype["MoveDown"]     = ApiFormRoles.prototype.MoveDown;
 
 }(window, null));