A5WS_Save_WebUser_Values Function
Syntax
Arguments
- Result
The result value is not meaningful if the function is being used in a web component.
- result.errors = Will return TRUE if any errors are found during processing.
- result.error_text = Error messages returned.
- CurrentForm
- UserValue
Optional. A pointer variable used to pass user defined value to the function. These will override the same values passed by the Request system variable. Users are identified by a value in the guid property of UserValue. If UserValue.guid is not specified, the function will use the value passed by the Request system variable.
- UserValue.guid = The user GUID value for the desired user record
- request
Optional. The Request system variable. The request variable should be considered READ ONLY. It is added automatically by the server when run from a web page. Users may be found by
- request.variable.guid = The user GUID value for the desired user record
Description
The CurrentForm variable, a system variable that refers to the contents of the dialog component.
Validate & Save values in the 'CurrentForm' controls that match fields in the user table for the current project. 'UserValue' overrides values passed by the request system variable. Accepts values as 'UserValue.Email', 'UserValue.Ulink', etc
Discussion
The A5WS_Save_WebUser_Values() function validates values from controls in a dialog component and then saves the values to fields in the Web Security User table. If you only want to validate the values without saving, use the function A5WS_Validate_WebUser_Values. Only values passed in the request.variable property of the request variable, or values passed by the pointer UserValue, are saved. The value in request.variable.guid will be used to find an existing record. An optional value can be supplied in UserValue.guid to override the value in request.variable.guid. If both values are blank, the record will be considered a new record. The name of each control in the dialog must exactly match the name of the field in the user table. A list of valid field names can be found by using the A5WS_User_File_Field_List() function. It is used in the Server Validate event of a dialog component. Adding Users with a Web Component shows how the function is used in dialog component event. If validation errors are detected, the form will be redisplayed with the error message shown at the top of the form and the variable CurrentForm.Has_Error will be TRUE. The user can then make corrections and resubmit the form. If the variable CurrentForm.Has_Error = .T. prior to calling the function, the function will test the security control values for validation and return any errors, but will not save the values. The security values will only be saved if CurrentForm.Has_Error =.F.
- 1. Display the Form > Properties menu page of the Dialog Builder.
- 2. Click in the Server Events > Validate property.
Example
Note that CurrentForm and Request are the names of variables created by the Application Server.
A5WS_Save_WebUser_Values(CurrentForm)
Using the Function Outside of a Dialog Component
The function is designed to be used within Server Events of a dialog component. However, it can be used on any Xbasic code section on a web page or component to save various values for a specific user. It is helpful to get a list of valid field names currently being used in the user security table by using the A5WS_User_File_Field_List() function. One additional field named groups can be saved. Groups should contain a comma delimited or CR-LF delimited list of the security groups assigned to the user. The group values can be the group_guid value for each group or the group_name of each group.
?a5ws_User_File_Field_List() = Email Guid Password Ulink Userid
The function will only save values for fields passed to the function in the Request system variable as request.variable. and will only save values for fields currently being used by the security system. NOTE: Security Settings may be defined to require values in certain User Verification Fields during data entry on the web. If these fields are included in the Request or UserValue variables, they can not be blank, or the record will not be saved and an error message will be returned. A value MUST be passed to the function to find the current user. This MUST be provided by either the system supplied request.variable.guid or a user supplied value in UserValue.guid. No other input value can be used to find an existing record. WARNING: If the guid value is not passed to the function, the guid value is blank, or the guid value doesn't match an existing record, a new record will be created. A userid value must be an input value for a new record, or the save is cancelled and returns an error message. Userid does not have to be entered for an existing record unless the value for userid is being changed. Only values sent to the function will be saved. If the record already exists, any values not sent to the function are unchanged. If the record is a new record, the security settings may have defined required fields. If required fields as not supplied for a new record, validation may fail, and nothing wil be saved. This code below will set the parameters to send to the function to find the user with a guid="20860aa66cfa4feb83ba25887d303f59" and change the email address to "[email protected]".
dim uservalue as p dim uservalue.guid as c dim uservalue.email as c uservalue.guid = "20860aa66cfa4feb83ba25887d303f59" uservalue.email = "[email protected]"
This code could be used in place of the code above to set the parameters to send to the function to enter a new user record with a userid = "[email protected]" and an email address with the same value. The new user record will have a password added with the value of "password". Since no guid is input, a new record is created. The function will automatically create a new guid value for the record when the record is saved.
dim uservalue.userid as c dim uservalue.email as c dim uservalue.password as c uservalue.userid = "[email protected]" uservalue.email = "[email protected]" uservalue.password = "password"
This code will set the parameters to set the user's group assignments to "Administrators" and "Marketing" if the user groups are being added or edited. The function will only save groups that are valid values in security groups definitions.
dim uservalue.groups as c uservalue.groups = "Administrators,Marketing"
An output pointer must be defined before the function is run. The function will always return the guid value for a saved record as .Controls.guid.value. If a new record was created, the function will NOT update the value in request.variable.guid if request variables were passed to the function. Request.variable.guid may be blank for a new record. The function will also return values for any fields passed to the function in the Request system variable.
dim output as p dim output.controls as p dim output.controls.guid.value as c
The parameters to send to the function, and the output pointers must be set before the function is run. When the function is run, it will return the values saved as .controls..value. The result.errors value can be tested to determine if any errors occured during processing. Any error messages will be should be returned in the result.error_text value.
dim result as p
dim error_message as c
result = a5ws_Save_WebUser_Values(output,uservalue)
if result.errors = .T. then
error_message = result.error_text
end
end if
user_guid = output.controls.guid.valueYou can reload the values saved by the function back into the pointer variable output with the function A5WS_Get_WebUser_Values after the save function was run.
dim uservalue as p
dim uservalue.guid as c
uservalue.guid = output.controls.guid.value ' this was populated when the record was saved above.
dim result as p
dim error_message as c
result = a5ws_Get_WebUser_Values(output,uservalue)
if result.errors = .T. then
error_message = result.error_text
end
end if
user_id = output.controls.user.valueLimitations
May only be used in a web component or web page.
See Also