anoopmb
/
frappe


			
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Form Widget API &mdash; Documentation</title>
    <link rel="stylesheet" href="_static/sphinxdoc.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Documentation" href="index.html" />
    <link rel="up" title="4. Client Side API" href="client_side_widgets.html" />
    <link rel="next" title="Report Builder" href="report_builder.html" />
    <link rel="prev" title="Accessing Local Data" href="local_data.html" /> 
  </head>
  <body>
    <div style="background-color: #FFF; text-align: left; padding: 8px 0px"><img src="_static/banner300910.gif"></div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="report_builder.html" title="Report Builder"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="local_data.html" title="Accessing Local Data"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Documentation</a> &raquo;</li>
          <li><a href="client_side_widgets.html" accesskey="U">4. Client Side API</a> &raquo;</li> 
      </ul>
    </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference external" href="">Form Widget API</a><ul>
<li><a class="reference external" href="#scripting-forms">Scripting Forms</a></li>
<li><a class="reference external" href="#form-container-class">Form Container Class</a></li>
<li><a class="reference external" href="#form-class">Form Class</a></li>
<li><a class="reference external" href="#field-class">Field Class</a></li>
<li><a class="reference external" href="#grid-class">Grid Class</a></li>
<li><a class="reference external" href="#examples">Examples</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="local_data.html"
                                  title="previous chapter">Accessing Local Data</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="report_builder.html"
                                  title="next chapter">Report Builder</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/form_widget.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="form-widget-api">
<h1>Form Widget API<a class="headerlink" href="#form-widget-api" title="Permalink to this headline">¶</a></h1>
<div class="section" id="scripting-forms">
<h2>Scripting Forms<a class="headerlink" href="#scripting-forms" title="Permalink to this headline">¶</a></h2>
<p>Custom scripts can be written in forms by writing events in &#8220;Client Script&#8221; / &#8220;Client Script Core&#8221; in the
DocType. Some conventions for writing client scripts</p>
<ul class="simple">
<li>All functions should be written in the namespace <cite>cur_frm.cscript</cite>. This namespace is set aside
for customized client scripts</li>
<li><cite>cur_frm</cite> is the global variable that represents the Current Form that is open.</li>
</ul>
<p>See Examples</p>
</div>
<div class="section" id="form-container-class">
<h2>Form Container Class<a class="headerlink" href="#form-container-class" title="Permalink to this headline">¶</a></h2>
<dl class="data">
<dt id="_f">
<tt class="descname">_f</tt><a class="headerlink" href="#_f" title="Permalink to this definition">¶</a></dt>
<dd>Namespace for the Form Widget</dd></dl>

<dl class="data">
<dt id="_f.frm_con">
<tt class="descclassname">_f.</tt><tt class="descname">frm_con</tt><a class="headerlink" href="#_f.frm_con" title="Permalink to this definition">¶</a></dt>
<dd>Global FrmContainer. There is only one instance of the Form Container</dd></dl>

<dl class="function">
<dt id="_f.get_value">
<tt class="descclassname">_f.</tt><tt class="descname">get_value</tt><big>(</big><em>dt</em>, <em>dn</em>, <em>fn</em><big>)</big><a class="headerlink" href="#_f.get_value" title="Permalink to this definition">¶</a></dt>
<dd>Returns the value of the field <cite>fn</cite> from DocType <cite>dt</cite> and name <cite>dn</cite></dd></dl>

<dl class="function">
<dt>
<tt class="descclassname">_f.</tt><tt class="descname">get_value</tt><big>(</big><em>dt</em>, <em>dn</em>, <em>fn</em>, <em>v</em><big>)</big></dt>
<dd><p>Sets value <cite>v</cite> in the field <cite>fn</cite> of the give <cite>dt</cite> and <cite>dn</cite></p>
<ul class="simple">
<li>Will also set the record as __unsaved = 1</li>
<li>Will refresh the display so that the record is set as &#8220;Changes are not saved&#8221;</li>
</ul>
</dd></dl>

<dl class="class">
<dt id="_f.FrmContainer">
<em class="property">class </em><tt class="descclassname">_f.</tt><tt class="descname">FrmContainer</tt><a class="headerlink" href="#_f.FrmContainer" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<dl class="attribute">
<dt id="_f.FrmContainer.head">
<tt class="descname">head</tt><a class="headerlink" href="#_f.FrmContainer.head" title="Permalink to this definition">¶</a></dt>
<dd>Element representing the header of the form.</dd></dl>

<dl class="attribute">
<dt id="_f.FrmContainer.body">
<tt class="descname">body</tt><a class="headerlink" href="#_f.FrmContainer.body" title="Permalink to this definition">¶</a></dt>
<dd>Element represnting the page body</dd></dl>

<dl class="method">
<dt id="_f.FrmContainer.show_head">
<tt class="descname">show_head</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.FrmContainer.show_head" title="Permalink to this definition">¶</a></dt>
<dd>Show the head element</dd></dl>

<dl class="method">
<dt id="_f.FrmContainer.hide_head">
<tt class="descname">hide_head</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.FrmContainer.hide_head" title="Permalink to this definition">¶</a></dt>
<dd>Show the head element</dd></dl>

<dl class="method">
<dt id="_f.FrmContainer.add_frm">
<tt class="descname">add_frm</tt><big>(</big><em>doctype</em>, <em>onload</em>, <em>opt_name</em><big>)</big><a class="headerlink" href="#_f.FrmContainer.add_frm" title="Permalink to this definition">¶</a></dt>
<dd>Called internally by <a title="loaddoc" class="reference external" href="navigation.html#loaddoc"><tt class="xref docutils literal"><span class="pre">loaddoc()</span></tt></a>. Adds a new Form of type <cite>doctype</cite> in the FrmContainer.</dd></dl>

</dd></dl>

</div>
<div class="section" id="form-class">
<h2>Form Class<a class="headerlink" href="#form-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="_f.Frm">
<em class="property">class </em><tt class="descclassname">_f.</tt><tt class="descname">Frm</tt><a class="headerlink" href="#_f.Frm" title="Permalink to this definition">¶</a></dt>
<dd><p>Each doctype has a Frm object. When records are loaded on the Frm object, fields inside the form are
refreshed</p>
<dl class="attribute">
<dt id="_f.Frm.doctype">
<tt class="descname">doctype</tt><a class="headerlink" href="#_f.Frm.doctype" title="Permalink to this definition">¶</a></dt>
<dd><cite>doctype</cite> of the current form</dd></dl>

<dl class="attribute">
<dt id="_f.Frm.docname">
<tt class="descname">docname</tt><a class="headerlink" href="#_f.Frm.docname" title="Permalink to this definition">¶</a></dt>
<dd><cite>name</cite> of the current record</dd></dl>

<dl class="attribute">
<dt id="_f.Frm.fields">
<tt class="descname">fields</tt><a class="headerlink" href="#_f.Frm.fields" title="Permalink to this definition">¶</a></dt>
<dd>List of all <cite>Field</cite> objects in the form</dd></dl>

<dl class="attribute">
<dt id="_f.Frm.fields_dict">
<tt class="descname">fields_dict</tt><a class="headerlink" href="#_f.Frm.fields_dict" title="Permalink to this definition">¶</a></dt>
<dd>Dictionary of all <cite>Field</cite> objects in the form, identified by the <cite>fieldname</cite> or <cite>label</cite> (if no fieldname)
exists</dd></dl>

<dl class="attribute">
<dt id="_f.Frm.sections">
<tt class="descname">sections</tt><a class="headerlink" href="#_f.Frm.sections" title="Permalink to this definition">¶</a></dt>
<dd>List of all sections known by section id (<cite>sec_id</cite>). (Id because Sections may not have headings / labels)</dd></dl>

<dl class="attribute">
<dt id="_f.Frm.sections_by_label">
<tt class="descname">sections_by_label</tt><a class="headerlink" href="#_f.Frm.sections_by_label" title="Permalink to this definition">¶</a></dt>
<dd><p>Dictionary of all sections by label. This can be used to switch to a particular section. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">cur_frm</span><span class="o">.</span><span class="n">set_section</span><span class="p">(</span><span class="n">cur_frm</span><span class="o">.</span><span class="n">sections_by_label</span><span class="p">[</span><span class="s">&#39;More Details&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">sec_id</span><span class="p">);</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="_f.Frm.show">
<tt class="descname">show</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.show" title="Permalink to this definition">¶</a></dt>
<dd>Show the form</dd></dl>

<dl class="method">
<dt id="_f.Frm.hide">
<tt class="descname">hide</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.hide" title="Permalink to this definition">¶</a></dt>
<dd>Hide the form</dd></dl>

<dl class="method">
<dt id="_f.Frm.sec_section">
<tt class="descname">sec_section</tt><big>(</big><em>sec_id</em><big>)</big><a class="headerlink" href="#_f.Frm.sec_section" title="Permalink to this definition">¶</a></dt>
<dd>Show the section identified by</dd></dl>

<dl class="method">
<dt id="_f.Frm.refresh">
<tt class="descname">refresh</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.refresh" title="Permalink to this definition">¶</a></dt>
<dd><p>Refresh the current form. It will</p>
<ul class="simple">
<li>Check permission</li>
<li>If the record is changed, load the new record data</li>
<li>Run &#8216;refresh&#8217; method</li>
<li>Refresh all fields</li>
<li>Show the form</li>
</ul>
</dd></dl>

<dl class="method">
<dt id="_f.Frm.refresh_fields">
<tt class="descname">refresh_fields</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.refresh_fields" title="Permalink to this definition">¶</a></dt>
<dd>Will refresh all fields</dd></dl>

<dl class="method">
<dt id="_f.Frm.refresh_dependancy">
<tt class="descname">refresh_dependancy</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.refresh_dependancy" title="Permalink to this definition">¶</a></dt>
<dd>Will refresh hide / show based on &#8216;depends_on&#8217;</dd></dl>

<dl class="method">
<dt id="_f.Frm.save">
<tt class="descname">save</tt><big>(</big><em>save_action</em>, <em>call_back</em><big>)</big><a class="headerlink" href="#_f.Frm.save" title="Permalink to this definition">¶</a></dt>
<dd><p>Will save the current record (function called from the &#8220;Save&#8221; button)</p>
<p>save_action can be <cite>Save</cite>, <cite>Submit</cite>, <cite>Cancel</cite></p>
</dd></dl>

<dl class="method">
<dt id="_f.Frm.print_doc">
<tt class="descname">print_doc</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.print_doc" title="Permalink to this definition">¶</a></dt>
<dd>Show the <cite>Print</cite> dialog</dd></dl>

<dl class="method">
<dt id="_f.Frm.email_doc">
<tt class="descname">email_doc</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.email_doc" title="Permalink to this definition">¶</a></dt>
<dd>Shows the <cite>Email</cite> dialog</dd></dl>

<dl class="method">
<dt id="_f.Frm.copy_doc">
<tt class="descname">copy_doc</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.copy_doc" title="Permalink to this definition">¶</a></dt>
<dd>Copy the current record</dd></dl>

<dl class="method">
<dt id="_f.Frm.reload_doc">
<tt class="descname">reload_doc</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.reload_doc" title="Permalink to this definition">¶</a></dt>
<dd>Reload the current record from the server</dd></dl>

<dl class="method">
<dt id="_f.Frm.amend_doc">
<tt class="descname">amend_doc</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.amend_doc" title="Permalink to this definition">¶</a></dt>
<dd>Amend the current Cancelled record</dd></dl>

<dl class="method">
<dt id="_f.Frm.check_required">
<tt class="descname">check_required</tt><big>(</big><em>dt</em>, <em>dn</em><big>)</big><a class="headerlink" href="#_f.Frm.check_required" title="Permalink to this definition">¶</a></dt>
<dd>Checks whether all mandatory fields are filled</dd></dl>

<dl class="method">
<dt id="_f.Frm.runscript">
<tt class="descname">runscript</tt><big>(</big><em>scriptname</em>, <em>callingfield</em>, <em>onrefresh</em><big>)</big><a class="headerlink" href="#_f.Frm.runscript" title="Permalink to this definition">¶</a></dt>
<dd>Run a server-side script where Trigger is set as <cite>Server</cite>. The server method is identified by
<cite>scriptname</cite></dd></dl>

<dl class="method">
<dt id="_f.Frm.runclientscript">
<tt class="descname">runclientscript</tt><big>(</big><em>caller</em>, <em>cdt</em>, <em>cdn</em><big>)</big><a class="headerlink" href="#_f.Frm.runclientscript" title="Permalink to this definition">¶</a></dt>
<dd>Run a client script identified by the calling fieldname <cite>caller</cite>. <cite>cdt</cite> and <cite>cdn</cite> are the
id of the calling <cite>DocType and `name</cite></dd></dl>

<dl class="method">
<dt id="_f.Frm.set_tip">
<tt class="descname">set_tip</tt><big>(</big><em>txt</em><big>)</big><a class="headerlink" href="#_f.Frm.set_tip" title="Permalink to this definition">¶</a></dt>
<dd>Clear existing tips and set a new tip (contextual help) in the Form</dd></dl>

<dl class="method">
<dt id="_f.Frm.append_tip">
<tt class="descname">append_tip</tt><big>(</big><em>txt</em><big>)</big><a class="headerlink" href="#_f.Frm.append_tip" title="Permalink to this definition">¶</a></dt>
<dd>Add another tip to the existing tips</dd></dl>

<dl class="method">
<dt id="_f.Frm.clear_tip">
<tt class="descname">clear_tip</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Frm.clear_tip" title="Permalink to this definition">¶</a></dt>
<dd>Clear all tips</dd></dl>

</dd></dl>

</div>
<div class="section" id="field-class">
<h2>Field Class<a class="headerlink" href="#field-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="_f.Field">
<em class="property">class </em><tt class="descclassname">_f.</tt><tt class="descname">Field</tt><a class="headerlink" href="#_f.Field" title="Permalink to this definition">¶</a></dt>
<dd><dl class="attribute">
<dt id="_f.Field.df">
<tt class="descname">df</tt><a class="headerlink" href="#_f.Field.df" title="Permalink to this definition">¶</a></dt>
<dd><p>the <cite>df</cite> attribute represents the Field data. Standard Field properties are</p>
<ul class="simple">
<li>fieldname</li>
<li>fieldtype</li>
<li>options</li>
<li>permlevel</li>
<li>description</li>
<li>reqd</li>
<li>hidden</li>
<li>search_index</li>
</ul>
<p>Example:</p>
<div class="highlight-python"><pre>var field = cur_frm.fields_dict['first_name']
field.df.reqd = 1;
field.refresh();</pre>
</div>
</dd></dl>

<dl class="attribute">
<dt id="_f.Field.wrapper">
<tt class="descname">wrapper</tt><a class="headerlink" href="#_f.Field.wrapper" title="Permalink to this definition">¶</a></dt>
<dd>Wrapping DIV Element</dd></dl>

<dl class="attribute">
<dt id="_f.Field.label_area">
<tt class="descname">label_area</tt><a class="headerlink" href="#_f.Field.label_area" title="Permalink to this definition">¶</a></dt>
<dd>HTML Element where the label of the field is printed</dd></dl>

<dl class="attribute">
<dt id="_f.Field.disp_area">
<tt class="descname">disp_area</tt><a class="headerlink" href="#_f.Field.disp_area" title="Permalink to this definition">¶</a></dt>
<dd>HTML Element where the value of the field is printed in &#8220;Read&#8221; mode</dd></dl>

<dl class="attribute">
<dt id="_f.Field.input_area">
<tt class="descname">input_area</tt><a class="headerlink" href="#_f.Field.input_area" title="Permalink to this definition">¶</a></dt>
<dd>HTML Element where the widget is placed in &#8220;Write&#8221; mode</dd></dl>

<dl class="attribute">
<dt id="_f.Field.comment_area">
<tt class="descname">comment_area</tt><a class="headerlink" href="#_f.Field.comment_area" title="Permalink to this definition">¶</a></dt>
<dd>HTML Element where the comment (description) is printed</dd></dl>

<dl class="attribute">
<dt id="_f.Field.parent_section">
<tt class="descname">parent_section</tt><a class="headerlink" href="#_f.Field.parent_section" title="Permalink to this definition">¶</a></dt>
<dd>If the <cite>section_style</cite> of the doctype is <cite>Tray</cite> or <cite>Tabbed</cite>, then this represents the SectionBreak
object in which this field is. This is used to switch to the section in case of an error.</dd></dl>

<dl class="method">
<dt id="_f.Field.get_status">
<tt class="descname">get_status</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Field.get_status" title="Permalink to this definition">¶</a></dt>
<dd>Retuns the whether the field has permission to <cite>Read</cite>, <cite>Write</cite> or <cite>None</cite></dd></dl>

<dl class="method">
<dt id="_f.Field.set">
<tt class="descname">set</tt><big>(</big><em>v</em><big>)</big><a class="headerlink" href="#_f.Field.set" title="Permalink to this definition">¶</a></dt>
<dd>Sets a value to the field. Value is set in <cite>locals</cite> and the widget</dd></dl>

<dl class="method">
<dt id="_f.Field.run_trigger">
<tt class="descname">run_trigger</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.Field.run_trigger" title="Permalink to this definition">¶</a></dt>
<dd>Runs any client / server triggers. Called <cite>onchange</cite></dd></dl>

</dd></dl>

</div>
<div class="section" id="grid-class">
<h2>Grid Class<a class="headerlink" href="#grid-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="_f.FormGrid">
<em class="property">class </em><tt class="descclassname">_f.</tt><tt class="descname">FormGrid</tt><a class="headerlink" href="#_f.FormGrid" title="Permalink to this definition">¶</a></dt>
<dd><p>The FromGrid Class inherits from the Grid class. The Grid class was designed to be a generic INPUT.</p>
<ul class="simple">
<li>The metadata of the grid is defined by the <cite>DocType</cite> of the <cite>Table</cite> field.</li>
<li>Each column of the grid represents a field.</li>
<li>Each row of the grid represents a record</li>
</ul>
<p><strong>Grid Types</strong></p>
<p>There are two type of Grids:</p>
<ol class="arabic simple">
<li>Standard: Where fields can be edited within the cell</li>
<li>Simple: Where fields are edited in a popup Dialog box. A Simple Grid can be created by setting the
<cite>default</cite> property of the Table field to &#8220;Simple&#8221;</li>
</ol>
<p>When the user clicks on an editable Grid cell, it adds an <cite>Field</cite> object of that particular column to the
cell so that the user can edit the values inside the cell. This <cite>Field</cite> object is known as the <cite>template</cite>
The <cite>template</cite> can be accessed by the <cite>get_field</cite> method</p>
<dl class="method">
<dt id="_f.FormGrid.get_field">
<tt class="descname">get_field</tt><big>(</big><em>fieldname</em><big>)</big><a class="headerlink" href="#_f.FormGrid.get_field" title="Permalink to this definition">¶</a></dt>
<dd>Returns the <cite>template</cite> (<cite>Field</cite> object) identified by <cite>fieldname</cite></dd></dl>

<dl class="method">
<dt id="_f.FormGrid.refresh">
<tt class="descname">refresh</tt><big>(</big><big>)</big><a class="headerlink" href="#_f.FormGrid.refresh" title="Permalink to this definition">¶</a></dt>
<dd>Refresh all data in the Grid</dd></dl>

</dd></dl>

</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="report_builder.html" title="Report Builder"
             >next</a> |</li>
        <li class="right" >
          <a href="local_data.html" title="Accessing Local Data"
             >previous</a> |</li>
        <li><a href="index.html">Documentation</a> &raquo;</li>
          <li><a href="client_side_widgets.html" >4. Client Side API</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2010, Rushabh Mehta.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
    </div>
  </body>
</html>