You are viewing the documentation for Blueriq 15. Documentation for other versions is available in our documentation directory.


This page is relevant to you when you want to create your own theme for Blueriq using The Angular framework for Blueriq

The Blueriq Material Theme can be used with Blueriq 10.x and onward.


This will explain on how to get your own material theme up and running so you can start create your own theme based on this kickstarter

Setup the Blueriq Material Theme

The following steps should be taken to get the Angular based Blueriq Material Theme running

  1. Download/fork our theme kickstarter here: https://github.com/blueriq/blueriq-material 
  2. Configure the `proxy.conf.js` correctly. Read the README.md on how to set the environment variable
  3. Configure the baseUrl in `environment.ts
  4. Set up the base href (see the Base href section below)
  5. https://my.blueriq.com/ApiDocs/npm-libs/blueriq-angular/0.6.16/additional-documentation/getting-started.html 
    1. Login to artifactory: npm login --always-auth --scope=@blueriq --registry=http://my-example-artifactory.com/artifactory/api/npm/yarn/
  6. Remove the yarn.lock file that is distributed with the kickstarter theme (see yarn.lock section below)
  7. Run the following command `yarn install` to install all packages
  8. Run the following command `yarn start` to see your theme in action. This which will open up a browser that navigates to the `default` shortcut that you configured or use `localhost:4200/flow/<project>/<flow>` 
    For other possible routes please look at the `app.module.ts` routes.

Customization

The next step would be to customize it to your liking. Take a look at the theme folder and read the 'THEMING.md' to get the best practice on how to do so.

yarn.lock file

The yarn.lock file that is distributed with the kickstarter theme is used by Blueriq's CI servers. It references Blueriq's internal Artifactory server, as the CI servers cannot connect to the internet directly.

Therefore, when initially using the kickstarter project, you should remove the yarn.lock file before performing `yarn install`. You should check the resulting new yarn.lock file into your version control system.

Base href

Angular apps require a base href in order to find the proper resources. More information can be found in the Angular documentation on deployment.

The Blueriq Material theme contains some inline javascript code to determine the base href in case the theme is served from the Runtime itself, because the URL can differ per customer and per server. If you know the URL on which the Angular application runs beforehand, you are encouraged to remove the inline javascript code from index.html and configure the base_href statically, by including a hard coded <base href="/path/to/your/app">  tag or by specifying in the base href in angular.json .

In production

For more information on this subject please read the following: Angular and Deploying the theme

  • No labels

8 Comments

  1. Oke, so how do I add the theme to the runtime so we can choose it from the Blueriq dashboard?

    After I did these 6 steps, which btw I used npm instead of yarn, since I kept getting errors with yarn, I did a maven install (after removing the yarn.cmd since I am not using Windows) and added the jar to my runtime.

    Do I need to change application.properties? I found:

    blueriq.angular.active-themes=material

    blueriq.angular.themes.material.template-group-file=UI/mvc/v2/material.stg

    blueriq.angular.themes.material.template-name=redirect


    But I don't really understand the path for material.stg

    1. Setting these properties is only if you want to use the material front-end out-of-the-box (instead of MVC)
      This path is used within the blueriq.war which points to the stg


      This page explains on how to get the front-end up and running as a developer for a custom front-end

      1. MVC is depricated, so yes I want to use the material front end, which I edited with my changes, build as a jar, and added to my runtime.war

        The question is: how do I add my custom front-end to the runtime so we can choose it from the Blueriq dashboard?

        1. You should not replace / add the current front-end to the runtime.
          If you want to have a custom theme you should have something like nginx / tomcat / etc. which runs your front-end (separately).

          1. Ok thank you! I will try that.

          2. but why? if we want a dev bar we kind of need to be able to run our own stg?

            1. For the frontend to become independent, it needs to be deployed separately from the Runtime. This has many benefits but also some downsides, one of which is that it may require a bit more effort to manage multiple deployments.

              The development toolbar is not designed with an independent frontend in mind, so the initial effort of moving the frontend outside of the Runtime is unable to offer a great experience in that regard.

              You can however workaround this limitation, by creating an STG that performs a redirect to the location where you host your theme:

              delimiters "$", "$"
              
              main(context) ::= <<
              <!DOCTYPE html>
              <html>
              <head>
                  <meta charset="UTF-8">
                  <script type="text/javascript">
                  window.location.href = "http://localhost:4200/session/$context.sessionId$" +  window.location.search;
                  </script>
                  <title>Redirecting to Angular...</title>
              </head>
              </html>
              >>
              
              

              This is less than ideal as you need to have an STG for each location the frontend may be hosted at, but at least it enables the usage of the development toolbar.

              1. True, and doing this with the devbar will trigger some csp validations in the browser. But these can be suppressed I suppose for dev purposes.