Web Snippets

Web Snippets allow external web pages to integrate with Softadmin®.

The web developer imports a script and places <softadmin-snippet> tags on the web page. The script will then replace the contents of the tags with HTML generated by procedures in Softadmin®.

Setting up snippets in Softadmin®

Snippets are administered from the Site menu item in the Web snippets subgroup in the Admin menu group.

Sites

A site consists of one or more paths, and snippets are connected to paths. A web page can use snippets from its own path and all paths above it in the hierarchy, so e.g. a snippet connected to the root is available to all paths.

Configuration

The WebSnippets folder must be converted to an application in IIS Manager.

Two URLs must be provided when setting up a site in Softadmin®:

  • Snippets URL, which is the URL to the IIS application created for the "WebSnippets" folder, and
  • Web site URL, which is the URL to the root of the web site using the snippets.

In order for sessions to work, HTTPS must be used and the snippets URL must appear to the browser as having the same domain name as the web site URL.

If the domains are different, and e.g. the web site is located at https://example.com, you can create a subdomain such as https://snippets.example.com and use a DNS CNAME record to point it to the snippets URL.

Paths

Paths have two purposes: access control, and providing snippet parameters via path parameters.

Access control

Paths can have an access control procedure connected to them. See the Access Control call for details.

Path parameters

Paths can contain parameters enclosed in {}, for example /mypages/{department}/{subdepartment}. The parameters can be used by snippets belonging to the path.
Its also possible to match the rest of the path by using a parameter name ending in three dots, for example /mypages/intranet/{path...}.
Path parameters also require configuring e.g. URL Rewrite on the web server for the paths.

Snippets

If access to the path is granted, the applicable snippet procedures are called in no particular order.

Using snippets on a web page

After the snippets have been set up in Softadmin®, use the Site documentation HTML button (available from the Paths for site and the Sites menu items) to generate documentation containing the script to include and the available snippet tags.

SQL

SQL Call: Access Control (mandatory)

To verify access rights to snippets for a path, access control procedures are called in order, starting at the root.

  • If a procedure redirects, the user is redirected and no further procedures in the chain are called.
  • If a procedure explicitly allows access, the next procedure (if any) in the chain is called.
  • If a procedure neither redirects nor explicitly allows access, access is denied and no further procedures in the chain are called.

Implicitly denies access unless one of the following procedures is called:

The following can also be used independently of the above:

May modify database: Yes

SQL Call: Snippet Output (mandatory)

Called when a page containing this snippet is loaded. Also called if any snippet has requested reloading all snippets via SoftadminSnippet.Page_ReloadSnippets (in the Form Submit or Link/Button Postback call).

If access to the path is granted, the applicable snippet procedures are called in no particular order.

  • Session variable changes will not take effect until after all the procedures have been called.
  • If any procedure calls SoftadminSnippet.Session_LogOut, all session variables will be cleared, even if SoftadminSnippet.Session_SetVariable has been called by another procedure.
  • Redirects are performed after the session variables have been updated.
  • It is an error to set the value of the same session variable multiple times.
  • It is also an error to redirect more than once.

In addition to the columns available in the Snippet Output result set, the following procedures can be used:

The following functions can be used by the Html column:

The Html column supports the Web Snippets HTML Level. Any other HTML will be removed from the output.

May modify database: Yes

Resultset: Snippet Output (optional)

Table count: repeated zero or more times
Row count: zero or more rows
Columns
Html optional string
HTML. See the call description for details.
JavaScript mandatory string
JavaScript. Each script will have its own scope, so a function declared in one script is not visible to any other.
Plaintext mandatory string
Plaintext. HTML will be escaped and newlines will be converted to <br> tags.

SQL Call: Form Submit (mandatory)

Called when a form generated by the snippet (via SoftadminSnippet.Form) is submitted.

The snippet can use all the functions and procedures available to the Snippet Output call. In addition, SoftadminSnippet.Page_ReloadSnippets can be used.

May modify database: Yes

Parameters

@IsFormSubmit bit
Set to 1 for this call.

Resultset: Form Submit Snippet Output (optional)

Table count: repeated zero or more times
Row count: zero or more rows
Columns
Html optional string
HTML. See the call description for details.
JavaScript mandatory string
JavaScript. Each script will have its own scope, so a function declared in one script is not visible to any other.
Plaintext mandatory string
Plaintext. HTML will be escaped and newlines will be converted to <br> tags.

Resultset: #FormValue

Contains the posted form values.

NOTE: It is possible for the client to change the fields and their values before posting, so remember to perform any necessary server side validation.
Table count: repeated exactly once
Row count: zero or more rows
Columns
Name mandatory string
The name of the input field.
Value mandatory string
The posted value. Null if this row refers to an uploaded file.

NOTE: Do not assume that the value is safe. It may contain e.g. HTML tags and JavaScript.
File mandatory binary
File data if this is an uploaded file. Null otherwise.
FileName mandatory string
The name of the uploaded file if any. Null otherwise.
ContentType mandatory string
The content type of the uploaded file if any. Null otherwise.

SQL Call: Link/Button Postback (mandatory)

Called when a link or button generated by the snippet (via SoftadminSnippet.PostbackLink or SoftadminSnippet.PostbackButton) is clicked.

The snippet can use all the functions and procedures available to the Snippet Output call. In addition, SoftadminSnippet.Page_ReloadSnippets can be used.

May modify database: Yes

Parameters

@PostbackAction string
@PostbackArgument string

Resultset: Link/Button Postback Snippet Output

Table count:
Row count:
Columns
Html optional string
HTML. See the call description for details.
JavaScript mandatory string
JavaScript. Each script will have its own scope, so a function declared in one script is not visible to any other.
Plaintext mandatory string
Plaintext. HTML will be escaped and newlines will be converted to <br> tags.

SQL Call: Get Database File (mandatory)

Called when a file link generated by SoftadminSnippet.DatabaseFileLink is accessed.

May modify database: Yes

Parameters

@FileId string
The id originally passed to SoftadminSnippet.DatabaseFileLink.

Resultset: File

Table count: repeated exactly once
Row count: exactly one row
Columns
ContentType optional string
The content type of the file.
File mandatory binary
File data.

This column must be last in the result set.

SQL Call: Get Database Image (mandatory)

Called when an image link generated by SoftadminSnippet.DatabaseImage is accessed.

May modify database: Yes

Parameters

@ImageId string
The id originally passed to SoftadminSnippet.DatabaseImage.

Resultset: Image

Table count: repeated exactly once
Row count: exactly one row
Columns
ContentType optional string
The content type of the file.
File mandatory binary
File data.

This column must be last in the result set.

SQL Call: BankID Completed (mandatory)

Called when a BankID operation started by the snippet (via SoftadminSnippet.BankId_Identify or SoftadminSnippet.BankId_Sign) is finished.

The snippet can use all the functions and procedures available to the Snippet Output call. In addition, SoftadminSnippet.Page_ReloadSnippets can be used.

May modify database: Yes

Parameters

@BankIdSignatureId int
Id of the stored signature (found in SoftadminApi.BankIdSignature) if the user successfully identified or signed the data.
Not set when @IsError = 1.
@ErrorMessage string
Error message.
Set when @IsError = 1.
@IsBankIdIdentify bit
Set to 1 if the call was triggered by SoftadminSnippet.BankId_Identify. Not set otherwise.
@IsBankIdSign bit
Set to 1 if the call was triggered by SoftadminSnippet.BankId_Identify. Not set otherwise.
@IsError bit
Set to 1 if an error occurred. Not set otherwise.
@PersonalNumber string
12 digits. No other characters.