White Labeling the Application
This applies to: Managed Dashboards, Managed Reports
This article shows how to use CSS, images, HTML, JavaScript, and other custom files for integrating, extending, or applying corporate branding (white labeling) to Symphony.
As a Symphony system administrator, you can:
Customize the Symphony web application's styling and appearance
Add JavaScript or HTML to be included on each page in the application
Add your own files to refer to, such as images or additional CSS or JS files
Customize displayed text using localization overrides
Custom CSS
Selecting Styles
All browsers have developer tools you can use to extract IDs and classes from page elements. As an example, we are going to use Google Chrome to select the element used as the background of the login page to change its color.
Pull up the Symphony login page.
Press F12, or open the developer tools from the browser menu.
In the Elements tab, click the element inspector icon next to the tabs in the toolbar (if using Chrome):
Now click on the page background. You will notice that it selects the page element <div id="loginPage-content">. We will now modify the element with this ID in our style override resource.
Modifying Styles
In the Administration area, expand Setup and then click App Styling.
Select the CSS style resource from the list and click Details on the toolbar.
In the Application Styling Resource dialog, enter the following CSS in the editor to modify the background on the login page. You can also download the resource as a file, update it in another tool, then upload it or copy and paste:
For class names, prefix the name with a period (.) instead of a hash (#).
Note: Some styles may require adding !important after the value for it to take precedence.
Click Submit to apply the changes.
Custom HTML
Similar to customizing the CSS style resource, you can add HTML to be included in every page of the application, including <script> or <link> elements that refer to separate JS or CSS files.
Under the expanded Setup section in Administration, click on the App Styling page and then select the HTML resource.
Click Details and enter or upload your HTML into the Application Styling Resource dialog.
Custom JavaScript
You can also add JavaScript to be executed when any page loads. In addition to customizing the application, this could provide a set of common functions in a global variable that can then be called from the script editor in dashboards and other views.
On the App Styling page in Administration, select the JavaScriptresource. Click Details, then enter or upload your JavaScript. For example:
Note:
If you make a mistake that prevents pages from being able to open, you can add ?ignoreBuiltInResources=true
to the end of the URL in your browser's address bar to temporarily prevent app styling resources from loading.
Images and Other Custom Files
You can add your own files to the Symphony web application to refer to in CSS, HTML, and JavaScript, including images or separate CSS or JavaScript files.
Under the expanded Setup section in Administration, click Static Resources, and then Add New in the toolbar.
In the Application Static Resource dialog, set the Resource File Type to one of the common types listed, or choose Custom file and set the Custom Resource Type to the appropriate MIME type for your file.
Click Choose File to browse to and upload your file.
After the file uploads, it will be listed along with the full URL you can use to refer to it. To copy this URL, click to select the row and click Copy in the toolbar.
As an example of using static resources, the web browser tools shown above can inspect the image element used to display the logo on the logon page to find its class.
The logo has the class loginPage-logo, and is located inside an element with the ID loginPage-contentHeader.
After uploading a custom logo.png, we can target the logo element in the CSS style resource with the following CSS that refers to our static resource using a root relative path beginning with a forward slash:
You could also use an absolute path. When using relative paths, note that the application styling resources like this CSS resource are located under the /Resource/ subfolder of your Symphony website rather than /api/resource/ like static resources.
The next time the logon page loads, the custom CSS is included that refers to the custom image:
Customizing Text
You can use Symphony's localization support to customize any of the predefined text displayed in its interface. In addition to translating it into other languages, you can override existing languages such as en (English) to customize some of its text.
As an example, we can localize the text Log on to Symphony in the page title.
Under the expanded Setup section in Administration, click Localization. A list of localization resources is displayed on the right.
You can select existing resources and open its Details from the toolbar, then download and search through its existing XML to help locate which resource you need to override.
In our example, the Web resource contains the page title. Select it from the list, then click Copy in the toolbar to create an override.
To override existing text, enter the same Target Culture name as the original localization resource (for example, en for English). Entering a different culture name can be used instead when translating the application's text into another language as described in the article localization and multi-language support.
Click Submit. The newly created localization resource is displayed on the list. It will be identified as an Override if the target culture is the same as the original localization.
Select and open the Details for the new resource. In the Localization dialog, you can update the resource directly in the editor, or you can upload a new localization resource file containing the required overrides by clicking the Choose File button.
When you populate the override, it should be the same format as the regular localization resources, but only needs to contain the strings you want to override. For example
Note: Some keys are located inside groups with the tag client so that they are downloaded and accessible in the browser rather than the server.
Click Submit and navigate to the logon page or the home page to see the changes above.
Note: You can also white label the default names of files created by Symphony. For example, override the value of GS_ImportExport_FilePrefix (you can find it in Dundas.Core) to change the prefix of exported DBIE files.
Modifying the Favicon
To modify the favorite icon displayed next to the page title by the browser, an option for installations of Symphony is to modify all of the images located in the folder [YourWebsite]\wwwroot\Content\Images\favicon.
Note: These images will not be replaced during upgrade.
As an alternative, you can use the JavaScript resource to add or change the <link> and <meta> DOM elements within the header element on the page as needed.
For more information, see:
Comments
0 comments
Please sign in to leave a comment.