REST

Blog
REST
Monday, September 18, 2017PrintSubscribe
Executing Requests with the Client API

All apps created with Code On Time app generator contain a single client-side API used for all server-side operations, including Select, Insert, Update, Delete, Report, Batch Edit, etc. One significant advantage of using a centralized API is that any style of user interface is able to access the same API – this has allowed the co-development of Classic and Touch UI.

Another major advantage in the client-side API is that developers are able to extend their apps with custom behavior utilizing the same data access routines – any access control rules, data controller customizations, and security restrictions will also equally apply to these custom requests.

To access the client API from custom JavaScript, simply call the method $app.execute(options) with the required parameters set on the options object. See a list of available options parameters below.

Property Description Default Value
controller The controller to direct the request to. (required)
view The view of the controller to use. grid1
done
success
Callback function when the request was send and received successfully. First argument contains the results. List of records can be found under the result property equal to the name of the controller.
fail
error
Callback function when the request failed.
command The name of the command to execute. “Select”
argument The argument of the command to execute.
lastCommand The last command name.
lastCommandArgument The last command argument.
pageSize The number of records to return in a single page. 100
pageIndex The page number to return. 0
filter An array of field filter objects. Each object must have 3 properties:
- “field” specifies the field name
- “operation” specifies the filter operation to perform
- “value” specifies the value of the filter. For operations with two operands (such as “between”), specify an array of two values.
values An array of field value objects. Each object can have the following properties:
- “name” specifies the name of the field matching the one defined in the controller.
- “value” specifies the current value of the field.
- “newValue” specifies the new value.
- “modified” specifies that the new value will be used in any Insert or Update expressions. Setting “newValue” will set “modified” to true by default.
selectedValues An array of strings that contain the primary keys of the selected records. Used for batch update.
tags Specify a list of tags that can be processed on the server.
requiresData Specifies if data should be returned to the client. true
requiresAggregates Specifies if aggregates defined on the view should be returned with the request. false
fieldFilter Specifies a list of fields to include in the response for each record. Not setting this value will return all fields.
format Specifies if field values should be formatted when the results are returned. true
includeRawResponse Specifies if the result should include the raw response in the rawResponse property. false

The simplest way to test your queries is to use the Developer Tools Console, available in most modern browsers.

First, browse to your running site in your favorite browser. Press “F12” to bring up Developer Tools. Switch to the Console tab.

Using the Console tab of Developer Tools to test the $app.execute() API.

You may now begin typing in $app.execute() requests in the console. Note the use of console.log(result), which will print the JavaScript object to the console when the request returns.

The following examples will use the online Northwind sample.

Select

The simplest use case for using the API is to request a page of data. See the following example below on how to fetch the first 10 records from the Orders table where the field “ShipCountry” is equal to “USA”.

$app.execute({
    controller: 'Orders',
    pageSize: 10,
    filter: [
        { field: 'ShipCountry', operator: '=', value: 'USA' }
    ],
    done: function (result) {
        console.log(result);
    }
})

The result shown in the Developer Tools Console.

Selecting 10 orders with a filter.

Insert

In order to insert records to a particular table, the request must specify the “Insert” command and a list of field values. This list is represented by the values property. Each field value object contains a field name. Values that will be assigned to the new record are stored in the field value’s newValue property. The primary key of the table is added as a field value object with the property value equal to null in order for the response to return the new primary key of the inserted record.

$app.execute({
    controller: 'Orders',
    command: 'Insert',
    values: [
        { name: 'OrderID', value: null },
        { name: 'ShipCity', newValue: 'San Diego' },
        { name: 'ShipCountry', newValue: 'USA' }
    ],
    done: function (result) {
        console.log(result);
    }
})

See the results below.

Inserting a record using the $app.execute() API.

Refreshing the view in the browser window will reveal the new record.

The new record is displayed in the grid.

Update

When performing operations on an existing record, either the primary key or an array of selected values must be specified. New field values must be specified in the newValue property.

$app.execute({
    controller: 'Orders',
    command: 'Update',
    values: [
        { name: 'OrderID', value: 11083 },
        { name: 'OrderDate', newValue: new Date() }
    ],
    done: function (result) {
        console.log(result);
    }
})

The result is shown below.

Updating an order via the $app.execute() API.

The result can be seen by refreshing the list of orders.

The updated field value is visible by refreshing the page.

Delete

Delete operations must specify the primary key in the values array.

$app.execute({
    controller: 'Orders',
    command: 'Delete',
    values: [
        { name: 'OrderID', value: 11079 }
    ],
    done: function (result) {
        console.log(result);
    }
})

See result below.

Deleting a record.

The rowsAffected property will be equal to “1” if the record was successfully deleted.

Saturday, March 28, 2015PrintSubscribe
Easy Setup of Content Management System, Page+JSON Compression, Auto-Rotation of JPEGs

Code On Time release 8.5.1.0 is a collection of several enhancements to the major release 8.5.0.0 that has introduces various enterprise components in the application framework including integrated Content Management System, Dynamic Access Control List, Dynamic Controller Customization, and Workflow Register.

CMS Setup

Now you can setup an integrated Content Management System for you app with a click of a button.

  1. Navigate to Project Settings in the app generator and choose Database Connection option.
  2. Click on the […] button on the right-hand side of Connection String box.
  3. Scroll to Content Management System (CMS) section and click Add button.
  4. Click OK and save settings of the connection string.
  5. Click Finish and Refresh your project.

image

CMS becomes a part of your application. Login as admin and select Site Content option in the menu.

Here is the site content management screen in the app with Touch UI.

image

This is the same page displayed with Desktop UI.

image

Add an image to the content database.

image

Now the jelly fish is available on your website when accessed with a custom URL composed of the path and file name:

~/images/jelly-fish.jpg

image

You can place static content, images, sitemaps, access control rules, pages, data controller XML files, data controller customization instructions, and just about anything else you like directly into CMS. Learn to use integrated content management system now!

The content is stored in the single database table called SiteContent, SITE_CONTENT, or site_content if the CMS was installed as explained above. Application generator will create a standard data controller, which you can customize as needed. Feel free to add new columns to the site content table.

Note that the installation of CMS in this release is supported for Microsoft SQL Server, Oracle, and MySQL. Let us know if you would like to see other databases to have a simplified setup of CMS.

Page and Script Compression

Non-hosted projects now  perform runtime compression of pages and JSON responses in SPA apps. Apps implemented with “*.aspx” page model are performing compression on page output only at this time. This new capability is available in apps with Desktop and Touch user interfaces.

JPEG Auto Rotation

Images captured on mobile devices of iOS family are preserving device orientation information in the EXIF metadata of each photo in JPEF format. Uploaded photos will display incorrectly if rotation information is not taken into account. Blob downloader of generated apps will auto-rotate and flip the photos in JPEG format by taking into account orientation of the camera recorded in the image.

Other Enhancements

Other enhancements include:

  • Duplicate data fields are not created during data controller customization if an attempt is made to create an existing data field.
  • Dynamic Access Control List correctly processes Tags property of data views.
  • Workflow Register is now available in all product editions including free edition.
  • Advanced Search form in Touch UI correctly processes dates.
  • Advanced Search form  correctly handles “include” comparison option and will not raise an exception.
  • SPA applications will correctly process HTML tags specified in About property of a page.
  • Client library parses integer values with radix of 10 to ensure correct parsing with earlier versions of JavaScript engine.
  • Application Framework activates Gregorian calendar for th-TH culture.
  • CMS: Added processing of "empty" relative path in ReadSiteContent method.
  • Pivot API: added "hideblank" keyword that will remove the "blank" value from that row or column.
Friday, October 18, 2013PrintSubscribe
Universal Mobile/Desktop Client, Mobile Factory, Active Directory, Synchronization Service

Code On Time release 8.0.0.0 introduces support for Universal Mobile/Desktop Client. The unique architecture of generated apps allows re-interpreting of the application user interface presentation. The original “Desktop” client library now has a “Mobile” counterpart. Apps created with Unlimited edition will automatically detect a mobile device and render an alternative touch-friendly GUI for the app.

The mobile client library is based on popular jQuery Mobile framework. The current implementation of the library allows read-only access to data. We are finalizing the editing capabilities and expect to have them rolled out by the middle of November 2013. Sorting, filtering, and advanced search will be included in the mobile client in the next couple of weeks.

The new project Mobile Factory allows creating apps with “mobile-only” user interface. This project is available without restrictions in Premium and Unlimited editions. Free and Standard editions allow creating Mobile Factory projects with up to ten tables.

Membership and authentication options have been extended to include Active Directory. Application users can sign-in with the standard fly-over login window or custom login. User identity is authenticated by Active Directory server. User roles are derived from Active Directory groups assigned to the user. This feature is available in Unlimited edition only.

New cloud-based Synchronization Service allows automated synchronization of Project Designer logs to simplify team development. Single users will also benefit from a cloud history of designer logs. Online portal allows management of design revision. The new service is designed to complement existing source control systems, such as Team Foundation Server. The synchronization service is offered at no charge. Organizations interested in hosting their own designer synchronization service may request pricing here.

Unlimited edition now includes SaaS (Software as a Service) support with full user authentication. Code On Time apps can be integrated into external web sites while running side-by-side. Examples will be available in the near future.  We expect to use this model to support the newest version of Microsoft SharePoint and other similar products in the future releases.

This release includes the following features, enhancements, and bug fixes.

  • Web App Factory, Azure Factory, and Web Site Factory support “_mobile” URL parameter. The “true” value will enable mobile GUI on desktop computers. Value “false” can be used to disable mobile GUI on mobile devices when needed. Empty value will delete the cookie.
     
  • Mobile Client displays “Call” context option for the fields tagged as mobile-action-call. Data fields with “Phone” in the name are tagged automatically.
     
  • Mobile Client supports tags mobile-item-heading, mobile-item-desc, mobile-item-label, mobile-item-count, mobile-item-aside, mobile-item-thumb and mobile-item-para to enable easy formatting of grid views presented on mobile devices. By default, the Mobile Client will automatically choose the fields to display based on their Show In Summary flag. Presence of any tag on a data field will override the default behavior.
     
  • New “Device” property of pages supports “Auto”, “Desktop”, and “Mobile” options. The default value is “Auto”. “Desktop” pages are not accessible in the menu or address bar from mobile clients and vice versa. This allows implementing pages that work only on mobile or only on desktop devices.
     
  • The current implementation of Mobile Client is based on jQuery Mobile 1.4 beta.
     
  • Class ApplicationServices implement EnableMobileClient static Boolean property that allows disabling Mobile Client UI. Create a partial class ApplicationServices in a dedicated class file, override method RegisterServices and assign “false” to he EnableMobileClient to disabled mobile client.
     
  • Standard TableOfContents and Welcome user controls include markup of mobile content.
     
  • New JavaScript and CSS versioning system is available in Web App Factory, Web Site Factory, and Azure Factory. File “DataAquarium.Version.xml” is included in the root of the projects. The file stores the application version number. The number starts at zero. It is incremented every time the application is published from the app generator. JavaScript and CSS references are enhanced with a suffix to force seamless re-loading on the client machines after deployment. For example, the suffix of a 7th revision of an app may look as follows in the actual combined script reference:
     
    ”../appservices/combined-8.0.0.7.en-us.js?_mobile”
     
    The  first part “8.0.0” reflects the version of the app generator. The last number “7” if the application revision.
     
  • Data controller service will not create data controller requests if a client is not authenticated by the app.
     
  • App services are exempt from "Authenticated user" requirement imposed by Controller.CreateConfiguration method.
     
  • Desktop Client correctly selects a record in a grid view if the record was created or changed in a modal form.
     
  • Active Directory authentication and groups are supports in Web App Factory, Web Site Factory, and Azure Factory apps created with Unlimited edition.
     
  • Combined script is integrated in Web App Factory, Web Site Factory, and Azure Factory in apps created with Unlimited edition. A single compressed script is returned to the client browser. This improves the download speed of pages. The combined script name accounts for user interface culture, “mobile” flag, and version.
      
  • App generators now supports Azure SDK 2.1
     
  • REST serialization processor correctly serializes Guid values.
     
  • User Controls are correctly opened in Visual Studio when selected in Project Designer.
     
  • Membership bar will detect and clear anchors from the URL when reloading a page.
     
  • Missing “type” attribute on “command” node of a data controller will not cause a runtime error.
     
  • Project Designer will clear contents of "empty" nodes when an empty text is assigned to an element. This eliminates the need to create unnecessary revisions in source control systems.
     
  • Solutions files are not re-generated anymore to allow modifying the solutions contents.
     
  • All projects types will now correctly reload if the source code has been opened in Visual Studio at the time of code generation.
     
  • BLOB Adapter implementation has been enhanced to work better with MySQL databases.
     
  • EASE auditing will correctly work with read-only fields.
     
  • Multiple business rule firing has been corrected. Caused by business rule blacklisting by ID instead of name.
     
  • Method MembershipProvider ResetPassword in custom membership providers has been fixed to support hashed passwordAnswer.
     
  • jQuery 10.2 and jQuery UI 1.10.3, are integrated in the client library.
  • New Watermark property is now available for data fields.
     
  • Fixed Oracle 4.5 projects not correctly hooking up ODP assembly. 
      
  • Desktop Client makes use of jQuery when dealing with various dimension calculations. We are abandoning Ajax Control Toolkit in the future releases.