About The Project

this package will allow you to easily make Rhodium24 runs in your website

Getting Started

You can install the package with npm

npm install @metal-heaven/rh24-webapp-sdk

or you can reference the script hosted on Rhodium24 CDN

<script src="https://rhodium24.io/sdk/rh24-webapp-sdk.js"></script>

Prerequisites

The referenced script will allow you to control the render of an <iframe> pointing to Rhodium24 webapp. You can call the render method any time (after a user click, or after the page load) and control some aspects of the app style (for now just the logo src, but more to came).

Be aware that is preferable to run Rhodium24 using the hole view port. Please contact Rhodium24 staff if you need more control on it.

Usage

1. Get your partyId in Rh24 integration settings page

2. Install the script in the desired page

3. You can define a container DOM node to be parent of the iframe.

<div id="rh24-container" />

4. Instanciate the rh24-webapp-sdk

const rh24 = new rh24Sdk.Rh24WebApp({
            partyId: '<YOUR_PARTY_ID>',
            rh24BaseUrl: 'https://rhodium24.io',
            theme: {
                logoSrc: '<COMPANY LOGO>,
            }
        })

        rh24.render('rh24-container', window.location.hash.slice(1));

Options

The options object comes with some handy flags to control what the sdk will do for you

• marginTop: if you wish to keep your site navbar visible at top of page, define the size of the marginTop property so the height of rh24 app will be calculated approperly
• onLocationChange: (relativePath: string) => void: Callback to control the Rhodium24 onLocationChange event. If you don't define it and has replaceHistoryStateOnLocationChange the HTML5 History API (pushState) will be used to change the browser URL
• replaceHistoryStateOnLocationChange: If true will use the HTML History API to change the browser URL when you navigate in Rhodium24 pages.
• replaceDocumentTitle: If true will change the document.title to be in sync with Rhodium24 context
• disableCache: If true will add a dummy querystring (?v=Math.random()) to iframe src in order to not get a cached result.

ThemeV5

Rhodium24 uses the @mui/material for UI components and theme support. To be able to customize the look and feel of the website, refer to official documentation.

To use the new version, you should set the themeV5 property like this

    themeV5: {
      logoSrc: <your logo url>,
      typography: {
        fontFamily: "'Poppins', sans-serif",
        button: {
          textTransform: 'lowercase'
        }
      },
      components: {
        MuiCssBaseline: {
          styleOverrides: {
            '@global': {
              body: {
                backgroundImage: 'none',
              },
            },
          },
        },
        MuiAppBar: {
          styleOverrides: {
            colorPrimary: {
              backgroundColor: '#24344d',
              boxShadow: '0px 0 2px 0 #a8a7a6',
            },
          },
        },
      }
    }

Changing the background

To override styling properties progress with the following:

  themeV5: {
      overrides: {
        '@global': {
          backgroundImage: 'none',
          backgroundColor: '#FAFAFA"
        }
      }
  }

Palette

You can define many aspect of the color palette for the web site

themeV5: {
 palette: {
    mode: 'dark',
    primary: {
      main: '#5893df',
    },
    secondary: {
      main: '#2ec5d3',
    },
    background: {
      default: '#192231',
      paper: '#24344d',
    },
    error: {
      main: '#f44337',
    },
    warning: {
      main: '#ffa727',
    },
    info: {
      main: '#29b6f7',
    },
    success: {
      main: '#66bb6b',
    },
    divider: 'rgba(255,255,255,0.13)',
  },
}

Typography

If the host page already import the necessary fonts, you can set the the fontFamily like this

   themeV5: {
     typography: {
       fontFamily: "'Poppins', sans-serif",
     }
   }

But, if the host page don't import the necessary fonts, you should also inform the fontFamilies that need to be imported from Google Fonts

  themeV5: {
    googleFonts: 'Poppins, Lato',
    typography: {
      fontFamily: 'Poppins' //default fontFamily
      h1: {
        fontFamily: 'Lato' //override the fontFamily h1 tag
      }
    }
  }

AppBar

To change the top navigation bar (where you have the search and the menu)

  themeV5: {
    overrides: {
      MuiAppBar: {
        colorPrimary: {
          backgroundColor: '#FAFAFA',
          color: 'black'
        }
      }
    }
  }

Project Page vertical menu

This will change the styling of the left side menu within the project page

  themeV5: {
    verticalMenu: {
      backgroundColor: '#FAFAFA',
    },
  }

Theme creator helper

You can use this @mui theme generator to create your theme.

Theme (material-ui v4 - deprecated)

• the property theme was deprecated in favor of themeV5 *

Rhodium24 uses the React-MaterialUI library, allowing the use of ThemeOptions to customize many aspects of the user interface. Please refer to a sample implmentation of this mechanism in the examples folder. Some common customization could be the following.

if you'd like to see all the default material-ui properties that can be changed, please check material-ui's default theme.

Needs inspiration? checkout the material theme creator

Advanced

Routes

The render method receives two parameters: the container element id and the relative path to render Rhodium24. It's up to you define how you will handle the routes and send it to the correct page. Check the samples for usage within a React App and for vanilla HTML app.

onLocationChange

You can define how to handle location changes by defining the options.onLocationChange method.

// deep link integration using window.location.hash
// will generate urls like https://<your-company>.com/<page>/#/project/<project-id>

const rh24 = new rh24Sdk.Rh24WebApp({
            partyId: '<YOUR_PARTY_ID>',
            rh24BaseUrl: 'https://rhodium24.io',
            options: {
                // by default the sdk changes the URL using HTML5 history api
                replaceHistoryStateOnLocationChange: false
                onLocationChange: (path) => {
                    window.location.hash = path
                }
            }
            theme: {
                logoSrc: '<COMPANY LOGO>',
            }
        })

rh24.render('rh24-container', window.location.hash)

Roadmap

See the open issues for a list of proposed features (and known issues).

Contact

• Quotation Factory
• [email protected]

Project Link: https://github.com/Rhodium24/rh24-webapp-sdk/