274 lines
6.8 KiB
Text
274 lines
6.8 KiB
Text
Form Widget API
|
|
===============
|
|
|
|
Scripting Forms
|
|
----------------
|
|
|
|
Custom scripts can be written in forms by writing events in "Client Script" / "Client Script Core" in the
|
|
DocType. Some conventions for writing client scripts
|
|
|
|
* All functions should be written in the namespace `cur_frm.cscript`. This namespace is set aside
|
|
for customized client scripts
|
|
* `cur_frm` is the global variable that represents the Current Form that is open.
|
|
|
|
See Examples
|
|
|
|
Form Container Class
|
|
--------------------
|
|
|
|
.. data:: _f
|
|
|
|
Namespace for the Form Widget
|
|
|
|
.. data:: _f.frm_con
|
|
|
|
Global FrmContainer. There is only one instance of the Form Container
|
|
|
|
.. function:: _f.get_value(dt, dn, fn)
|
|
|
|
Returns the value of the field `fn` from DocType `dt` and name `dn`
|
|
|
|
.. function:: _f.get_value(dt, dn, fn, v)
|
|
|
|
Sets value `v` in the field `fn` of the give `dt` and `dn`
|
|
|
|
* Will also set the record as __unsaved = 1
|
|
* Will refresh the display so that the record is set as "Changes are not saved"
|
|
|
|
.. class:: _f.FrmContainer
|
|
|
|
This is the object that contains all Forms. The Form Container contains the page header and Form toolbar
|
|
that is refreshed whenever a new record is shown.
|
|
|
|
.. attribute:: head
|
|
|
|
Element representing the header of the form.
|
|
|
|
.. attribute:: body
|
|
|
|
Element represnting the page body
|
|
|
|
.. method:: show_head()
|
|
|
|
Show the head element
|
|
|
|
.. method:: hide_head()
|
|
|
|
Show the head element
|
|
|
|
.. method:: add_frm(doctype, onload, opt_name)
|
|
|
|
Called internally by :func:`loaddoc`. Adds a new Form of type `doctype` in the FrmContainer.
|
|
|
|
Form Class
|
|
----------
|
|
|
|
.. class:: _f.Frm
|
|
|
|
Each doctype has a Frm object. When records are loaded on the Frm object, fields inside the form are
|
|
refreshed
|
|
|
|
.. attribute:: doctype
|
|
|
|
`doctype` of the current form
|
|
|
|
.. attribute:: docname
|
|
|
|
`name` of the current record
|
|
|
|
.. attribute:: fields
|
|
|
|
List of all `Field` objects in the form
|
|
|
|
.. attribute:: fields_dict
|
|
|
|
Dictionary of all `Field` objects in the form, identified by the `fieldname` or `label` (if no fieldname)
|
|
exists
|
|
|
|
.. attribute:: sections
|
|
|
|
List of all sections known by section id (`sec_id`). (Id because Sections may not have headings / labels)
|
|
|
|
.. attribute:: sections_by_label
|
|
|
|
Dictionary of all sections by label. This can be used to switch to a particular section. Example::
|
|
|
|
cur_frm.set_section(cur_frm.sections_by_label['More Details'].sec_id);
|
|
|
|
.. method:: show()
|
|
|
|
Show the form
|
|
|
|
.. method:: hide()
|
|
|
|
Hide the form
|
|
|
|
.. method:: sec_section(sec_id)
|
|
|
|
Show the section identified by
|
|
|
|
.. method:: refresh()
|
|
|
|
Refresh the current form. It will
|
|
|
|
* Check permission
|
|
* If the record is changed, load the new record data
|
|
* Run 'refresh' method
|
|
* Refresh all fields
|
|
* Show the form
|
|
|
|
.. method:: refresh_fields()
|
|
|
|
Will refresh all fields
|
|
|
|
.. method:: refresh_dependancy()
|
|
|
|
Will refresh hide / show based on 'depends_on'
|
|
|
|
.. method:: save(save_action, call_back)
|
|
|
|
Will save the current record (function called from the "Save" button)
|
|
|
|
save_action can be `Save`, `Submit`, `Cancel`
|
|
|
|
.. method:: print_doc()
|
|
|
|
Show the `Print` dialog
|
|
|
|
.. method:: email_doc()
|
|
|
|
Shows the `Email` dialog
|
|
|
|
.. method:: copy_doc()
|
|
|
|
Copy the current record
|
|
|
|
.. method:: reload_doc()
|
|
|
|
Reload the current record from the server
|
|
|
|
.. method:: amend_doc()
|
|
|
|
Amend the current Cancelled record
|
|
|
|
.. method:: check_required(dt, dn)
|
|
|
|
Checks whether all mandatory fields are filled
|
|
|
|
.. method:: runscript(scriptname, callingfield, onrefresh)
|
|
|
|
Run a server-side script where Trigger is set as `Server`. The server method is identified by
|
|
`scriptname`
|
|
|
|
.. method:: runclientscript(caller, cdt, cdn)
|
|
|
|
Run a client script identified by the calling fieldname `caller`. `cdt` and `cdn` are the
|
|
id of the calling `DocType and `name`
|
|
|
|
.. method:: set_tip(txt)
|
|
|
|
Clear existing tips and set a new tip (contextual help) in the Form
|
|
|
|
.. method:: append_tip(txt)
|
|
|
|
Add another tip to the existing tips
|
|
|
|
.. method:: clear_tip()
|
|
|
|
Clear all tips
|
|
|
|
Field Class
|
|
-----------
|
|
|
|
.. class:: _f.Field()
|
|
|
|
.. attribute:: df
|
|
|
|
the `df` attribute represents the Field data. Standard Field properties are
|
|
|
|
* fieldname
|
|
* fieldtype
|
|
* options
|
|
* permlevel
|
|
* description
|
|
* reqd
|
|
* hidden
|
|
* search_index
|
|
|
|
Example::
|
|
|
|
var field = cur_frm.fields_dict['first_name']
|
|
field.df.reqd = 1;
|
|
field.refresh();
|
|
|
|
.. attribute:: wrapper
|
|
|
|
Wrapping DIV Element
|
|
|
|
.. attribute:: label_area
|
|
|
|
HTML Element where the label of the field is printed
|
|
|
|
.. attribute:: disp_area
|
|
|
|
HTML Element where the value of the field is printed in "Read" mode
|
|
|
|
.. attribute:: input_area
|
|
|
|
HTML Element where the widget is placed in "Write" mode
|
|
|
|
.. attribute:: comment_area
|
|
|
|
HTML Element where the comment (description) is printed
|
|
|
|
.. attribute:: parent_section
|
|
|
|
If the `section_style` of the doctype is `Tray` or `Tabbed`, then this represents the SectionBreak
|
|
object in which this field is. This is used to switch to the section in case of an error.
|
|
|
|
.. method:: get_status()
|
|
|
|
Retuns the whether the field has permission to `Read`, `Write` or `None`
|
|
|
|
.. method:: set(v)
|
|
|
|
Sets a value to the field. Value is set in `locals` and the widget
|
|
|
|
.. method:: run_trigger()
|
|
|
|
Runs any client / server triggers. Called `onchange`
|
|
|
|
Grid Class
|
|
----------
|
|
|
|
.. class:: _f.FormGrid()
|
|
|
|
The FromGrid Class inherits from the Grid class. The Grid class was designed to be a generic INPUT.
|
|
|
|
* The metadata of the grid is defined by the `DocType` of the `Table` field.
|
|
* Each column of the grid represents a field.
|
|
* Each row of the grid represents a record
|
|
|
|
**Grid Types**
|
|
|
|
There are two type of Grids:
|
|
|
|
#. Standard: Where fields can be edited within the cell
|
|
#. Simple: Where fields are edited in a popup Dialog box. A Simple Grid can be created by setting the
|
|
`default` property of the Table field to "Simple"
|
|
|
|
When the user clicks on an editable Grid cell, it adds an `Field` object of that particular column to the
|
|
cell so that the user can edit the values inside the cell. This `Field` object is known as the `template`
|
|
The `template` can be accessed by the `get_field` method
|
|
|
|
.. method:: get_field(fieldname)
|
|
|
|
Returns the `template` (`Field` object) identified by `fieldname`
|
|
|
|
.. method:: refresh()
|
|
|
|
Refresh all data in the Grid
|
|
|
|
Examples
|
|
--------
|
|
|