Platform Static Content Server
In addition to providing a rich OData and WebApi endpoint, the Cireson Platform can also serve static content to an http client. By utilizing the static file services of the platform, developers can create rich client side UI experiences.
Understanding Static Content
Static content can be added to a Cireson Platform instance in one of two ways.
- Added as a ResourceOverride to the running platform
- Added as files in the ContentRoot folder of a CPEX Package
When a web client requests a static file, the Platform first checks the ResourceOverride Store for the file, if it is not found, it will check the PlatformExtensionResource Store in descending order of Resource Priority, as multiple extensions may contain a same named file.
Imagine this scenario:
- Bob creates an extension with a file called ReadMe.html in the ContentRoot folder of his project
- Nancy also creates an extension with a file of the same name in the ContentRoot folder
- Nancy uploads her extension to their shared Platform and checks the ReadMe.html file at http://platform/ReadMe.html and it looks good
- Bob uploads his extension, and checks the same path expecting to see his file, but instead he sees Nancy's
To understand what might have happened, let's start by looking at how the platform determines which file gets delivered in the case of conflicting names. Since both Extensions define the same file, the platform first looks at the Extension.manifest file found in the root of the CPEX Project. The extension.manifest is a json formatted file that looks like this
{
"PrimaryAssembly": "Cireson.Nancy.dll",
"ContentRootPath": "ContentRoot",
"ExtensionName": "Nancy",
"Description": null,
"Version": "1.0.0.0",
"SecondaryAssemblies": [],
"ResourcePriority": 1000,
"IsApplicationPackage": false,
"Keywords": []
}
Notice the property ResourcePriority. This is the value the Platform uses to make a determination when a file name collission occurs. The higher the value, the more precidence is given to the file.
If Bob wants his files to take precidence over Nancy's files, he needs to increase the ResourcePriority of his extension to a greated value than Nancy's.
In addition to static files delivered as a part of a CPEX Package, an administrator can override specific files by adding them to the ResourceOverride Set. The ResourceOverride allows an end user (with appropriate permissions) to upload individual files that may or may not override existing CPEX delivered files. If a CPEX delivered file is overridden, the file is not destroyed, and will be delivered if the ResourceOverride file is subsequently removed.
You can add files to the ResourceOverride store using the CPEXLets command Set-CPEXResourceOverride
see Platform Powershell Management for more information.
Note
Static content can represent almost any type of file you wish to serve. For a Web based application (such as Cireson.Platform.WebUI) you may wish to serve css, js, svg files. But if you are planning to build a Windows Universal app, you may want to deliver xaml files as static content.
Note
For very large files such as videos, or large data files, it is not recommended to use static content. You should host the file on a content service (Such as Azure Storage) and reference the file within your application.
Customizations using Static Content
If you wish to customize an application that exposes a web based UI, overriding files using Resource Overrides may be an easy way to make modifications to the UI. If for example you wish to change a logo, you can inspect the logo in a browser, and look at the URL. you may see something like this
<img width="66" height="24" src="~/img/logo.png" alt="True">
if you would like to replace the logo with your own, you can do so by creating another png image file with the same name, and uploading it to the ResourceOverride Store by invoking the following command:
Set-CPEXResourceOverride -resourceFolder "\img\" -uploadFilePath .\logo.png
The same technique can be used to customize css, js, or html files as well.