DaST API Reference

This page contains the detailed class reference for back-end Scope Tree API and for client JavaScript API.


1. Scope Tree API

The complete DaST Scope Tree API public class diagram is below:

FullClassDiagram-2

Fig. 1: Scope Tree API class diagram

1.1. ScopeController Class

ScopeController is an abstract class that all our application controller classes are inherited from. It has functions that we override to setup the controller. It also exposes methods to point the specific scope in the tree.

ProvideTemplate()

When overridden in a derived controller class, tells the system what template to use.

abstract public string ProvideTemplate()
Return Value string Plain text content of the desired template.

You simply need to read your template content and return it as string. Templates can be located anywhere: local or remote files, database, HTTP, etc. – there is no limitation.

See usage example in Controller Class section of tutorial.

InitializeModel(ControllerModelBuilder)

When overridden in a derived controller class, binds all handlers and nested controllers to the scope tree.

abstract public void InitializeModel(ControllerModelBuilder model)
Parameters ControllerModelBuilder model An instance of model builder that you use to do all your controller setup.

An instance of the model builder must be used to do the following:

  • Associate scopes with binding handlers.
  • Associate actions with action handlers.
  • Attach nested controllers to scopes.

This method is like an ASP.NET boilerplate code created for you behind the scenes by Forms Designer. There is no such designer tool for DaST yet, so we need to accomplish this part overriding the InitializeModel() and setting everything up manually.

See usage example in Controller Class section of tutorial.

CurrPath(params object[])

Points at the specified scope in the rendered scope tree using scope path starting from the current scope.

protected ScopeFacade CurrPath(params object[] segments)
Parameters params object[] segments Scope path definition as alternating list of non-negative integers for axes and strings for scope names. If path starts from negative integer –N, then pointer goes N steps back in the tree. This parameter is optional. If no path specified, then pointer stays at the current scope.
Return Value ScopeFacade This object is used to manipulate the pointed data scope.

This function is for rendered scope tree and is intended to be used from within action and binding handlers during rendering process. Scope path (see Scope Paths in tutorial)  passed as parameter is relative to the current scope i.e. the scope whose binding handler is currently executed.

Note that pointing at the scope you cannot go beyond the current controller. If there is a nested controller and you try to access its scopes, you’ll get an error. However, you can access the root scope that nested controller is attached to in order to set parameters that later can be picked up in the nested controller.

See usage example in Controller Class section of tutorial.

CtrlPath(params object[])

Points at the specified scope in the rendered scope tree using scope path starting from the root scope of the current controller.

protected ScopeFacade CtrlPath(params object[] segments)

Everything is the same as for CurrPath(), but instead of the current scope, scope path is relative to the root scope of the current controller i.e. the scope that the controller is attached to or NULL scope for page top-level controller.

See usage example in Controller Class section of tutorial.

1.2. ControllerModelBuilder Class

Parameter of this type is passed to the overridden InitializeModel() function in your derived controller class. So all functions described below are used to setup controller and template relationship from within InitializeModel() method. 

Select(params object[])

Points at the specified scope in the initial scope tree using scope path starting from the root scope of the current controller.

public ControllerModelBuilder Select(params object[] segments)
Parameters params object[] segments Scope path definition as list of strings for scope names. This parameter is optional. If no path specified, then pointer stays at the controller’s root scope.
Return Value ControllerModelBuilder Model builder object pointing at the selected scope. Returning instance of the same object allows for compact chained call syntax.

Because we’re working with initial scope tree, all repeating axes are 0 and to specify a path we only need scope names. The return values is the same object allowing us to use compact chained call syntax for all setup functions.

See usage example in Controller Class section of tutorial.

SetDataBind(DataBindHandler)

When chained after Select(), associates binding handler with the pointed scope.

public void SetDataBind(DataBindHandler handler)
Parameters DataBindHandler handler A callback that will be invoked when rendering traversal procedure hits the pointed data scope.

If function is called without Select(), then binding handler is set for the root scope of the controller.

See usage example in Controller Class section of tutorial.

SetController(ScopeController)

When chained after Select(), attaches nested controller to the pointed scope.

public void SetController(ScopeController controller)
Parameters ScopeController controller Instance of the nested controller you wish to attach.

In the template, the scope that you attach the controller to, must be empty without any content. You can attach different controllers to one scope depending on some parameters. This vaguely resembles building server controls programmatically in the standard ASP.NET.

See usage example in Setting Up Child Controller section of tutorial.

HandleAction(string, ActionHandler)

This function associates action handler with action name.

public void HandleAction(string actionName, ActionHandler handler)
Parameters string actionName Name of the action you wish to handle. Name format should be alphanumeric with dashes and underscores.
  ActionHandler handler Function that needs to be invoked to process the event with specified name.

Unlike data binding handlers, action is associated with the controller, not with a separate scope. Within the controller, action is identified by name. When you handle action coming from client side, there is no need to chain function call after Select(), because ControllerModelBuilder instance points at the controller’s root scope from the beginning. But if you want to handle action raised in a nested conroller, you must use Select() first to point the scope which the nested controller is attached to. Before using HandleAction() method on the nested controller, the controller has to be attached using SetController() method.

See usage example in Handling Actions section of tutorial.

1.3. ScopeFacade Class

Object of this type is returned by CurrPath() and CtrlPath() functions and allows you to manipulate the scope pointed within the rendered scope tree. This is the primary class you’ll be dealing with inside your action and binding handlers. To call any of the class members, the specific scope has to be pointed first using ether CurrPath() or CtrlPath() functions which return the instance of ScopeFacade class.

ClientID property

Gets the ID of the selected scope container element how it will look in the resulting web page.

public string ClientID { get; }

Client ID of the scope is built using scope path (see Scope Paths in tutorial) and resembles it in structure. Since every scope of the rendered scope tree is uniquely identified by its path, the id of the scope element in the resulting page is also unique.

See usage example in Controller Class section of tutorial.

Attributes property

Get attributes of the selected scope container element defined in the template.

public Dictionary<string, string> Attributes { get; }

The property returns all attributes as name/value collection except for dast:scope attribute which is ignored. Being able to access scope container attributes we can pass static parameters from template to controller individually for each scope.

RenderType property

Gets or sets the way the selected scope is rendered.

public ScopeRenderType RenderType { get; set; }

The property is of type ScopeRenderType whose values are Normal, Empty, and None:

  • Normal – scope is rendered normally. This is a default value.
  • Empty – only scope container is rendered, but all scope content is not rendered.
  • None – scope container as well as content are not rendered. Note that this value might be deprecated in the future versions.

Note that if scope is rendered with value None, then partial AJAX update on it will not work, because container is absent. Avoid using None and use Empty instead.

Params property

Gets ParamsFacade object for the selected scope allowing to get and set intermediate scope parameters.

public ParamsFacade Params { get; }

Intermediate scope parameters are not saved across postbacks and persist only during single rendering traversal. This is a primary facility of passing parameters between the scopes during rendering process.

See usage example in Controller Class section of tutorial.

StoredParams property

Gets ParamsFacade object for the selected scope allowing to get and set permanent scope parameters.

public ParamsFacade StoredParams { get; }

Permanent scope parameters are persisted across postbacks. Parameters saved with scopes on one postback can be accessed on the subsequent postbacks. Since StoredParams need to persist, they are saved in JSON serialized form (almost similar to ASP.NET __VIEWSTATE) which adds overhead to the client-server traffic. If value can not be JSON serialized, error will be thrown.

This property is created just for your convenience, but consider passing action parameters together with using Params property instead. If your application is properly designed, there should be no need for saving the parameters.

See usage example in Binding Handlers section of tutorial.

Replace(string, object)

Binds real value to the placeholder for the selected scope.

public void Replace(string placeholder, object replacement)
Parameters string placeholder String placeholder specified in the template.
  object replacement Value that placeholder will be replaced with.

This function is the most basic way to bring data value to a placeholder. Physical replacement of the placeholder occurs when scope is rendered which takes place immediately after the corresponding binding handler is executed.

See usage example in Controller Class section of tutorial.

Replace(string, object, string)

Same as basic Replace(), but takes replacement value from specified object property.

public void Replace(string placeholder, object obj, string propertyName)
Parameters string placeholder String placeholder specified in the template.
  object obj Any object containing the desired property value.
  string propertyName Name of the property in obj from which the replacement value will be taken.

AreaConditional(string, bool)

Shows or hides an HTML fragment marked by special comment elements.

public void AreaConditional(string area, bool flag)
Parameters string area Area name to identify fragment wrapping comments.
  bool flag if true, area is displayed, otherwise, area is hidden.

For example, if area is “my-area” and flag is FALSE, the system will look for the fragment surrounded by <!--showfrom:my-area--> and <!--showstop:my-area--> and will remove this fragment from the resulting page.

This function is a convenient way to toggle a fragment of HTML markup. It makes sense to use conditionals instead of nested scopes for certain smaller tasks. Surrounding the conditional area by comments you have to make sure there are no nested scopes in this area.

See usage example in Conditional Areas section of tutorial.

AreaRepeater()

Reserved for future version.

Repeat()

Repeats the content of the selected scope.

public void Repeat()

If the function is called N times, then the content of the scope inside the container is duplicated N times. Use RepeatStart() function to reset repeating axis counter before multiple scope repeats.

See usage example in Controller Class section of tutorial.

RepeatStart()

Resets repeating axis counter on the selected scope to 0.

public void RepeatStart()

This function can be called before multiple calls to Repeat() method. By default every scope is repeated once i.e. 1 repeating axis that results in initial scope tree. So, before repeating the scope, axis counter has to be reset to start from 0 instead of 1. If counter stays 0, the scope will have no content displayed. This behavior is what we used to for standard ASP.NET and MVC repeaters.

See usage example in Controller Class section of tutorial.

Refresh()

Tells the system to refresh the selected scope using partial update.

public void Refresh()

Can only be called from within the action handler. This function tells the system to use partial update and refresh the pointed scope in AJAX manner.

See usage example in Partial Updates section of tutorial.

RaiseAction(string, object)

Raises action on the current controller which can be handled in the parent controller.

public void RaiseAction(string actionName, object actionArg)
Parameters string actionName String name identifying action
  object actionArg Generic argument passed to action handler in the parent controller.

Controller actions allow controllers to talk to each other. Action handler syntax in parent controller is absolutely uniform with syntax for regular client actions. Unlike client actions that require the argument to be JSON-serializable, controller actions allow any generic objects.

See usage example in Raising Child Controller Actions section of tutorial.

InvokeAction(string, object)

Invokes action on the selected nested controller.

public void InvokeAction(string actionName, object actionArg)
Parameters string actionName String name identifying action
  object actionArg Generic argument passed to action handler in the parent controller.

Same as RaiseAction(), but in the opposite direction. While RaiseAction() sends event to the parent controller, InvokeAction() sends event to the nested controlled. Action handler syntax in nested controller is also uniform with client action handlers.

See usage example in Raising Parent Controller Actions section of tutorial.

MessageClient(string, object)

Sends client side the message which can be handled using JavaScript callback.

public void MessageClient(string msgID, object dataItem)
Parameters string msgID String name identifying the message
  object dataItem Generic argument passed to the client side message handler. The object has to be JSON-serializable.

This function is a server side of the DaST duplex messaging mechanism which complements actions mechanism to allow consistent and intuitive event-based client-server both-way communication.

In other words, this is an event in the opposite server-to-client direction. Together with client action mechanism, this feature provides real duplex messaging between the client and the server.

See usage example in Duplex Messaging section of tutorial.

1.4. ParamsFacade Class

This class provides  a simple name/value parameters storage. The instance of this class is returned by Params and StoredParams properties of the ScopeFacade class. See usage examples in Controller Class section of tutorial.

Set(string, object)

Sets the parameter with specified name on the selected scope.

public void Set(string name, object value)
Parameters string name Parameter name.
  object value Parameter value.

Set(object, string, string)

Sets the parameter with specified name taking value from the specified object and property.

public void Set(object obj, string propertyName, string paramName)
Parameters object obj Object containing the desired value.
  string propertyName Name of the property from which the value is retrieved.
  string paramName Parameter name.

Set(object, string[], string[])

Sets multiple parameters with specified names taking values from the specified object and properties.

public void Set(object obj, string[] propertyNames, string[] paramNames)
Parameters object obj Object containing the desired values.
  string[] propertyNames Names of the properties from which the values are retrieved
  string[] paramNames Parameter names (order is the same as for property names)

Init(string, object)

Sets the parameter with specified name on the selected scope if this parameter is not set yet.

public void Init(string name, object value)
Parameters string name Parameter name.
  object value Parameter value.

Has(string)

Indicates if parameter is already set.

public bool Has(string name)
Parameters string name Parameter name.

Get<T>(string)

Gets the parameter by name as object of specified type.

public T Get<T>(string name)
Parameters string name Parameter name.

Get<T>(string, T)

Gets the parameter by name as object of specified type returning default value if not found.

public T Get<T>(string name, T defaultValue)
Parameters string name Parameter name.
  T defaultValue Parameter default value.

Clear(string)

Removes the parameter with specified name from the selected scope.

public bool Clear(string name)
Parameters string name Parameter name.

Clear()

Removes all parameters from the selected scope.

public void Clear()

2. JavaScript Client API

The entire JavaScript API is small and consists only of a couple of functions that you need to know.

2.1. DaST.Scopes Class

DaST.Scopes namespace/class is a container for all client methods that you may need to use in your javascript. To invoke methods listed below, you have to prefix them by DaST.Scopes.

Action(scopePath, actionName, actionArgs)

Raises client-side action which can be handled in the backend controller.

DaST.Scopes.Action(scopePath, actionName, actionArgs)
Parameters scopePath String path to the target scope which is the same as id of the scope. The CurrPath() selector will be pointing at this scope inside action handler. This path also identifies the responsible controller the action is routed to.
  actionName String name under which action is bound to the action handler inside the controller class.
  actionArgs Generic JSON-serializable object that will be passed to the action handler in arg parameter.

The scopePath parameter is actually a scope ID, because scope ID is constructed from scope path. Scope ID can be taken from the id attribute of the scope container element in the HTML.

The actionArgs must be a JSON-serializable object. You can pass any custom data, and your action handler inside the controller class will get exactly the same object. JSON objects in .NET are represented by arrays and name-value dictionaries.

See usage example in Rising Actions section of tutorial.

AddMessageHandler(scopeID, msgID, callback)

Adds javascript callback listener for the message raised in the backend controller.

DaST.Scopes.AddMessageHandler(scopeID, msgID, callback)
Parameters scopeID String client id of the scope that message is associated with.
  msgID String name identifying the message.
  callback Function called whenever message is raised on the controller.

This function is a client side of the DaST duplex messaging mechanism which complements actions mechanism to allow consistent and intuitive event-based client-server both-way communication.

To raise message on the server side, MessageClient() is called on the selected scope. To handle this message on the client, AddMessageHandler() is used where scopeID should point to the selected scope and msgID should match the original msgID passed to MessageClient().

The dataItem parameter passed to MessageClient() on the server side is exposed on the client side as the first parameter of the callback specified in AddMessageHandler(). The parameter is passed to the callback in a JSON form.

See usage example in Duplex Messaging section of tutorial.

Last edited Jan 25, 2013 at 5:38 AM by rgubarenko, version 38

Comments

No comments yet.