App Builder - Deluge Scripting

Deluge or Data Enriched Language for the Universal Grid Environment as we call it, is an online scripting language integrated with Zoho Creator. It enables users to add logic to the application, making it more powerful and robust.

With Zoho Creator, you don't have to write code to build a simple data collection and viewing application like a Contacts list. But, for building a full-fledged application, with complex logic, for example, Library Manager, Recruitment application, Inventory Management etc., we provide an inbuilt scripting language called Deluge. For more information, refer Getting Started with Deluge Scripting.

Definitely not. Zoho Creator primarily addresses the needs of a large number of people who have a requirement for a web application but do not know to build it on their own. You just need to have a clear idea about the application you want to build and how you want it to be presented.

Yes, there is a limit on the number of statements that can be executed when a deluge action is invoked and also on the number of mails that can be sent per day. The usage limits for your account can be viewed by selecting the Account Settings -> Usage limit option.

No, the language keywords are not case insensitive but the form names and field names are case sensitive.

Yes, you can create a custom application from scratch by writing deluge script or import a deluge script file (.ds) file to create your application.

a. Write code from scratch
b. Import a Deluge Script (.ds file)

a. Write code from scratch

You can create a custom application from scratch by writing deluge scripts. The steps to create a sample feedback form and a view for viewing the submitted feedback is given below:

• Login to Zoho Creator and click on the Create New Application button.
• Select the Deluge Script icon on the left-side.
• Select the Write Script option.
• Write the script file with the required syntax or copy and paste an existing script. A sample script to create a simple Feedback Application is given below.
• Click the Create button to save the script. You will be directed to the newly created application.

Sample Deluge Script to create a simple "Feedback Application"

Copy/paste the below given snippet and save it to create an application called "Feedback Application". The application has one form "Send_Feedback" and a list view named "View feedback". You can now add data in the form and view it in the form of a list.

Application "Feedback Application" { page "Submit feedback" { form Send_Feedback { displayname = "Feedback" sender ( displayname = "From" type = email ) mail_subject ( displayname = "Subject" type = text ) category ( displayname = "Category" type = radiobuttons values = {General, Usability, Bug Report, Feature Request} ) comments ( displayname = "Comments" type = textarea ) } list "View feedback" { show all rows from Send_Feedback ( sender mail_subject category comments ) filters ( category ) } } }

Import a deluge script (.ds) directly

An entire application can be saved as a Deluge Script (see feedback.ds). The deluge script file can then be imported in Zoho Creator to create a new application. To know more about saving an application as .ds file, refer to Save / Backup an Application.

• Login to Zoho Creator and click on the Create New Application button.
• Select the Deluge Script icon on the left-side as shown below.
• Select the Import Script option.
• Just select the .ds file from your local file system using the browse button.
• And click the Create Now button to save the script. You will be directed to the newly created application.

 

You can save/backup your application as a .ds file. To do this,

• Select option displayed in the top-right corner, in access mode.
• The entire application will be saved as a .ds file at the desired location.
• You can create a copy of this application later, by importing this deluge script. Refer to Creating an application by Importing Deluge Script.

Form is the structure that contains the data. It can be referred to in two ways:

• display name

  It is the name by which a form will be referred through out in the GUI mode and also while a user is accessing the application in Live Mode. The display name should be given within double quotes.

   
• label name

  It is the actual name of the form. The label name of a form is unique within an application. Only the label name will be referred while scripting. A label name of a form should be alphanumeric and can contain underscore.

   

  form add_employee { displayname = "Add Employee" }

   

  where,

   

  add_employee     -  label name
  "Add Employee"   -  display name

   

Renaming a form is a safe operation and would not affect the data in anyway.

Rename display name

Renaming the display name of a form is very straight forward. Just change the display name in the form definition and save the script as shown below.

form add_employee { displayname = "Add Employee" "Add New Employee" }

Rename label name

The label name can be renamed by using the following syntax.

form add_employee as add_new_employee { displayname = "Add New Employee" }

Just replacing add_employee as add_new_employee is equivalent to deleting the form add_employee and creating a new form add_new_employee.

If no data is present, a form can be deleted by just removing the form definition from the text area and saving the page. If data is present, Zoho Creator will issue an error message that it is not possible to delete the form since data is present. To delete the form in such cases, you have to explicitly use the delete keyword, as shown below,

delete form add_employee

or just add a delete keyword before the form definition, as shown below.

delete form add_employee { displayname = "display name of the form" }

Form have display names and label names. You can have more than one form having the same display name in an application but the label name should be unique within an application.

The fields in a form define the individual properties of the specific kind of information. A form field is referred in two ways.

 

display name

 

It is the name by which a field will be referred through out in the GUI mode and also while a user is accessing the application in Live Mode. The display name should be given within double quotes.

 

label name

 

It is the actual name of the field. The label name of a field is unique within a form. Only the label name will be referred while scripting. A label name should be alphanumeric and can contain underscore.

 

Sample code:

 

form add_employee { displayname = "Add Employee" Name Age ( displayname = "Enter Age" type = number ) Date_Of_Birth ( displayname = "Date Of Birth" type = date ) Qualification ( displayname = "Educational Qualification" type = number ) }

 

where,

 

Name, Age, Qualification -  label names
"Enter Age:" , "Educational Qualification"  -  display names

 

If no type is specified, it is assumed to be of type text field.  E.g. Name

 

A field name should be alphanumeric and can contain underscore.

Refer Form field - Types to learn about the lists all the field types supported by Zoho creator, its description and data type.

Renaming a field is a safe operation and would not affect the data in anyway.

Renaming display name

Renaming the display name of a field is very straight forward. Just change the display name in the field definition and save the script.

form add_employee { displayname = "Add Employee" Name Age ( displayname = "Enter Age: " "Enter Employee Age: " type = number ) Date_Of_Birth ( displayname = "Date Of Birth" type = date ) Qualification ( displayname = "Enter Qualification" "Enter Educational Qualification" type = number ) }

Renaming label name

The label name can be renamed by using the following syntax.

form add_employee { displayname = "Add Employee" Name as EmpName Age as EmpAge ( displayname = "Enter Age:" type = number ) Date_Of_Birth ( displayname = "Date Of Birth" type = date ) Qualification as EmpQualification ( displayname = "Educational Qualification" type = number ) }

When you delete a field, all the data corresponding to the field also gets deleted and it cannot be recovered. If no data is present, a field can be deleted by just removing the field definition from the text area and saving the script. If data is present, Zoho Creator will issue a error message that it is not possible to delete the field with the data present. To delete the field in such cases, you have to explicitly use the delete keyword.

form add_employee
{
    displayname = "Add Employee"  
    Name    
    delete Age
    Date_Of_Birth
    (
      displayname = "Date Of Birth"
      type = date
    ) 
    Qualification
    (
        displayname =   "Enter Educational Qualification"
       type = number        
   )
}

or just add a delete keyword before the field definition and save the script

form add_employee
{
    displayname = "Add Employee"  
    Name     
    
    delete Age
    (
        displayname = "Enter Employee Age: "
        type = number        
    )
    Date_Of_Birth
    (
      displayname = "Date Of Birth"
      type = date
    )
    Qualification
    (
        displayname =   "Enter Educational Qualification"
        type = number        
   )
}

The script mode does not generate all the properties of a field. Only the properties modified by the user will be generated back and properties having the default values would not get generated. e.g. For a text filed, the maxchar property will not be generated if it has not been modified by the user.

Yes, you can create a hidden field by having the Hide this field to others box checked, as shown in the screen-shot below. Selecting this option will make this field accessible only to the author/owner of the application. To hide/show field based on a condition, refer the topic, Client side functions - Hide and Show for more information.

It is possible to do it in script mode using the Hide and Show deluge keywords. Refer the topic, Client side functions - Hide and Show for more information.

It is possible to do it in script mode by writing an on submit script for the form. The "on submit" script gets executed before the data is persisted. In the following code, the "on submit" script is written to find if there are rows that have the same name and data of birth and cancels the submit action if there are any rows matching the criteria.

Whenever a formula is modified, the formula filed value will be recalculated for all the rows. You will not be able to see the view until this recalculation is completed.

No, using one formula field in another formula is currently not supported.

Zoho Creator automatically stores the added time and modified time of each record submitted. Please refer FAQ - Views for more information. The Deluge date variable zoho.currenttime can also be used to record the current time. Here's how you can do it using the Deluge script:

 
Time_Stamp
  (
  type = formula
  value = zoho.currenttime
  )

In the UI mode, create a field with formula as it's type and just type zoho.currenttime as the value for the field in order to enable a timestamp.

You cannot import a picklist field from one form to another form. All other field types can be imported as a picklist in another form. For example, you can import a textfield in Form A as a picklist in Form B.

Yes, you can set a picklist to display only selected values. Refer Criteria in Import Picklist Data, for more information.

Yes, you can dynamically populate single picklist. Refer the topic, Add to picklist dynamically for more information.

Yes, you can do this by adding the following code in the on submit function. In the following code, if Amount is greater than 100 and if Address/City have no values, the entry will not be submitted.

  
on validate
  { 
  if ((input.Amount > 100) && ((input.Address == "") || (input.City 
  == ""))) 
  { 
  alert "enter Address/City"; 
  cancel submit; 
  } 
  }

You can manipulate a date field by using the '+' (to add) and '-' (to subtract) operators or by using the Deluge built-in Date functions. Refer Date Calculations and formula for more information and examples.

The validate script performs validation on the form data and is executed when a form is submitted. The data gets persisted only if the validation does not get cancelled. Refer, Form Actions -> Validate for more information and example.

The on success script performs an action after the form data is persisted in the database. Refer, Form Actions -> On success for more information and example.

On User Input and On Update are field actions performed on a specific field. These script will be invoked only when a particular field value changes or is updated. Refer, Field Actions  for more information and example.

Yes, you can conditionally fetch a collection of records and iterate over them. Consider the following simple use case. The CEO of a company wants to address all the new employees who have joined after certain date say, '10-jun-2006' . We have to mail all these new employees. Lets see how we can achieve this.

The form 'Employee' has the following fields: Name, Qualification, EmailID, TeamName, JoinDate

1) Fetch the data by applying filter.
emprecords = Employee [JoinDate > '10-Jul-2006'];

2) Now iterate over the records and send the mail. Here 'x' is the instance variable that will represent a single record in each iteration.

for each x in emprecords
  {
  sendmail
  (
  To : x.EmailID
  From : "yourmail@yourdomain.com"
  Subject : "Meeting"
  Message : "You are requested to attend the meeting at 6:pm tomorrow"
  )
  }

on success
  {
  sendmail
  (
  To : "xxx@adventnet.com"
  From : "support@zohocreator.com"
  Subject : "Welcome"
  Message : "Happy <br>development <br> with Zoho Creator / Deluge"
  )
  }

the message will be displayed like this:

Happy
development
with Zoho Creator / Deluge

For more tips on customizing email messages, refer the topic Tips & Tricks - Customizing Email Messages.

You can create a date field and set it with the current date, using the zoho.currentdate function inside on load action. The following deluge code will set the date field with the current date whenever the form is loaded.

form CurrentDate
  {
  date1
  (
  type = date
  ) 


on load
  {
  set date1 = zoho.currentdate;
  }
  }

Yes. There are two Zoho creator constants that you can use in scripting,

- zoho.loginuser
- zoho.loginuserid

It refers to the username and emailid of the currently logged in user. It would be very useful in scripting. Refer Deluge Variables, for more information.

To find the sum of more than one numeric field, you can create a new field of type "formula" as shown in the following sample code. Here, Maths, English and Science are the fields whose sum has to be calculated. The sum value will be displayed in the TotalMarks field.

TotalMarks

        (

        type = formula

        value = (Maths + English + Science)

Scheduling is currently not supported in Zoho Creator.

Variables are local to the "event section" in which they are defined/used. So if you define a variable (called TotalAmount) in the on Load section, you can also define it in the on User Input section of the Price Field of the Form ... and the values assigned in one section will not be available in the other(s).

Also, variables defined inside Functions are local to that instance of the Function only.

List View

In list view, the form data will get displayed as a table. The sample code given below creates a list view, where "View Employee" is the list name and "add_employee" is the form name. This will display all the records in the "add_employee" form in the form of a list.

list "View Employees"
{
      add_employee
}

The double quote is not needed if the view name has no special characters other than underscore. A view name need not be unique within an application.

Calendar view

In calendar view, the data will be presented as a calendar. This view is supported only if there is a date column.

calendar "View Employees"
{
      add_employee
}

Summary view

A summary view gives more information than a table/list view. But it is not possible to see any pattern in a summary view like in table view. This will display all the records in the "add_employee" form in the form of a summary.

summary "View Employees"
{
      add_employee
}

To specify criteria to display only selected records in a view, refer the topic, Criteria/Filters in Views.

To rename the "View Employees" as "View All Employees", just replace the view name in the script and save the entire script.

calendar "View Employees"  "View All Employees"
{
      show all rows from add_employee
      (
           Name
           Age
           Date_Of_Birth
           Qualification
      )
}

The data remains unaffected if a view is deleted.

A view has only a display name and more than one view can have the same display name in an application.