Single-page application routing and hosting conventions
You can host an Angular CLI application within a Sitecore instance and you can use conventions for routing requests to the application.
This topic describes:
Angular applications in Sitecore
An Angular-CLI application normally contains a set of related files:
-
The application entry point file (
index.html
). This file references the JavaScript files the application uses. -
A set of compiled and bundled JavaScript files, including
main.bundle.js
,inline.js
, andstyles.bundle.js
. The set of JavaScript files varies depending on the compilation engine. The JavaScript files contain the application logic.
By default, Angular-CLI applications run in the root of the server. However, you cannot run Angular applications this way in Sitecore, so you must change the root path for your application.
Normally, an Angular-CLI application contains inner routing, resolved by the Angular client side. Users access any given page through the combination of the virtual path to the entry point of the application (index.html
) and the inner client side route, configured inside the application.
Consider this scenario:
-
The application is hosted under
: [your instance]\website\sitecore\shell\client\Applications\MyAwesomeApp\
-
When a user accesses this URL, the web server automatically retrieves the application files and returns them to the browser. The browser displays the
index.html
file. -
The application routing is configured to show the dashboard page by retrieving the /dashboard route.
-
When a user accesses the dashboard page from within the application, the browser displays this URL:
http://[your instance]/sitecore/shell/client/Applications/MyAwesomApplication/dashboard
, but the browser just automatically displays the appropriate file already retrieved from the server. -
If, however, the user enters the dashboard URL into the browser manually, the server does not find the file and it returns error 404 (File Not Found). This happens because the dashboard route does not correspond directly to a file on the server with that path.
To solve this problem, you use routing conventions.
Routing and hosting conventions
When you use routing and hosting conventions, you define a folder for each application. You set up Sitecore so that the server responds appropriately to requests for client-side routes.
The conventions are:
-
Each application must have a unique application name (
[AppName]
). -
You define an application host folder for each application in the file system:
/sitecore/shell/client/Applications/[AppName]
. -
You use the ng-sc module's build task to generate the Sitecore entry-point based on the Angular entry-point. As a result of this task, you will have an
index.aspx
page instead of anindex.html
. You must do this to make your application Sitecore authentication compliant andenable Anti-CSRF protection for your application.
The ng-sc cli tool
You use the ng-sc cli tool to change the index.html
file to index.aspx
. You can use the tool as a post-build step for Angular projects. When the tool renames to .aspx
, it also adds one line of code at the top of the file. This code enables SPEAK 3 features when the application runs inside Sitecore. These features include Anti-CSRF tokens, entry-point user authentication, and so on.
You use ng-sc --entry ./dist/index.html
with the following parameters:
Flag |
Description |
Default value |
---|---|---|
--entry, -e |
The name of the file to create an |
This argument is required and there is no default value. |
--out, -o |
The name of the output file, relative to the input file. |
The default value is |
--keep, -k |
A Boolean value. If set (true), the tool does not remove the input file |
Removes the entry file by default because we do not recommend that you ship your entry |
How Sitecore handles the requests
The Sitecore.Speak.Integration module handles requests in the following way:
-
The module reads the
config
file. -
The module extends the
preprocessRequest
pipeline so it listens to all requests. -
When the module detects that a URL request corresponds to one of the application folders, it rewrites the URL to redirect the request to the
index.aspx
file of the correct application.
The entry point
By default, the ng-sc cli tool creates an ASP.NET Web Forms page that inherits the Sitecore.Speak.Integration.Spa.SecureSpaPage
class.
After redirecting to the index.aspx
file, the Sitecore integration sets up backend logic in the following way:
-
It sets the Anti-CSRF cookies.
-
It tries to find the corresponding application Sitecore item.
-
It checks if the current user is allowed to access this item. If there is no item, it does not check access permissions.
-
It reads the EntryPoint field of this item (by default
index.aspx
). If there is no application item, it usesindex.aspx
as the entry point. -
It tries to find the application folder following the convention.
-
If the EntryPoint file exists in the application folder, the URL is rewritten to point to this file.
There is also an Sitecore.Speak.Integration.Spa.SpaPage
class. This class does not do the ShellPage.IsLoggedIn()
check. If you do not need Sitecore authentication in your application, you can use this class for your application entry point.
Known issues
You can switch the context language in Sitecore in the sc_lang=language
query string parameter. SPEAK 3 does not support this feature for applications that use the entry point solution.