diff options
Diffstat (limited to 'install/ui/src/freeipa/ipa.js')
| -rw-r--r-- | install/ui/src/freeipa/ipa.js | 675 |
1 files changed, 647 insertions, 28 deletions
diff --git a/install/ui/src/freeipa/ipa.js b/install/ui/src/freeipa/ipa.js index 0e9fdefb..b3017650 100644 --- a/install/ui/src/freeipa/ipa.js +++ b/install/ui/src/freeipa/ipa.js @@ -31,6 +31,16 @@ define(['./jquery', './text'], function($, JSON, i18n, metadata_provider, builder, reg, text) { +/** + * @class + * @singleton + * + * Defined in ipa module. Other modules extend it. + * + * There is a long-term goal to reduce the number of items in this namespace + * and move them to separate modules. + * + */ var IPA = function() { var that = { @@ -40,6 +50,10 @@ var IPA = function() { // live server path that.url = '/ipa/ui/'; + /** + * jQuery AJAX options used by RPC commands + * @property + */ that.ajax_options = { type: 'POST', contentType: 'application/json', @@ -48,17 +62,57 @@ var IPA = function() { processData: false }; + /** + * i18n messages + * @deprecated + * @property {Object} + */ that.messages = {}; + + /** + * User information + * + * - output of ipa user-find --whoami + */ that.whoami = {}; + /** + * Map of entities + * @deprecated + * @property {ordered_map} + */ that.entities = $.ordered_map(); + + /** + * Map of entity factories + * @deprecated + */ that.entity_factories = {}; + /** + * Number of currently active command calls - controls visibility of network indicator + */ that.network_call_count = 0; + /** + * UI state + * @property {boolean} initialized - Intialization completed: + * - metadata + * - user information + * - server configuration + * @property {boolean} logged_kerberos - User authenticated by + * Kerberos negotiation + * @property {boolean} logged_password - User authenticated by password + */ that.ui = {}; - /* initialize the IPA JSON-RPC helper */ + /** + * Load initialization data and initialize UI + * @param {Object} params + * @param {string} params.url - URL of JSON RPC interface + * @param {Function} params.on_success - success callback + * @param {Function} params.on_error - error callback + */ that.init = function(params) { // if current path matches live server path, use live data @@ -160,6 +214,12 @@ var IPA = function() { batch.execute(); }; + /** + * Prepares `user-find --whoami` command + * @protected + * @param {boolean} batch - Specifies if it will be used as single command or + * in a batch. + */ that.get_whoami_command = function(batch) { return IPA.command({ entity: 'user', @@ -175,6 +235,13 @@ var IPA = function() { }); }; + /** + * Executes RPC commands to load metadata + * @protected + * @param {Object} params + * @param {Function} params.on_success + * @param {Function} params.on_error + */ that.init_metadata = function(params) { var objects = IPA.command({ @@ -216,6 +283,12 @@ var IPA = function() { metadata_command.execute(); }; + /** + * Register entity factory in global registry + * @deprecated + * @param {string} name - Entity name + * @param {Function} factory - Entity factory + */ that.register = function(name, factory) { reg.entity.remove(name); reg.entity.register({ @@ -225,15 +298,28 @@ var IPA = function() { }); }; + /** + * Return entity instance with given name from global entity registry + * @deprecated + * @param {string} name - entity name + */ that.get_entity = function(name) { return reg.entity.get(name); }; + /** + * Display network activity indicator + */ that.display_activity_icon = function() { that.network_call_count++; $('.network-activity-indicator').css('visibility', 'visible'); }; + /** + * Hide network activity indicator + * + * - based on network_call_count + */ that.hide_activity_icon = function() { that.network_call_count--; @@ -249,19 +335,26 @@ var IPA = function() { }(); /** - * Basic object - * - * Framework objects created by factories should use this instead of {} when - * creating base objects. As an alternative they can just set __fw_obj - * property. + * Framework objects created by factories should use this + * instead of empty object when creating base objects. As an alternative + * they can just set __fw_obj property. * * __fw_obj property serves for telling the framework that it's instantiated * object and not an object specification (spec). + * + * @class */ -IPA.object = function() { +IPA.object = function(s) { return new IPA.obj_cls(); }; +/** + * Make request on Kerberos authentication url to initialize Kerberos negotiation. + * + * Set result to IPA.ui.logged_kerberos. + * + * @member IPA + */ IPA.get_credentials = function() { var status; @@ -289,6 +382,14 @@ IPA.get_credentials = function() { return status; }; +/** + * Logout + * + * - terminate the session. + * - redirect to logout landing page on success + * + * @member IPA + */ IPA.logout = function() { function show_error(message) { @@ -335,6 +436,14 @@ IPA.logout = function() { $.ajax(request); }; +/** + * Login by username and password + * + * @member IPA + * @param {string} username + * @param {string} password + * @return {string} Logout status - {password-expired, denied, invalid, success} + */ IPA.login_password = function(username, password) { var result = 'invalid'; @@ -383,6 +492,17 @@ IPA.login_password = function(username, password) { return result; }; +/** + * Reset user's password + * + * @member IPA + * @param {string} username + * @param {string} old_password + * @param {string} new_password + * @return {Object} result + * @return {string} result.status + * @return {string} result.message + */ IPA.reset_password = function(username, old_password, new_password) { //possible results: 'ok', 'invalid-password', 'policy-error' @@ -439,6 +559,13 @@ IPA.reset_password = function(username, old_password, new_password) { return result; }; +/** + * Check if password is about to expired (based on + * IPA.server_config.ipapwdexpadvnotify). If so, display a notification + * message with a link to reset password dialog. + * + * @member IPA + */ IPA.update_password_expiration = function() { var now, expires, notify_days, diff, message, container; @@ -476,6 +603,11 @@ IPA.update_password_expiration = function() { } }; +/** + * Show password dialog for self-service change of password. + * + * @member IPA + */ IPA.password_selfservice = function() { var reset_dialog = IPA.user_password_dialog({ self_service: true, @@ -495,6 +627,11 @@ IPA.password_selfservice = function() { reset_dialog.open(); }; +/** + * Parse value as UTC date + * @member IPA + * @return Data + */ IPA.parse_utc_date = function(value) { if (!value) return null; @@ -527,14 +664,17 @@ IPA.parse_utc_date = function(value) { /** * Call an IPA command over JSON-RPC. * - * Arguments: - * name - command name (optional) - * entity - command entity (optional) - * method - command method - * args - list of arguments, e.g. [username] - * options - dict of options, e.g. {givenname: 'Pavel'} - * on_success - callback function if command succeeds - * on_error - callback function if command fails + * @class IPA.command + * + * @param {Object} spec - construct specification + * @param {string} spec.name - command name (optional) + * @param {string} spec.entity - command entity(name) (optional) + * @param {string} spec.method - command method + * @param {string[]} spec.args - list of arguments, e.g. ['username'] + * @param {Object} spec.options - dict of options, e.g. {givenname: 'Petr'} + * @param {Function} spec.on_success - callback function if command succeeds + * @param {Function} spec.on_error - callback function if command fails + * */ IPA.command = function(spec) { @@ -542,44 +682,109 @@ IPA.command = function(spec) { var that = IPA.object(); + /** @property {string} name Name */ that.name = spec.name; + /** @property {entity.entity} entity Entity */ that.entity = spec.entity; + + /** @property {string} method Method */ that.method = spec.method; + /** @property {string[]} args Command Arguments */ that.args = $.merge([], spec.args || []); + + /** @property {Object} options Option map */ that.options = $.extend({}, spec.options || {}); + /** + * Success handler + * @property {Function} + * @param {Object} data + * @param {string} text_status + * @param {XMLHttpRequest} xhr + */ that.on_success = spec.on_success; + + /** + * Error handler + * @property {Function} + * @param {XMLHttpRequest} xhr + * @param {string} text_status + * @param {{name:string,message:string}} error_thrown + */ that.on_error = spec.on_error; + /** + * Allow retrying of execution if previous ended as error + * + * Manifested by error dialog. Set it to `false` for custom error dialogs or + * error handling without any dialog. + * @property {Boolean} retry=true + */ that.retry = typeof spec.retry == 'undefined' ? true : spec.retry; + /** @property {string} error_message Default error message */ that.error_message = text.get(spec.error_message || '@i18n:dialogs.batch_error_message', 'Some operations failed.'); + + /** @property {ordered_map.<number,string>} error_messages Error messages map */ that.error_messages = $.ordered_map({ 911: 'Missing HTTP referer. <br/> You have to configure your browser to send HTTP referer header.' }); + /** + * Get command name + * + * - it's `entity.name + '_' + method` + * - or `method` + * @return {string} + */ that.get_command = function() { return (that.entity ? that.entity+'_' : '') + that.method; }; + /** + * Add argument + * @param {string} arg + */ that.add_arg = function(arg) { that.args.push(arg); }; + /** + * Add arguments + * @param {string[]} args + */ that.add_args = function(args) { $.merge(that.args, args); }; + /** + * Set option + * @param {string} name + * @param {Mixed} value + */ that.set_option = function(name, value) { that.options[name] = value; }; + /** + * Extends options map with another options map + * + * @param {{opt1:Mixed, opt2:Mixed}} options + */ that.set_options = function(options) { $.extend(that.options, options); }; + /** + * Add value to an option + * + * - creates a new option if it does not exist yet + * - for option overriding use `set_option` method + * @param {string} name + * @param {Mixed} value + */ that.add_option = function(name, value) { var values = that.options[name]; if (!values) { @@ -589,14 +794,26 @@ IPA.command = function(spec) { values.push(value); }; + /** + * Get option value + * @return {Mixed} + */ that.get_option = function(name) { return that.options[name]; }; + /** + * Remove option from option map + */ that.remove_option = function(name) { delete that.options[name]; }; + /** + * Execute the command. + * + * Set `on_success` and/or `on_error` handlers to be informed about result. + */ that.execute = function() { function dialog_open(xhr, text_status, error_thrown) { @@ -788,6 +1005,15 @@ IPA.command = function(spec) { $.ajax(that.request); }; + /** + * Parse successful command result and get all errors. + * @protected + * @param {IPA.command} command + * @param {Object} result + * @param {string} text_status + * @param {XMLHttpRequest} xhr + * @return {IPA.error_list} + */ that.get_failed = function(command, result, text_status, xhr) { var errors = IPA.error_list(); if(result && result.failed) { @@ -809,12 +1035,21 @@ IPA.command = function(spec) { return errors; }; + /** + * Check if command accepts option + * @param {string} option_name + * @return {Boolean} + */ that.check_option = function(option_name) { var metadata = IPA.get_command_option(that.get_command(), option_name); return metadata !== null; }; + /** + * Encodes command into JSON-RPC command object + * @return {Object} + */ that.to_json = function() { var json = {}; @@ -827,6 +1062,10 @@ IPA.command = function(spec) { return json; }; + /** + * Encodes command into CLI command string + * @return {string} + */ that.to_string = function() { var string = that.get_command().replace(/_/g, '-'); @@ -844,7 +1083,18 @@ IPA.command = function(spec) { return that; }; -IPA.batch_command = function (spec) { +/** + * Call multiple IPA commands in a batch over JSON-RPC. + * + * @class IPA.batch_command + * @extends IPA.command + * + * @param {Object} spec + * @param {Array.<IPA.command>} spec.commands - IPA commands to be executed + * @param {Function} spec.on_success - callback function if command succeeds + * @param {Function} spec.on_error - callback function if command fails + */ +IPA.batch_command = function(spec) { spec = spec || {}; @@ -852,22 +1102,40 @@ IPA.batch_command = function (spec) { var that = IPA.command(spec); + /** @property {IPA.command[]} commands Commands */ that.commands = []; + /** @property {IPA.error_list} errors Errors */ that.errors = IPA.error_list(); + + /** + * Show error if some command fail + * @property {Boolean} show_error=true + */ that.show_error = typeof spec.show_error == 'undefined' ? true : spec.show_error; + /** + * Add command + * @param {IPA.command} command + */ that.add_command = function(command) { that.commands.push(command); that.add_arg(command.to_json()); }; + /** + * Add commands + * @param {IPA.command[]} commands + */ that.add_commands = function(commands) { for (var i=0; i<commands.length; i++) { that.add_command(commands[i]); } }; + /** + * @inheritDoc + */ that.execute = function() { that.errors.clear(); @@ -886,6 +1154,16 @@ IPA.batch_command = function (spec) { command.execute(); }; + /** + * Internal XHR success handler + * + * Parses data and looks for errors. `on_success` or `on_error` is then + * called. + * @protected + * @param {Object} data + * @param {string} text_status + * @param {XMLHttpRequest} xhr + */ that.batch_command_on_success = function(data, text_status, xhr) { for (var i=0; i<that.commands.length; i++) { @@ -965,6 +1243,13 @@ IPA.batch_command = function (spec) { } }; + /** + * Internal XHR error handler + * @protected + * @param {XMLHttpRequest} xhr + * @param {string} text_status + * @param {{name:string,message:string}} error_thrown + */ that.batch_command_on_error = function(xhr, text_status, error_thrown) { // TODO: undefined behavior if (that.on_error) { @@ -975,16 +1260,45 @@ IPA.batch_command = function (spec) { return that; }; - +/** + * Call multiple IPA commands over JSON-RPC separately and wait for every + * command's response. + * + * - concurrent command fails if any command fails + * - result is reported when each command finishes + * + * @class IPA.concurrent_command + * + * @param {Object} spec - construct specification + * @param {Array.<IPA.command>} spec.commands - IPA commands to execute + * @param {Function} spec.on_success - callback function if each command succeed + * @param {Function} spec.on_error - callback function one command fails + * + */ IPA.concurrent_command = function(spec) { spec = spec || {}; var that = IPA.object(); + /** @property {IPA.command[]} commands Commands */ that.commands = []; + + /** + * Success handler + * @property {Function} + */ that.on_success = spec.on_success; + + /** + * Error handler + * @property {Function} + */ that.on_error = spec.on_error; + /** + * Add commands + * @param {IPA.command[]} commands + */ that.add_commands = function(commands) { if(commands && commands.length) { @@ -996,6 +1310,9 @@ IPA.concurrent_command = function(spec) { } }; + /** + * Execute the commands one by one. + */ that.execute = function() { var command_info, command, i; @@ -1035,6 +1352,10 @@ IPA.concurrent_command = function(spec) { } }; + /** + * Internal error handler + * @protected + */ that.error_handler = function(command_info, xhr, text_status, error_thrown) { command_info.completed = true; @@ -1046,6 +1367,10 @@ IPA.concurrent_command = function(spec) { that.command_completed(); }; + /** + * Internal success handler + * @protected + */ that.success_handler = function(command_info, data, text_status, xhr) { command_info.completed = true; @@ -1057,6 +1382,11 @@ IPA.concurrent_command = function(spec) { that.command_completed(); }; + /** + * Check if all commands finished. + * If so, report it. + * @protected + */ that.command_completed = function() { var all_completed = true; @@ -1077,6 +1407,10 @@ IPA.concurrent_command = function(spec) { } }; + /** + * Call each command's success handler and `on_success`. + * @protected + */ that.on_success_all = function() { for(var i=0; i < that.commands.length; i++) { @@ -1095,6 +1429,10 @@ IPA.concurrent_command = function(spec) { } }; + /** + * Call each command's error handler and `on_success`. + * @protected + */ that.on_error_all = function() { if(that.on_error) { @@ -1116,11 +1454,24 @@ IPA.concurrent_command = function(spec) { return that; }; +/** + * Build object with {@link builder}. + * @member IPA + * @param {Object} spec - contruction spec + * @param {Object} context + * @param {Object} overrides + */ IPA.build = function(spec, context, overrides) { return builder.build(null, spec, context, overrides); }; +/** + * Create a object defined by spec with IPA.object as parent. + * @member IPA + * @param {Object} spec + * @return {Object} new object with all properties as spec + */ IPA.default_factory = function(spec) { spec = spec || {}; @@ -1132,23 +1483,46 @@ IPA.default_factory = function(spec) { return that; }; -/* helper function used to retrieve information about an attribute */ +/** + * Helper function used to retrieve information about an object attribute from metadata + * @member IPA + * @param {string} entity_name + * @param {string} name - attribute name + */ IPA.get_entity_param = function(entity_name, name) { return metadata_provider.get(['@mo-param', entity_name, name].join(':')); }; +/** + * Helper function used to retrieve information about an command argument from metadata + * @member IPA + * @param {string} command_name + * @param {string} arg_name - argument name + */ IPA.get_command_arg = function(command_name, arg_name) { return metadata_provider.get(['@mc-arg', command_name, arg_name].join(':')); }; + +/** + * Helper function used to retrieve information about an command option from metadata + * @member IPA + * @param {string} command_name + * @param {string} option_name - argument name + */ IPA.get_command_option = function(command_name, option_name) { return metadata_provider.get(['@mc-opt', command_name, option_name].join(':')); }; -/* helper function used to retrieve attr name with members of type `member` */ +/** + * Helper function used to retrieve information about an attribute member + * @member IPA + * @param {string} obj_name - object(entity) name + * @param {string} member - attribute member + */ IPA.get_member_attribute = function(obj_name, member) { var obj = metadata_provider.get('@mo:'+obj_name); @@ -1169,6 +1543,11 @@ IPA.get_member_attribute = function(obj_name, member) { return null; }; +/** + * Create HTML representation of network spinner. + * @member IPA + * @return {HTMLElement} Network spinner node + */ IPA.create_network_spinner = function(){ var span = $('<span/>', { 'class': 'network-activity-indicator' @@ -1179,6 +1558,18 @@ IPA.create_network_spinner = function(){ return span; }; +/** + * Dirty dialog + * + * Should be used as an indication of unsaved changes on page when leaving the + * page. Offers user to safe/reset the changes or cancel the action. + * + * @class + * @extends IPA.dialog + * @param {Object} spec + * @param {IPA.facet} spec.facet - Dirty facet + * @param {string} [spec.message] - Displayed message + */ IPA.dirty_dialog = function(spec) { spec = spec || {}; @@ -1186,9 +1577,14 @@ IPA.dirty_dialog = function(spec) { spec.width = spec.width || '25em'; var that = IPA.dialog(spec); + + /** @property {facet.facet} facet Facet*/ that.facet = spec.facet; + + /** @property {string} message Dirty message*/ that.message = text.get(spec.message || '@i18n:dialogs.dirty_message'); + /** @inheritDoc */ that.create = function() { that.container.append(that.message); }; @@ -1222,12 +1618,25 @@ IPA.dirty_dialog = function(spec) { } }); + /** + * Function which is called when user click on 'update' or 'delete' button + */ that.callback = function() { }; return that; }; +/** + * Error dialog + * + * Serves for notifying an error in RPC command. + * + * @class + * @extends IPA.dialog + * @mixins IPA.confirm_mixin + * @param {Object} spec + */ IPA.error_dialog = function(spec) { spec = spec || {}; @@ -1240,20 +1649,32 @@ IPA.error_dialog = function(spec) { IPA.confirm_mixin().apply(that); + /** @property {XMLHttpRequest} xhr Command's xhr */ that.xhr = spec.xhr || {}; + /** @property {string} text_status Command's text status */ that.text_status = spec.text_status || ''; + /** @property {{name:string,message:string}} error_thrown Command's error */ that.error_thrown = spec.error_thrown || {}; + /** @property {IPA.command} command Command */ that.command = spec.command; + /** @property {IPA.error_list} errors Errors */ that.errors = spec.errors; + /** @property {string[]} visible_buttons=['retry', 'cancel'] Visible button names */ that.visible_buttons = spec.visible_buttons || ['retry', 'cancel']; - + /** + * Beautify error message + * + * Multi-lined text may contain TAB character as first char of the line + * to hint at marking the whole line differently. + * @param {jQuery} container Container to add the beautified message. + * @param {string} message + */ that.beautify_message = function(container, message) { var lines = message.split(/\n/g); var line_span; for(var i=0; i<lines.length; i++) { - // multi-lined text may contain TAB character as first char of the line - // to hint at marking the whole line differently + if (lines[i].charAt(0) == '\t') { line_span = $('<p />', { 'class': 'error-message-hinted', @@ -1267,6 +1688,7 @@ IPA.error_dialog = function(spec) { } }; + /** @inheritDoc */ that.create = function() { if (that.error_thrown.url) { $('<p/>', { @@ -1327,12 +1749,15 @@ IPA.error_dialog = function(spec) { } }; + /** + * Create dialog buttons + * @protected + */ that.create_buttons = function() { - /** - * When a user initially opens the Web UI without a Kerberos - * ticket, the messages including the button labels have not - * been loaded yet, so the button labels need default values. - */ + + // When a user initially opens the Web UI without a Kerberos + // ticket, the messages including the button labels have not + // been loaded yet, so the button labels need default values. var visible = that.visible_buttons.indexOf('retry') > -1; var label = text.get('@i18n:buttons.retry', 'Retry'); @@ -1368,19 +1793,35 @@ IPA.error_dialog = function(spec) { }); }; + /** + * Retry handler + * @protected + */ that.on_retry = function() { that.close(); that.command.execute(); }; + /** + * OK button handler + * @protected + */ that.on_ok = function() { that.close(); }; + /** + * Cancel button and negative confirmation handler + * @protected + */ that.on_cancel = function() { that.close(); }; + /** + * Positive confirmation handler + * @protected + */ that.on_confirm = function() { if (that.visible_buttons.indexOf('retry') > -1) that.on_retry(); else that.on_ok(); @@ -1391,13 +1832,23 @@ IPA.error_dialog = function(spec) { return that; }; +/** + * Error list + * + * Collection for RPC command errors. + * + * @class IPA.error_list + * @private + */ IPA.error_list = function() { var that = IPA.object(); + /** Clear errors */ that.clear = function() { that.errors = []; }; + /** Add error */ that.add = function(command, name, message, status) { that.errors.push({ command: command, @@ -1407,10 +1858,15 @@ IPA.error_list = function() { }); }; + /** Add errors */ that.add_range = function(error_list) { that.errors = that.errors.concat(error_list.errors); }; + /** + * Check if there are no errors + * @return {Boolean} + */ that.is_empty = function () { return that.errors.length === 0; }; @@ -1419,6 +1875,14 @@ IPA.error_list = function() { return that; }; +/** + * Error handler for IPA.command which handles error #4304 as success. + * + * 4304 is raised when part of an operation succeeds and the part that failed + * isn't critical. + * @member IPA + * @param {IPA.entity_adder_dialog} adder_dialog + */ IPA.create_4304_error_handler = function(adder_dialog) { var set_pkey = function(result) { @@ -1460,6 +1924,16 @@ IPA.create_4304_error_handler = function(adder_dialog) { }; }; +/** + * Unauthorized dialog + * + * Notifies that user's session is expired. It supports forms-based authentication + * and password reset when password is expired. + * + * @class IPA.unauthorized_dialog + * @extends IPA.error_dialog + * @param {Object} spec + */ IPA.unauthorized_dialog = function(spec) { spec = spec || {}; @@ -1515,14 +1989,18 @@ IPA.unauthorized_dialog = function(spec) { var that = IPA.error_dialog(spec); + /** @inheritDoc */ that.title = spec.title || text.get('@i18n:login.login', "Login"); + /** @property {string} message Session expired message */ that.message = text.get(spec.message || '@i18n:ajax.401.message', "Your session has expired. Please re-login."); + /** @property {string} form_auth_msg Forms authentication message */ that.form_auth_msg = text.get(spec.form_auth_msg || '@i18n:login.form_auth', "To login with username and password, enter them in the fields below then click Login."); + /** @property {string} krb_auth_msg Kerberos authentication message */ that.krb_auth_msg = text.get(spec.krb_auth_msg || '@i18n:login.krb_auth_msg', " To login with Kerberos, please make sure you" + " have valid tickets (obtainable via kinit) and " + @@ -1531,21 +2009,29 @@ IPA.unauthorized_dialog = function(spec) { that.krb_auth_msg = that.krb_auth_msg.replace('${host}', window.location.hostname); + /** @property {string} form_auth_failed Forms authentication failure message */ that.form_auth_failed = "<p><strong>Please re-enter your username or password</strong></p>" + "<p>The password or username you entered is incorrect. " + "Please try again (make sure your caps lock is off).</p>" + "<p>If the problem persists, contact your administrator.</p>"; + /** @property {string} password_expired Password expired message */ that.password_expired = "Your password has expired. Please enter a new password."; + /** @property {string} denied Login denied message */ that.denied = "Sorry you are not allowed to access this service."; + /** @inheritDoc */ that.create = function() { that.session_expired_form(); that.create_reset_form(); }; + /** + * Create session expired form + * @protected + */ that.session_expired_form = function() { that.session_form = $('<div\>').appendTo(that.container); @@ -1585,6 +2071,10 @@ IPA.unauthorized_dialog = function(spec) { that.username_widget.value_changed.attach(that.on_username_change); }; + /** + * Create password reset form + * @protected + */ that.create_reset_form = function() { that.reset_form = $('<div\>', { @@ -1611,6 +2101,10 @@ IPA.unauthorized_dialog = function(spec) { that.verify_password_widget = that.widgets.get_widget('reset.verify_password'); }; + /** + * Create dialog buttons + * @protected + */ that.create_buttons = function() { that.buttons.empty(); @@ -1649,12 +2143,17 @@ IPA.unauthorized_dialog = function(spec) { }); }; + /** @inheritDoc */ that.open = function() { that.dialog_open(); that.show_session_form(); that.check_error_reason(); }; + /** + * Check if response contains IPA specific rejection reason. + * @protected + */ that.check_error_reason = function() { if (this.xhr) { var reason = this.xhr.getResponseHeader("X-IPA-Rejection-Reason"); @@ -1664,6 +2163,10 @@ IPA.unauthorized_dialog = function(spec) { } }; + /** + * User name field value change handler + * @protected + */ that.on_username_change = function() { var password_field = that.fields.get_field('password'); @@ -1672,6 +2175,11 @@ IPA.unauthorized_dialog = function(spec) { if (!user_specified) that.password_widget.clear(); }; + /** + * Enable fields with given name + * @protected + * @param {string[]} field_names + */ that.enable_fields = function(field_names) { var field, fields, i, enable; @@ -1683,6 +2191,10 @@ IPA.unauthorized_dialog = function(spec) { } }; + /** + * Shows session expired form. Hides other. + * @protected + */ that.show_session_form = function() { that.current_view = 'session'; @@ -1693,6 +2205,10 @@ IPA.unauthorized_dialog = function(spec) { that.username_widget.focus_input(); }; + /** + * Shows password reset form. Hides other. + * @protected + */ that.show_reset_form = function() { that.current_view = 'reset'; @@ -1706,6 +2222,11 @@ IPA.unauthorized_dialog = function(spec) { that.new_password_widget.focus_input(); }; + /** + * Show login error message - based on reason + * @protected + * @param {"invalid"|"denied"|string} reason + */ that.show_login_error_message = function(reason) { var errors = { 'invalid': that.form_auth_failed, @@ -1720,6 +2241,10 @@ IPA.unauthorized_dialog = function(spec) { } }; + /** + * Cancel handler + * @protected + */ that.on_cancel = function() { that.username_widget.clear(); @@ -1731,6 +2256,10 @@ IPA.unauthorized_dialog = function(spec) { that.show_session_form(); }; + /** + * Initiates login procedure + * @protected + */ that.on_login = function() { var username = that.username_widget.save(); @@ -1760,6 +2289,10 @@ IPA.unauthorized_dialog = function(spec) { } }; + /** + * Login success handler + * @protected + */ that.on_login_success = function() { that.login_error_box.css('display', 'none'); @@ -1769,6 +2302,10 @@ IPA.unauthorized_dialog = function(spec) { that.on_retry(); }; + /** + * Initiates password reset procedure + * @protected + */ that.on_reset = function() { if (!that.validate()) return; @@ -1791,6 +2328,10 @@ IPA.unauthorized_dialog = function(spec) { } }; + /** + * Password reset success handler + * @protected + */ that.on_reset_success = function() { that.login_error_box.css('display', 'none'); @@ -1807,7 +2348,10 @@ IPA.unauthorized_dialog = function(spec) { that.on_login(); }; - //replaces confirm_mixin method + /** + * Key up handler for proper keyboard usage. + * @protected + */ that.on_key_up = function(event) { if (that.switching) { @@ -1836,6 +2380,15 @@ IPA.unauthorized_dialog = function(spec) { return that; }; +/** + * Shorten text to desired number of characters. + * + * If shortened, '...' is appended to the shortened text. + * @member IPA + * @param {string} value - text to shorten + * @param {number} max_length - maximum number of characters + * @return {string} shortened text + */ IPA.limit_text = function(value, max_length) { if (!value) return ''; @@ -1849,6 +2402,13 @@ IPA.limit_text = function(value, max_length) { return limited_text; }; + +/** + * Convert strings to options. + * @member IPA + * @param {string[]} values - options as strings + * @return {Array.<{value,label}>} options + */ IPA.create_options = function(values) { var options = []; @@ -1870,6 +2430,19 @@ IPA.create_options = function(values) { return options; }; +/** + * Check if value is not defined. + * + * True when: + * + * - value is undefined or null or '' + * - value is empty Array + * - value is Array with an empty string ('') + * - value is empty Object- {} + * @member IPA + * @param value - value to check + * @return {boolean} + */ IPA.is_empty = function(value) { var empty = false; @@ -1893,11 +2466,29 @@ IPA.is_empty = function(value) { return empty; }; +/** + * Check if value is not null or undefined. + * @member IPA + * @param value + * @param {boolean} check_empty_str - additional check for empty string + */ IPA.defined = function(value, check_empty_str) { return value !== null && value !== undefined && ((check_empty_str && value !== '') || !check_empty_str); }; + +/** + * Check if arrays differ. + * + * False when: + * + * - length and items or arrays equals (===) + * - undefined state of both is the same + * @member IPA + * @param a + * @param b + */ IPA.array_diff = function(a, b) { if (a === b || (!a && !b)) return false; @@ -1913,10 +2504,23 @@ IPA.array_diff = function(a, b) { return false; }; +/** + * Shows confirm dialog with message + * @member IPA + * @param {string} msg - message + * @return {boolean} confirmed state + */ IPA.confirm = function(msg) { return window.confirm(msg); }; +/** + * Display positive notification message + * @member IPA + * @param {string} message + * @param {number} [timeout=IPA.config.message_timeout] - duration for the + * message to be displayed [ms] + */ IPA.notify_success = function(message, timeout) { if (!message) return; // don't show undefined, null and such @@ -1951,6 +2555,12 @@ IPA.notify_success = function(message, timeout) { }, timeout || IPA.config.message_timeout); }; +/** + * Get number of succeeded commands in RPC command + * @member IPA + * @param {Object} data - RPC command data + * @return {number} + */ IPA.get_succeeded = function(data) { var succeeded = data.result.completed; @@ -1966,6 +2576,15 @@ IPA.get_succeeded = function(data) { return succeeded; }; +/** + * Global configuration + * @member IPA + * @property {number} default_priority - command default priority. Used in + * 'update info' concept + * @property {number} message_timeout - timeout for notification messages + * @property {number} message_fadeout_time + * @property {number} message_fadein_time + */ IPA.config = { default_priority: 500, message_timeout: 3000, // [ms] |