version

Install web app from external HTML page

Web snippets can be used to create customized installation pages for the system's web app.

Begin by creating a snippet used by a web page on the same domain as the Softadmin application. If the web page is not on the same domain it will not be able to install the app. The procedure should call SoftadminSnippet.WebApp_Install_Init to link the web app configuration to the external HTML page. A JavaScript callback function should also be created to display the appropriate installation steps depending on whether an installation button can be shown or device-specific installation instructions are required.

Exactly one installation button must be created with SoftadminSnippet.WebApp_Install_Button.

The recommended approach is to create the elements hidden, and displaying them depending on the callback function.


CREATE OR ALTER PROCEDURE dbo.ExampleSnippet
AS
BEGIN
	SET NOCOUNT, XACT_ABORT ON;

	DECLARE
		@InstallButtonContainerId varchar(30) = 'ButtonContainer',
		@AndroidInstructionsId varchar(30) = 'AndroidInstructions',
		@IosInstructionsId varchar(30) = 'IosInstructions',
		@GeneralInstructionsId varchar(30) = 'GeneralInstructions',
		@InstructionIdJson varchar(MAX),
		@LanguageId int = SoftadminApi.LanguageId_Default(),
		@ApplicationUrl nvarchar(500) = SoftadminApi.Setting_Value('ApplicationUrl');

	SELECT
		@InstructionIdJson = '[' + STRING_AGG('"' + I.Id + '"', ',') + ']'
	FROM
		(VALUES
			(@InstallButtonContainerId),
			(@AndroidInstructionsId),
			(@IosInstructionsId),
			(@GeneralInstructionsId)
		) I(Id);

	SELECT 
		'<div id="' + @InstallButtonContainerId + '" style="display: none">
			<p>Press the button below to install</p>
			' + SoftadminSnippet.WebApp_Install_Button(N'Install web app', 'WebAppInstallButton') +
		'</div>' AS Html;

	SELECT
		'<p style="display: none" id="' + @IosInstructionsId + '">???</p>' AS Html;

	SELECT
		'<p style="display: none" id="' + @AndroidInstructionsId + '">???</p>' AS Html;

	SELECT
		'<p style="display: none" id="' + @GeneralInstructionsId + '">???</p>' AS Html;

	SELECT
	'function showInstructions(deviceType, showInstallButton) {
		// Here we choose to explicitly not install the Web App on desktop and instead
		// show the mobile instructions even though it is fully possible to install it on a 
		// desktop device. This is purely a preference.
		if (showInstallButton && deviceType !== "desktop") {
			showSingleInstruction("' + @InstallButtonContainerId + '");
			return;
		}

		if (deviceType === "ios") {
			showSingleInstruction("' + @IosInstructionsId + '");
		} else if (deviceType === "android") {
			showSingleInstruction("' + @AndroidInstructionsId + '");
		} else {
			showSingleInstruction("' + @GeneralInstructionsId + '");
		}
	}

	function showSingleInstruction(htmlId){
		for (let currentId of ' + @InstructionIdJson + '){
			if (currentId === htmlId){
				document.getElementById(currentId).style.display = "block";
			} else {
				document.getElementById(currentId).style.display = "none";
			}
		}
	}' AS JavaScript;

	EXEC SoftadminSnippet.WebApp_Install_Init
		@ApplicationUrl = @ApplicationUrl,
		@LanguageId = @LanguageId,
		@InstructionsCallbackJavaScriptFunctionName = 'showInstructions';
END;

Create an index.html file in the path specified for the snippet site, and paste the below skeleton.

<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<script src="https://xxxxx/softadmin.js"></script>
	<title>Web app installation</title>
</head>
<body>
	<softadmin-snippet snippet="xxxx"></softadmin-snippet>
</body>
</html>

The snippet needs to be placed inside of the body tags, "xxxx" represents the name of the snippet.

The site's JavaScript needs to be referenced inside of the head tags, it can be found in Softadmin by going to the site, and then pressing the top link "Site documentation HTML". "xxxxx" in the example illustrates the URL found in the site documentation.

Android instructions

Replace the "???" with the Android instructions. See phrase with ID 111515 for inspiration, but do not use that phrase as it may change and reference internal resources (images) inaccessible from the web site in the future. The text of the phrase may be copied, but it should only reference pictures on the external web site, add pictures to the external web site if necessary.

iOS instructions

Replace the "???" with the iOS instructions. See phrase with ID 111514 for inspiration, but do not use that phrase as it may change and reference internal resources (images) inaccessible from the web site in the future. The text of the phrase may be copied, but it should only reference pictures on the external web site, add pictures to the external web site if necessary.

Desktop instructions

For desktop there are two approaches depending on if you want to allow the Web App to be installed on a desktop device.

If it should be installed on desktop devices, simply write the instructions to do so for the browsers that should be supported.

If the Web App should only be installed on mobile devices, the recommended way is show an image with a QR-code with a link to the same web page. This way the user easily can open the same link on their mobile device and install the app.