Table of Contents
< All Topics
Print

Custom Script View

Gnosis Views with gs and gsAction format are custom Item Type Static methods and Web API for your Gnosis Application.

Views in gs format can be called with the GET Web method, while Views in gsAction format can be called with either the POST or PUT Web methods.

Views in gshtml format can be called with the GET Web method.

The Gnosis Identities set as Permissions on the View control access to the Web APIs.

$Params Variable

The query string parameters and the JSON Web request body passed to gs, gshtml, and gsAction Views are available in the Gnosis Script View as the special $Params object.

For example, the parameter name is passed in the query string for the CustomWebAPI endpoint:

/v2/View/Demo.CustomWebAPI?name=tom

In the CustomWebAPI View, the query string name parameter is available on the $Params object:

if (not $Params?.name) Error("No name provided.")

Response object

The response object is how to return special keys.

$Cookies

The $Cookies key is how to set and remove cookies. It can be used in both GET and POST Views.

$Commit

The $Commit key annotates the transaction message appearing in the Item History if the Item Type has history enabled. It is only valid for Action Views.

$AffectedItems

The $AffectedItems key holds the affected items.

To explicitly set affected items, use the AffectItem() function.

For POST

$AffectedItems = true

GET Web API Views

Gnosis gs and gshtml Views are read-only (GET) Web API endpoints.

For example, the following Custom gshtml View will return an HTML page of the items the user created.

<div style="padding:1em;">
	<h2>Hello, {$User}</h2>
	
	<h1>My {@.Entity.Plural}</h1>
	
	<a href=/#/{@}/Explore/{@.Entity}.Items>Explore Items View</a>
	
	{:
	var baseUrl = $ServerUrl + "/#/{@.Entity}/Explore/item:";
	
	FindItems(@.Entity)
		.IncludeDerived()
		.Filter(i => i.CreatedBy == $User)
		.Map(i => (
			var url = baseUrl + i.Id;
			"<div style='padding:0 1em; margin:1em; border:solid 1px; border-radius:6px; box-shadow: rgba(149, 157, 165, 0.2) 0px 8px 24px;'>
				<h3><a href={url}>{i.Name}</a> ({i.$ItemType} Type)</h3>
				<h4>Created On: {i.CreatedOn.ToString('MMMM, d, yyyy h:mm tt')}</h4>
				<p>{i.Description}</p>
			</div>";
		))
	:}
</div>

Test GET Web API

You can test the gs and gshtml Views using the Gnosis Scripting Console. Call the View function using the Render() method.

View("Demo.MyItems").Render()
$.Demo.MyItems()

You can use the browser to test a Gnosis gs or gshtml View using the Gnosis v1 Web API:

/api/View/Content/{SolutionName}.{View.Name}
/api/View/Content/{SolutionName}.{ItemTypeName}.{View.Name}

For example, to get the MyItems View in the Demo Solution:

/api/View/Content/Demo.MyItems

Alternatively, to get a Gnosis gs or gshtml View with v2 Web API:

/v2/View/{SolutionName}.{View.Name}

For example, the same Solution View could be called with the shorter v2 API URL:

/v2/View/Demo.MyItems

POST/PUT Web API Views

Gnosis gsAction Views are transactional (PUT, POST) Web API endpoints that can modify Items.

The following is a sample Custom gsAction View named CreateMyItem for the Entity Item Type in the Demo Solution that will create an Entity Item returning an HTML page.

/**
 * Creates an Entity.
 * @group Demo
 * @param Name: string // The Entity Name, defaults to "Random Name {Random(1, 100)}".
 * @param Description: string // The Entity Description, defaults to Lorem Ipsum text.
 * @result HTML
 * @example View("Demo.Entity.CreateItem", missing, true).Render()
 */
 
// If no Name is passed in, generate a random name.
var name = $Params?.Name
	? Name // Name is short for $Params.Name
	: "Random Name {Random(1, 100)}";

// If no Desctiontion is passed in, set Lorem Ipsum text.
var desc = $Params?.Description 
	? Description  // Description is short for $Params.Description
	: "Lorem Ipsum gestas eget aliquet praesent cursus in habitasse platea";

// Create a new Item and catch if there is an error.
var item = Safe(CreateItem($ItemType, {
	Name = name,
	Description = desc
	// Catch and return a clone of the Error.
	// Returning the error will rethrow the error.
}), e => { Error = e });

// Within triple double quotes we can
// intermix Gnosis Script with HTML markup.
"""
<h1>Hello, {$User}</h1>

{:
	// If there is an Error show the message.
	if (item?.Error) (
		"<div>{item.Error.Message}</div>"
	) else (
		var created = item.CreatedOn.ToString('MMM dd, yyyy');
		"<div>{item?.Name} was created on {created}</div>"
	)
:}
""";

Test POST Web API

You can test the gsAction View using the Gnosis Scripting Console. To execute the gsAction View, use the View() function, passing the parameters in the Render() method. The third parameter must be true, indicating this is a gsAction View.

View("Demo.Entity.CreateMyItem", missing, true).Render({
	"Name": "Testing " + Random(1, 100),
	"Description": "Created by View function"
})

Call the Action View with the false argument will return null if there is no View by the path provided.

ActionView("Demo.Entity.CreateMyItem", false)?.Render({
	"Name": "Testing " + Random(1, 100),
	"Description": "Created by View function"
})

To call the View as a static Item Type method:

$.Demo.Entity.CreateMyItem({
	"Name": "Testing " + Random(1, 100),
	"Description": "Created by View function"
})

You can use the Ajax() function in the Gnosis Scripting Console to test POST/PUT Web API gsAction Views.

// Get Authorization header with the OAuth access token.
OAuth(username, password) => (
	var url = $ServerUrl + "/v2/OAuth";
	var cred = {
	  "username": username,
	  "password": password,
	  "grant_type": "password"};
	var oauth = Ajax(url, cred, "POST");
	
	// The object is the last statement so it is the return value.
	{ "Authorization": "Bearer " + oauth.access_token }
);

// Credential variables
var user = "email";
var pwd = "password";

// The gsAction Solution View path.
var gsAction = "Demo.Entity.CreateItem";

// POST the gsAction using Gnosis v1 API.
Ajax.Call({
	url = $ServerUrl + "/api/View/Action/" + gsAction,
	params = {
		"Name": "Testing " + Random(1, 100),
		"Description": "Created by {gsAction} Web v1 API"
	},
	method = "POST",
	user = user,
	password = pwd
});

// POST the gsAction using Gnosis v2 API.
Ajax(
	$ServerUrl + "/v2/View/" + gsAction,
	{
		"Description": "Created by {gsAction} Web v2 API"
	},
	"POST",
	missing, missing, missing,
	OAuth(user, pwd));

Documenting Gnosis Script Views

Custom Web API Views can be documented using the Gnosis Script Documentation comment directives. For more details, see Documenting Gnosis Scripts.