Редактирование ячейки в jqGrid

Цикл статей «Документация jqGrid на русском».

Следующая статья — «Редактирование строки в jqGrid».
Предыдущая статья — «Свойство formoptions в jqGrid».

Редактирование ячейки даёт возможность пользователю менять содержимое одной ячейки в строке, затем разработчик имеет возможность обработать изменения в данных с помощью AJAX или в обработчике события редактирования ячейки (смотрите ниже).

Редактирование ячейки поддерживает навигацию с помощью клавиатуры и редактирование отдельных ячеек со следующим поведением:

• При клике на не редактируемую ячейку, ячейка выделяется, и можно использовать клавиши влево и вправо для перехода по ячейкам.
• При переходе на редактируемую ячейку, можно нажать клавишу Enter для начала редактирования. Значение в ячейке сохраняется при повторном нажатии Enter, при нажатии Tab или при клике на другую ячейку. При нажатии Esc ячейка не сохраняется. При редактировании ячейки клавиши со стрелками перемещают только внутри ячейки.
• При клике на редактируемую ячейку, мы сразу попадаем в режим редактирования.
• Ячейка не редактируется, если она имеет класс 'not-editable-cell' , вместо установки в colModel свойства editable.

Установка

Для того  чтобы использовать этот модуль, нужно пометить галочкой модули Cell editing и Common  при скачивании таблицы. Смотрите статью «Установка jqGrid».

Разработчики jQuery-плагинов могут использовать файл grid.celledit.js в каталоге src.

Свойства, события и методы используемые при редактировании ячейки перечислены ниже:

Свойства

Эти свойства являются специфичными для редактирования ячейки и должны устанавливаться в свойствах таблицы.

Свойство: cellEdit
Тип: boolean
Включает/выключает редактирование ячеек. Если это свойство установлено в true, то событие onSelectRow не может использоваться, и нависание курсора мышки (hover) отключено (при перемещении курсора мышки над строками).
По умолчанию: false

Свойство: cellsubmit
Тип: string
Определяет, куда сохранять содержимое ячейки. Может иметь одно из двух значений: 'remote' или 'clientArray'.
Если 'remote', то содержимое ячейки, если оно изменилось, сразу же сохраняется на сервер с помощью свойства cellurl и AJAX-запроса. Идентификатор строки и содержимое ячейки добавляются к url по умолчанию. Если свойство "mtype" установлено в "POST", то пары ключ-значение отправляются как параметры POST-запроса. Например, если мы сохраняем ячейку с именем mycell, то {id: rowid, mycell: cellvalue} добавляется к url.
Если свойство cellsubmit установлено в 'clientArray', то никаких AJAX-запросов не отправляется, и содержимое изменённой ячейки может быть получено с помощью метода getChangedCells или с помощью события.
По умолчанию: 'remote'

Свойство: cellurl
Тип: string
URL для сохранения содержимого ячейки. Это свойство следует устанавливать только при cellsubmit : 'remote'.
По умолчанию: null

Свойство: ajaxCellOptions
Тип: object
Это свойство позволяет задать глобальные настройки AJAX для отправки данных на сервер в режиме редактирования ячейки. Обратите внимание, что с помощью этого свойства можно переопределить все текущие настройки AJAX в запросе сохранения, включая событие complete.
По умолчанию: пустой объект

Примеры

При использовании 'remote' варианта, вы можете добавить эти линии в конфигурацию таблицы:

При использовании ‘clientArray’ в качестве свойства cellsubmit, только эти свойства важны:

События

Эти события относятся к редактированию ячейки и должны использоваться в свойствах таблицы.

Многие из этих событий используют следующие параметры:

• rowid — id строки
• cellname — имя ячейки (name из colModel)
• value — значение в ячейке
• iRow — индекс строки (не путать с rowid)
• iCol — индекс колонки

Событие: afterEditCell
Параметры: rowid, cellname, value, iRow, iCol
Применяется только к ячейкам, которые можно редактировать. Возникает после редактирования ячейки, то есть после вставки элемента в DOM.

Событие: afterRestoreCell
Тип: rowid, value, iRow, iCol
Применяется только к ячейкам, которые можно редактировать. Возникает после вызова метода restoreCell или нажатия пользователем клавиши Esc для отмены изменений.

Событие: afterSaveCell
Параметры: rowid, cellname, value, iRow, iCol
Применяется только к ячейкам, которые можно редактировать. Возникает после успешного сохранения ячейки. Идеальное место для изменения другого содержимого.

Событие: afterSubmitCell
Параметры: serverresponse, rowid, cellname, value, iRow, iCol
Применяется только к ячейкам, которые можно редактировать. Возникает после отправки данных на сервер. Должно вернуть массив вида [success(boolean),message]. Если возвращает [true,""], то всё ОК, и содержимое успешно сохранено. Если возвращает [false,"Сообщение об ошибке"], то возникает диалоговое окно с «Сообщение об ошибке» и содержимое не сохраняется. Параметр serverresponse — это ответ сервера. Вы должны использовать serverresponse.responseText для получения текстового сообщения с сервера.

Событие: beforeEditCell
Параметры: rowid, cellname, value, iRow, iCol
Применяется только к ячейкам, которые можно редактировать. Возникает перед редактированием ячейки.

Событие: beforeSaveCell
Параметры: rowid, cellname, value, iRow, iCol
Применяется только к ячейкам, которые можно редактировать. Это событие возникает перед проверкой значений. Это событие может вернуть новое значение, которое заменит отредактированное.
beforeSaveCell : function(rowid,celname,value,iRow,iCol) {if( some_condition ){ return "new value"; }}
Значение будет заменено на "new value".

Событие: beforeSubmitCell
Параметры: rowid, cellname, value, iRow, iCol
Применяется только к ячейкам, которые можно редактировать. Это событие возникает перед отправкой содержимого ячейки на сервер (только для cellsubmit : 'remote'). Может вернуть новый массив, который будет отправлен на сервер.
beforeSubmitCell : function(rowid,celname,value,iRow,iCol) {if( some_condition ) {return {name1:value1,name2:value2}}else{ return {} }}
Возвращённый массив будет добавлен к данным, отправляемым на cellurl.

Событие: errorCell
Параметры: serverresponse, status
Это событие возникает в случае ошибки сервера. Параметр servereresponse — это ответ сервера. Вы должны использовать serverresponse.responseText для получения текстового сообщения от сервера. Параметр status — это статус ошибки. Если обработчик события не установлен, то возникает диалоговое окно.

Событие: formatCell
Параметры: rowid, cellname, value, iRow, iCol
Применяется только к ячейкам, которые можно редактировать. Это событие позволяет форматировать содержимое ячейки перед редактированием и возвращает отформатированное значение.

Событие: onSelectCell
Параметры: rowid, celname, value, iRow, iCol
Применяется только к ячейкам, которые нельзя редактировать. Возникает после выделения ячейки.

Событие: serializeCellData
Параметры: postdata
Если установлено, то это событие может сериализовать данные, передаваемые в AJAX-запрос при сохранении ячейки. Функция должна вернуть сериализованные данные. Это событие можно использовать при необходимости отправки пользовательских данных на сервер в виде JSON-строки, XML-строки и других форматов. В это событие передаются данные, которые будут отправлены на сервер.

Порядок возникновения событий

В зависимости от свойства cellsubmit, установленного в 'remote' или 'clientArray', следующие события возникают в следующем порядке:

Свойство cellsumbit равно 'remote'

1. formatCell (rowid, cellname, value, iRow, iCol) — Вы можете поменять значение ячейки, которое будет использоваться в режиме редактирования
2. beforeEditCell (rowid, cellname, value, iRow, iCol) — Перед переходом ячейки в режим редактирования.
3. afterEditCell (rowid, cellname, value, iRow, iCol) — Событие возникает после создания элемента ввода.
4. beforeSaveCell (rowid, cellname, value, iRow, iCol) — Событие возникает перед сохранением ячейки, вы можете поменять значение, которое будет отправлено на сервер.
5. beforeSubmitCell (rowid, cellname, value, iRow, iCol) — Событие возникает перед отправкой на сервер, вы можете добавить дополнительные параметры к запросу, вернув массив.
6. afterSubmitCell (serverresponse, rowid, cellname, value, iRow, iCol) — Событие возникает только после отправки данных, вы можете вернуть сообщение об ошибке, чтобы отобразить диалоговое окно.
7. afterSaveCell (rowid, cellname, value, iRow, iCol) — Событие возникает после успешного сохранения значения ячейки.
8. errorCell (serverresponse, status) — Событие возникает при возникновении ошибки сервера (коды 403, 404, 500 и другие)
9. onSelectCell (rowid, celname, value, iRow, iCol) — Возникает, когда ячейка не редактируема.

Свойство cellsubmit равно 'clientArray'

1. formatCell (rowid, cellname, value, iRow, iCol) — Вы можете поменять значение ячейки, которое будет использоваться в режиме редактирования
2. beforeEditCell (rowid, cellname, value, iRow, iCol) — Перед переходом ячейки в режим редактирования.
3. afterEditCell (rowid, cellname, value, iRow, iCol) — Событие возникает после создания элемента ввода.
4. beforeSaveCell (rowid, cellname, value, iRow, iCol) — Событие возникает перед сохранением ячейки пользователем
5. beforeSubmitCell (rowid, cellname, value, iRow, iCol) — Здесь вы можете куда-нибудь сохранить значение.
6. afterSaveCell (rowid, cellname, value, iRow, iCol) — Возникает после успешного сохранения ячейки в beforeSubmitCell
7. onSelectCell (rowid, celname, value, iRow, iCol) — Возникает в случае, когда ячейка не редактируема.

Методы

Все методы ниже должны применяться к объекту jqGrid, и все они возвращают тот же объект.

Метод: editCell
Параметры: iRow, iCol, edit
Вызывает редактирование ячейки с индексом iRow(не путать с rowid) и индексом колонки iCol. Если edit установлено в false, то ячейка просто выделяется, но не редактируется. Если edit установлено в true, то ячейка выделяется и переходит в режим редактирования.

Метод: getChangedCells
Параметры: method
Возвращает массив изменённых (отредактированных) ячеек в зависимости от method (string, по умолчанию 'all' ). Если 'all', то метод возвращает все изменённые строки. Если 'dirty', то возвращает только изменённые ячейки с id строк.

Метод: restoreCell
Параметры: iRow, iCol
Восстанавливает значение изменённой ячейки с порядковым индексом строки iRow(не путать с rowid) и индексом колонки iCol.

Метод: saveCell
Параметры: iRow, iCol
Сохраняет ячейку с порядковым индексом строки iRow(не путать с rowid) и индексом колонки iCol.

Заметки

Как создаются элементы редактирования

При редактировании ячейки и создании элементов ввода используются следующие правила:

• Атрибут id элемента ввода создаётся как 'iRow_'+ name из colModel, где iRow — индекс строки (не rowid). Например, при редактировании ячейки с индексом 20 и именем 'myname' (из colModel), id становится равен 20_myname.
• Атрибут name элемента ввода равен name из colModel.

Что отправляется на сервер

При отправке данных на сервер отправляемый объект {} содержит:

• Пары «имя:значение», где имя — это name элемента ввода для ячейки
• Дополнительно добавляется пара «id:rowid», где rowid — это id строки.
• Если данные, возвращённые из события beforeSubmitCell, не пусты, то к отправляемым данным добавляются эти данные.

 

Цикл статей «Документация jqGrid на русском».

Следующая статья — «Редактирование строки в jqGrid».
Предыдущая статья — «Свойство formoptions в jqGrid».