Documentation - Using Code Fields & SnappyForge Internal API

While SnappyForge was designed to allow quite a lot of freedom in designing and developing applications, we realize that sometimes there are some tasks that cannot be replicated without good old code. The following sections were developed to extend SnappyForge's base functionality. This section will be added to and revised in the near future, so be on the lookout!

SnappyForge supports a few different ways you can create calculations and execute code on our server. This feature is designed for more advanced users who understand code, but anyone can copy and paste the snippets below and get instant results!

Currently, we support Code in two places - Buttons and Fields. Each of those has both a C# and VB option, so you can use whichever you are more comfortable with.

Code Fields

What is It? Special Fields which give you the ability to run calculations and do other special things. On the fly calculations can be inserted into Form Modes (except Add Mode) and in List Mode.

Where to Find It? When you're in Form Edit mode, you will see two fields that you can drag into your Form. They are called CodeFormula and RowCodeFormula.

How Can I Use It? After dragging a CodeFormula or RowCodeFormula to your form, look on the control to find the Edit Code button. (). This will pop up a window with two Text Area Fields, one for C# and the other for Visual Basic. They're called "C# Code" and "VB Code".

Note that there is a difference in CodeFormula and RowCodeFormula - CodeFormula by default is not in the list view, but CAN be set to display there. RowCodeFormula is for code which executes but is NOT visible to the end-user, and is to execute for each row in the List View.

Button Code

What is It? Any button can be given some code to execute on the server. When the button is clicked, the code will be executed. This feature is more advanced than the Code Fields, and will likely only be used for very special things, like making Internal API calls to quickly make changes to your data.

Where to Find It? When on a Form you own, hover over This Form (, then click on Edit Buttons (). When you Add or Edit a button, at the bottom of that Form you will see two Text Area Fields - "C# Code" and "VB Code".

How Can I Use It? After creating a button, just put the code you want to run on button click into the appropriate field. Note that these Code options are Server Side code, and get compiled and executed on our servers. This is different than the Button's OnClientClick field, which lets you run Javascript code when the button is clicked. Also note that the code is run AFTER your data is saved to the database.

Code and SnappyTags

Just as with a Field's ParameterName, all Code fields can use the SnappyTags feature to insert a value from your database (or other special value) into your code. For example, if you have an Field named "My Number" and want to run a calculation on it via a CodeFormula field, you can enter the following into the Code Text Area:

##My Number## * 2

Here we took the value of "My Number" and multiplied it by 2. See the documentation section for SnappyTags to see some more of how this can be used.

Note that we are simply returning a value here - so no other code is necessary. SnappyForge will know to add the semicolon (for C#) and the appropriate return keyword for a small snippet like this.

Using SnappyForge Internal API

We've added some really neat things you can do with the Code feature, and we hope you can make use of them. Please get in touch with us if there's some additional functionality you'd like to see us add in the near future!

SwapRow

Use:

bool SwapRow(string _sortColumnName, string _idColumnName, string _rowid, bool _up = true, string _fk = "", string _fkval = "")

Inputs

_sortColumnName - string the Database Column name that you are using to sort your list. Must be an integer.

_idColumnName - string the name of the Database Column that is your Form's primary key. Default is "ID".

_rowid - string the index of the row we are clicking on and want to swap with the row above or below.

_up - bool Default value is true, to move the row upward according to the SortColumn. False will move the row downward.

_fk - string Default value is empty string. If the Form you want to sort is a SubForm, you'll need to include the Foreign Key field for Sorting to work properly.

_fk - string Default value is empty string. If the Form you want to sort is a SubForm, you'll need to include the Foreign Key value for Sorting to work properly.

Outputs

A boolean value to indicate whether the swap was successful.

Example

API.SwapRow("#@SortOrder@#", "ID", "##rowindex##", true);

API.SwapRow("#@SortOrder@#", "ID", "##rowindex##", false);

API.SwapRow("#@SortOrder@#", "ID", "##rowindex##", true, "#@FK@#", "##FK##");

API.SwapRow("#@SortOrder@#", "ID", "##rowindex##", false, "#@FK@#", "##FK##");
            

For the code above, you would use either one line or the other! The first line looks for the row with an ID of ##rowindex##, and tries to move it up according to #@SortOrder@# (Remember that tags with #@...@# will try to find the Column Name of that Field!). FormID will probably be depricated soon!

GetICSFile

Use:

bool GetICSFile(string _dateStart, string _dateEnd, string _summary, string _location, string _description, string _filename = "")

Inputs

_dateStart - string the Start Date of your meeting or event.

_dateEnd - string the End Date of your meeting or event.

_summary - string the Summary (Title) of your event.

_location - string the Location of your event.

_description - string the Description of your event.

_filename - string Default value is empty string. (Which will generate CalendarItem.ics) You do not need to specify the ".ics" extension.

Outputs

An ICS File which gets downloaded to the user's computer for their calendar.

Example

API.GetICSFile("##Requested On##", "##Requested On##", "##Summary##", "##Location##", "##Description##", "MyICS")
            

This Code would generate an ICS file for the user based on the row that is clicked. You could place the button in the grid or within an Edit or View Mode for the user to generate the reminders they want.

DateDiff

Use:

string DateDiff(string _utcdate, string _totimezone, bool _includeseconds = true)

Inputs

_utcdate - string the datetime you want to comapre with the present time. Note that we are using UTC throughout all of SnappyForge and will convert to your time zone.

_totimezone - string the Standard name of the Time Zone your form uses. Could also be the user's timezone if your Form uses the default Global time zone setting. We recommend "##timezone##" (include the quotes, because the value of ##timezone## is a string!).

_includeseconds - bool indicates whether or not to also include seconds in the output calculation.

Outputs

A string represntation of the difference of the _utcdate and now. E.G. "1 day, 3 hours, 28 minutes ago" or "3 days, 47 seconds from now".

Example

API.DateDiff("##My Date##", "##timezone##", true)
            

Will compare the date from the field "My Date" with the current time. Uses the ##timezone## tag to pull the form's timezone (if it is set), and the user's timezone (if the form is using Global time).

DateDiffNumber

Use:

string DateDiffNumber(string _utcdate, string _totimezone, bool _includeseconds = true)

Inputs

_utcdate - string the datetime you want to comapre with the present time. Note that we are using UTC throughout all of SnappyForge and will convert to your time zone.

_totimezone - string the Standard name of the Time Zone your form uses. Could also be the user's timezone if your Form uses the default Global time zone setting. We recommend "##timezone##" (include the quotes, because the value of ##timezone## is a string!).

_includeseconds - bool indicates whether or not to also include seconds in the output calculation.

Outputs

A numberic represntation of the difference of the _utcdate and now. E.G. "-1.14444" or "3.0000543".

Example

API.DateDiffNumber("##My Date##", "##timezone##", true)
            

Will compare the date from the field "My Date" with the current time. Uses the ##timezone## tag to pull the form's timezone (if it is set), and the user's timezone (if the form is using Global time). Use this if you want to use the calculation in a formula, such as knowing which of your tasks are overdue by 7 or more days. You can also use this for Automation Conditions to determine if an email should be sent out!

SetRowColor

Use:

string SetRowColor(string _rowid, string _bgcolor, string _color, int _animatetime)

Inputs

_rowid - string the html id of the row to color.

_bgcolor - string the html color to be used for the background. Can be standard html strings or hex ('red' or '#FF0000'). We recommend http://colorpicker.com to pick colors!

_color - bool the html color to be used for the text. Can be standard html strings or hex.

_animatetime - int number of milliseconds to animate the transition. See below for a fun use of this!

Outputs

A piece of Javascript code to colorize the row.

Example

string output = "";
switch ("##Status##") {
    case "Not Started":
        output += API.SetRowColor("##row##", "#CCCCCC", "#000000", 1000 * ##rowindex##);
        break;
    case "Behind Schedule":
        output += API.SetRowColor("##row##", "#FFC2C2", "#000000", 1000 * ##rowindex##);
        break;
    case "In Progress":
        output += API.SetRowColor("##row##", "#FFFFC2", "#000000", 1000 * ##rowindex##);
        break;
    case "Complete":
        output += API.SetRowColor("##row##", "#C2FFCA", "#000000", 1000 * ##rowindex##);
        break;
}
            

The code above takes the value of the "Status" field, and colors each row accordingly. Note that ##row## is passed in for _rowid, and 1000 * ##rowindex## is passed in for _animatetime. For each successive row, the animation time will increase by one second (1000 ms * row's index). This produces a nice fade in effect!

HideButton

Use:

string HideButton(string _buttonid)

Inputs

_buttonid - string the ID of the button you want to hide. You'll likely have to know the rendered button's ID and then replace the last part of it with ##rowid## .

Outputs

A piece of Javascript code to hide the button.

Example

string output = "";
if (##rownum## == 1) {
    output += API.HideButton("26Button8_##rowid##");
} 
if (##rownum## == ##rowcount##) {
	output += API.HideButton("26Button9_##rowid##");
} 
return (output == "" ? "<script></script>" : output);
            

This code checks the current row number (##rownum##) and compares it to 1, and the last row in the grid (##rowcount##). If it's the first row, we hide one button. If it's the second row, we hide the other button. Both buttons are set up as Grid buttons in the List View for form #26 (and they are 8 and 9, respectively) - you will have to create buttons and tweak this code a bit to make it work on your form! Also note the ID of the row is also placed into the button id (##rowid##). For the last line, we check if there is any script output from the API calls - if there is not we return an empty script tag "<script></script>" to ensure the RowCodeFormula stays hidden!

Some Additional Notes about Code

Some code can be combined when you are using a RowCodeFormula field. For example, we could have a task list which is ordered by a Field named SortOrder, and also contains a Status Field.

string output = "";
switch ("##Status##") {
    case "Not Started":
        output += API.SetRowColor("##row##", "#CCCCCC", "#000000", 1000 * ##rowindex##);
        break;
    case "Behind Schedule":
        output += API.SetRowColor("##row##", "#FFC2C2", "#000000", 1000 * ##rowindex##);
        break;
    case "In Progress":
        output += API.SetRowColor("##row##", "#FFFFC2", "#000000", 1000 * ##rowindex##);
        break;
    case "Complete":
        output += API.SetRowColor("##row##", "#C2FFCA", "#000000", 1000 * ##rowindex##);
        break;
}
if (##rownum## == 1) {
    output += API.HideButton("26Button8_##rowid##");
} 
if (##rownum## == ##rowcount##) {
    output += API.HideButton("26Button9_##rowid##");
} 
return (output == "" ? "" : output);
            

You can see how we append the resulting script returned by API.SetRowColor and then add API.HideButton to hide the Move Up or Move Down buttons for the first and last items in the list!