Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
wiki:form_editing [2010/03/01 21:16] wrdieter finction -> function |
wiki:form_editing [2017/12/12 17:19] (current) admin |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ~~ODT~~ | ||
| ====== Form Editing ====== | ====== Form Editing ====== | ||
| - | jqGrid supports creating a form "on the fly" to view, add, edit, or delete grid data. The methods listed below are included in the navGrid (navigator method) | ||
| - | ===== Installation ===== | + | jqGrid supports creating a form "on the fly" to view, add, edit, delete, or search grid data. A screenshot of an "Add Record" form is shown below: |
| - | In order to use this module you should mark the Common, Form Editing and optional jqModal and jqDnR plugins when you download the grid. For more information refer to [[Download]].\\ | + | |
| - | For Developers - this is the grid.common.js, grid.formedit.js, jqModal.js and jqDnR.js in the src directory. | + | {{:wiki:formeditshot.jpg|}} |
| + | |||
| + | <note tip>It's possible to use a combination of Modal Boxes and Inline Editing in your application. After all, Inline editing can only be used to edit an existing row and can't be used to search, delete, or add data. However, it's not recommended to use both Inline Editing and Modal Box Editing because one will interfere with the other when both select the same row. (In this scenario, when you select a row for editing then click the edit model box, you'll get the ID names of the cells in the box rather than the actual cell data contents.</note> | ||
| + | |||
| + | |||
| + | |||
| + | |||
| + | The methods listed in the table below are included in the navGrid (navigator method). | ||
| + | |||
| + | ===== Software Requirements & Installation ===== | ||
| + | |||
| + | To use this module, you should mark the Common, Form Editing and optional jqModal and jqDnR plugins when you download the grid. For more information refer to [[Download]].\\ | ||
| + | |||
| + | Note For Developers - this is the grid.common.js, grid.formedit.js, jqModal.js and jqDnR.js in the src directory. | ||
| Line 14: | Line 25: | ||
| ==== searchGrid ==== | ==== searchGrid ==== | ||
| - | For more information about this method refer to [[Singe Searching]] and [[Advanced Searching]] | + | For more information about this method refer to [[Single Searching]] and [[Advanced Searching]] |
| ==== editGridRow ==== | ==== editGridRow ==== | ||
| - | This method create a form via modal dialog for editing a particular row from the grid. \\ | + | This method creates a form via modal dialog for editing a particular row from the grid. \\ |
| This method uses [[wiki:common_rules | Common Editing Properties ]] from colModel and editurl option from jqGrid. | This method uses [[wiki:common_rules | Common Editing Properties ]] from colModel and editurl option from jqGrid. | ||
| Line 92: | Line 103: | ||
| |ajaxEditOptions|This option allow to set global ajax settings for the form editiing when we save the data to the server. Note that with this option is possible to overwrite all current ajax setting in the save request including the complete event.|empty object| | |ajaxEditOptions|This option allow to set global ajax settings for the form editiing when we save the data to the server. Note that with this option is possible to overwrite all current ajax setting in the save request including the complete event.|empty object| | ||
| |viewPagerButtons| This option enable or disable the appearing of the previous and next buttons (pager buttons) in the form |true| | |viewPagerButtons| This option enable or disable the appearing of the previous and next buttons (pager buttons) in the form |true| | ||
| + | |zIndex|The starting z-index for the dialog. If you will see the dialog form under another elements or dialogs you should use the parameter with some value higher as default value 950. In the most cases it should be the value higher as 1000 - the default value of jQuery UI dialog.|950| | ||
| === Events === | === Events === | ||
| ^Event^Description^ | ^Event^Description^ | ||
| - | |afterclickPgButtons|This event can be used only when we are in edit mode and the navigator buttons are enabled; it fires after the data for the new row is loaded from the grid, allowing modification of the data or form before the form is redisplayed. \\ afterclickPgButtons : function(whichbutton, formid, rowid) {...} \\ where \\ //whichbutton// is either 'prev' or 'next' \\ //formid// is the id of the form \\ //rowid// is the id of the current row | | + | |afterclickPgButtons|This event can be used only when we are in edit mode and the navigator buttons are enabled; it fires after the data for the new row is loaded from the grid, allowing modification of the data or form before the form is redisplayed. \\ afterclickPgButtons : function(whichbutton, formid, rowid) {...} \\ where \\ //whichbutton// is either 'prev' or 'next' \\ //formid// is the jQuery object of form id, you can use formid[0].id to get form id. \\ //rowid// is the id of the current row | |
| - | |afterComplete| This event fires immediately after all actions and events are completed and the row is inserted or updated in the grid. \\ afterComplete : function (response, postdata, formid) {...} \\ where \\ //response// is the data returned from the server (if any) \\ //postdata// an array, is the data sent to the server \\ //formid// is the id of the form | | + | |afterComplete| This event fires immediately after all actions and events are completed and the row is inserted or updated in the grid. \\ afterComplete : function (response, postdata, formid) {...} \\ where \\ //response// is the data returned from the server (if any) \\ //postdata// an array, is the data sent to the server \\ //formid// is the jQuery object of form id, you can use formid[0].id to get form id. | |
| |afterShowForm|fires after showing the form; receives as Parameter the id of the constructed form. \\ afterShowForm : function (formid) {...} | | |afterShowForm|fires after showing the form; receives as Parameter the id of the constructed form. \\ afterShowForm : function (formid) {...} | | ||
| |afterSubmit| fires after response has been received from server. Typically used to display status from server (e.g., the data is successfully saved or the save cancelled for server-side editing reasons). Receives as parameters the data returned from the request and an array of the posted values of type id=value1,value2. \\ When used this event should return array with the following items [success, message, new_id] \\ where \\ //success// is a boolean value if true the process continues, if false a error //message// appear and all other processing is stopped. (message is ignored if success is true). \\ //new_id// can be used to set the new row id in the grid when we are in add mode. \\ afterSubmit : function(response, postdata) \\ { \\ ... \\ return [success,message,new_id] \\ } | | |afterSubmit| fires after response has been received from server. Typically used to display status from server (e.g., the data is successfully saved or the save cancelled for server-side editing reasons). Receives as parameters the data returned from the request and an array of the posted values of type id=value1,value2. \\ When used this event should return array with the following items [success, message, new_id] \\ where \\ //success// is a boolean value if true the process continues, if false a error //message// appear and all other processing is stopped. (message is ignored if success is true). \\ //new_id// can be used to set the new row id in the grid when we are in add mode. \\ afterSubmit : function(response, postdata) \\ { \\ ... \\ return [success,message,new_id] \\ } | | ||
| |beforeCheckValues|This event fires before checking the values (if checking is defined in colModel via editrules option). \\ To this event we pass the following parameters: \\ 1. //posdata// - the array of values which should be chaced in name:value pair, where the name is the name from colModel. \\ 2. //formid// - the form id object. \\ 3. //mode// - the current mode in which we are - can be add or edit. \\ In all cases the event should return object in name value pair which then will be posted to the server.| | |beforeCheckValues|This event fires before checking the values (if checking is defined in colModel via editrules option). \\ To this event we pass the following parameters: \\ 1. //posdata// - the array of values which should be chaced in name:value pair, where the name is the name from colModel. \\ 2. //formid// - the form id object. \\ 3. //mode// - the current mode in which we are - can be add or edit. \\ In all cases the event should return object in name value pair which then will be posted to the server.| | ||
| - | |beforeInitData|fires before initialize the new form data. Receives, as parameter, the id of the constructed form. \\ beforeInitData : function(formid) {...} | | + | |beforeInitData|fires before initialize the new form data. Receives, as parameter, the jQuery object of the constructed form. The Event can return true or false.If the event return false the the action is not done and the form is not lunched.\\ beforeInitData : function(formid) {...} | |
| |beforeShowForm|fires before showing the form with the new data; receives as Parameter the id of the constructed form. \\ beforeShowForm : function(formid) {...} | | |beforeShowForm|fires before showing the form with the new data; receives as Parameter the id of the constructed form. \\ beforeShowForm : function(formid) {...} | | ||
| |beforeSubmit|fires before the data is submitted to the server. Recieves as parameter the posted data array and the formid. \\ beforeSubmit : function(postdata, formid) { \\ ... \\ return[success,message]; \\ } \\ When defined this event should return array with the following values \\ //success// boolean indicating if the proccess should continue (true) or a error (false) //message// should appear to the user| | |beforeSubmit|fires before the data is submitted to the server. Recieves as parameter the posted data array and the formid. \\ beforeSubmit : function(postdata, formid) { \\ ... \\ return[success,message]; \\ } \\ When defined this event should return array with the following values \\ //success// boolean indicating if the proccess should continue (true) or a error (false) //message// should appear to the user| | ||
| - | |onclickPgButtons|This event can be used only when we are in edit mode; it fires immediately after the previous or next button is clicked, before leaving the current row, allowing working with (e.g., saving) the currently loaded values in the form. \\ onclickPgButtons : function (whichbutton, formid, rowid) {...} \\ where \\ //whichbutton// is either 'prev' or 'next' \\ //formid// is the id of the form \\ //rowid// is the id of the current row | | + | |onclickPgButtons|This event can be used only when we are in edit mode; it fires immediately after the previous or next button is clicked, before leaving the current row, allowing working with (e.g., saving) the currently loaded values in the form. \\ onclickPgButtons : function (whichbutton, formid, rowid) {...} \\ where \\ //whichbutton// is either 'prev' or 'next' \\ //formid// is the jQuery object of form id, you can use formid[0].id to get form id. \\ //rowid// is the id of the current row | |
| |onclickSubmit|fires after the submit button is clicked and the postdata is constructed. Parameters passed to this event are: a options array of the method and the posted data array. The event should return array of type {} which extends the postdata array. \\ onclickSubmit : function(params, posdata) { \\ ... \\ return {add_data} \\ }| | |onclickSubmit|fires after the submit button is clicked and the postdata is constructed. Parameters passed to this event are: a options array of the method and the posted data array. The event should return array of type {} which extends the postdata array. \\ onclickSubmit : function(params, posdata) { \\ ... \\ return {add_data} \\ }| | ||
| |onInitializeForm|fires only once when creating the data for editing and adding. Receives, as parameter, the id of the constructed form. \\ onInitializeForm : function(formid) {...}| | |onInitializeForm|fires only once when creating the data for editing and adding. Receives, as parameter, the id of the constructed form. \\ onInitializeForm : function(formid) {...}| | ||
| Line 146: | Line 158: | ||
| or with the new API | or with the new API | ||
| <code javascript> | <code javascript> | ||
| - | jQuery("#grid_id").jqGrid('editGridRow, "new", properties ); | + | jQuery("#grid_id").jqGrid('editGridRow', "new", properties ); |
| </code> | </code> | ||
| Line 250: | Line 262: | ||
| |labelswidth|Since we construct the view with table element it is difficult to calculate, in this case, how much width is needed for the labels. Depending on the needs this value can be increased or decreased|30%| | |labelswidth|Since we construct the view with table element it is difficult to calculate, in this case, how much width is needed for the labels. Depending on the needs this value can be increased or decreased|30%| | ||
| |viewPagerButtons| This option enable or disable the appearing of the previous and next buttons (pager buttons) in the form |true| | |viewPagerButtons| This option enable or disable the appearing of the previous and next buttons (pager buttons) in the form |true| | ||
| + | |zIndex|The starting z-index for the dialog. If you will see the dialog form under another elements or dialogs you should use the parameter with some value higher as default value 950. In the most cases it should be the value higher as 1000 - the default value of jQuery UI dialog.|950| | ||
| + | |recreateForm|when set to true the form is recreated every time the dialog is activated with the new options from colModel (if they are changed) |false| | ||
| === Events === | === Events === | ||
| Line 325: | Line 339: | ||
| |closeOnEscape|When set to true the modal window can be closed with ESC key from the user.|false| | |closeOnEscape|When set to true the modal window can be closed with ESC key from the user.|false| | ||
| |ajaxDelOptions|This option allow to set global ajax settings for the form editiing when we delete the data to the server. Note that with this option is possible to overwrite all current ajax setting in the save request including the complete event.|empty object| | |ajaxDelOptions|This option allow to set global ajax settings for the form editiing when we delete the data to the server. Note that with this option is possible to overwrite all current ajax setting in the save request including the complete event.|empty object| | ||
| + | |zIndex|The starting z-index for the dialog. If you will see the dialog form under another elements or dialogs you should use the parameter with some value higher as default value 950. In the most cases it should be the value higher as 1000 - the default value of jQuery UI dialog.|950| | ||
| === Events === | === Events === | ||
| ^Event^Description^ | ^Event^Description^ | ||
| - | |afterComplete| This event fires immediately after all actions and events are completed and the row is inserted or updated in the grid. \\ afterComplete : function (response, postdata, formid) {...} \\ where \\ //response// is the data returned from the server (if any) \\ //postdata// an array, is the data sent to the server \\ //formid// is the id of the form | | + | |afterComplete| This event fires immediately after all actions and events are completed and the row is inserted or updated in the grid. \\ afterComplete : function (response, postdata, formid) {...} \\ where \\ //response// is the data returned from the server (if any) \\ //postdata// an array, is the data sent to the server \\ //formid// is the jQuery object of form id, you can use formid[0].id to get form id. | |
| |afterShowForm|fires after showing the form; receives as Parameter the id of the constructed form. \\ afterShowForm : finction (formid) {...} | | |afterShowForm|fires after showing the form; receives as Parameter the id of the constructed form. \\ afterShowForm : finction (formid) {...} | | ||
| |afterSubmit| fires after response has been received from server. Typically used to display status from server (e.g., the data is successfully deleted or the delete cancelled for server-side reasons). Receives as parameters the data returned from the request and an array of the posted values of type id=value1,value2. \\ When used this event should return array with the following items [success, message] \\ where \\ //success// is a boolean value if true the process continues, if false a error //message// appear and all other processing is stoped. \\ afterSubmit : function(response, postdata) \\ { \\ ... \\ return [succes,message] \\ } | | |afterSubmit| fires after response has been received from server. Typically used to display status from server (e.g., the data is successfully deleted or the delete cancelled for server-side reasons). Receives as parameters the data returned from the request and an array of the posted values of type id=value1,value2. \\ When used this event should return array with the following items [success, message] \\ where \\ //success// is a boolean value if true the process continues, if false a error //message// appear and all other processing is stoped. \\ afterSubmit : function(response, postdata) \\ { \\ ... \\ return [succes,message] \\ } | | ||
| Line 335: | Line 350: | ||
| |onclickSubmit|fires after the submit button is clicked and the postdata is constructed. Parameters passed to this event is a options array of the method. The event should return array of type {} which extends the postdata array. \\ onclickSubmit : function(params) { \\ ... \\ return {add_data} \\ }| | |onclickSubmit|fires after the submit button is clicked and the postdata is constructed. Parameters passed to this event is a options array of the method. The event should return array of type {} which extends the postdata array. \\ onclickSubmit : function(params) { \\ ... \\ return {add_data} \\ }| | ||
| |onClose|This event is called just before closing the form and when a close icon is clicked, a cancel button is clicked, ESC key is pressed or click on overlay (if jqModal is present). The event can return (optionally) true or false. If the return value is true the form is closed, if false the form does not close. If nothing is returned the form is closed| | |onClose|This event is called just before closing the form and when a close icon is clicked, a cancel button is clicked, ESC key is pressed or click on overlay (if jqModal is present). The event can return (optionally) true or false. If the return value is true the form is closed, if false the form does not close. If nothing is returned the form is closed| | ||
| + | |errorTextFormat|The event (can) fire when error occurs from the ajax call and can be used for better formatting of the error messages. To this event is passed response from the server. The event should return single message (not array), which then is displayed to the user.| | ||
| + | |serializeDelData|If set this event can serialize the data passed to the ajax request when we save a form data. The function should return the serialized data. This event can be used when a custom data should be passed to the server - e.g - JSON string, XML string and etc. To this event is passed the data which will be posted to the server.| | ||
| === What is posted to the server === | === What is posted to the server === | ||
| When we are in delete mode the data that is posted to the server is object {} that contain: | When we are in delete mode the data that is posted to the server is object {} that contain: | ||
| - | * the pair id:rowids where the roids can be a single value a value string separated with comma in case of multiple selection | + | * the pair id:rowids where the rowids can be a single value a value string separated with comma in case of multiple selection |
| * additionally we add a pair oper:del to indicate the delete mode | * additionally we add a pair oper:del to indicate the delete mode | ||
| * if the delData object is not empty we extend this data with the posted data | * if the delData object is not empty we extend this data with the posted data | ||
| Line 357: | Line 374: | ||
| * grid_id: the id of the parent grid | * grid_id: the id of the parent grid | ||
| * rowid: the id of the row | * rowid: the id of the row | ||
| - | * formid: is the id of the form | + | * formid: is the jQuery object of form id, you can use formid[0].id to get form id. |
| When called this method read the grid data with the id = rowid and places the data from the grid to the given form. if the form element has a name which is equal of those from colModel the value is placed to the form. | When called this method read the grid data with the id = rowid and places the data from the grid to the given form. if the form element has a name which is equal of those from colModel the value is placed to the form. | ||
| Line 375: | Line 392: | ||
| * grid_id: the id of the parent grid | * grid_id: the id of the parent grid | ||
| * rowid: the id of the row | * rowid: the id of the row | ||
| - | * formid: is the id of the form | + | * formid: is the jQuery object of form id, you can use formid[0].id to get form id. |
| * mode: determines the mode. Can be set or add. Default is set. If the mode is defined as set, the record in the grid is updated with the new values from the form. When the mode is defined as add the record is added to the grid. | * mode: determines the mode. Can be set or add. Default is set. If the mode is defined as set, the record in the grid is updated with the new values from the form. When the mode is defined as add the record is added to the grid. | ||
| * position: this parameter have sense only when the mode parameter is set to add. Can be first - the record is inserted as first row in the grid or last - the record is inserted as last row in the grid. | * position: this parameter have sense only when the mode parameter is set to add. Can be first - the record is inserted as first row in the grid or last - the record is inserted as last row in the grid. | ||
