Customize prebuilt screens

Learn about features and the prebuilt screens that come with the HealthCare Locator SDK before customizing them as part of your app UI. For details, see the following:

●         Android app

●         iOS app

●         JavaScript app (or website)

Notes

●         The following examples of code show the location to specify the API key received from the free trial or pro version signup.

●         The following examples include customization for:

o       near me geolocation of user for search input

o       Google Maps integration

o       dark theme for screens and dark mode for map

●         Test your app after configuring the SDK and customizing its prebuilt screens. Once published, your app is now packaged and features the HealthCare Locator search screens for users to find HCPs and HCOs.

Android app

Configure

To configure, initialize with your API key, and start as a new Activity or Fragment within your UI, see the following:

●         As a new Activity:

o       Java:

```Java

/**

* Font(s) must be in assets folder.

* Example: assets/fonts/Roboto-Regular.ttf

**/

HealthCareLocatorViewFontObject fontTitleMain = new HealthCareLocatorViewFontObject.Builder()

        .title("titleMain").fontName("fonts/Roboto-Regular.ttf")

        .weight(Typeface.BOLD).size(20).build();

//...

//Set font(s)

builder.fontTitleMain(fontTitleMain);

//...

//Set color(s)

builder.colorPrimary("#FFFFFF");

builder.colorSecondary("#000000");

HealthCareLocatorSDK.init("<Your api key>").setAppName("<Your app name>")

                .setAppDownloadLink("<Your download link>").setCustomObject(builder.build());

HealthCareLocatorSDK.getInstance().startSDKActivity(this);

```

o       Kotlin:

```Kotlin

val builder = HealthCareLocatorCustomObject.Builder()

/**

*Font(s) must be in assets folder.

*Example: assets/fonts/Roboto-Regular.ttf

**/

val fontTitleMain: HealthCareLocatorViewFontObject = HealthCareLocatorViewFontObject.Builder(

        id = "titleMain", size = 20, fontName= "fonts/Roboto-Regular.ttf",

         weight = Typeface.BOLD).build()

//...

//Set font(s)

builder.fontTitleMain(fontTitleMain)

//...

//Set color(s)

builder.colorPrimary("#FFFFFF")

       .colorSecondary("#000000")

builder.entryScreen(ScreenReference.HOME_FULL)

HealthCareLocatorSDK.init("<Your api key>").setAppName("<Your app name>")

                .setAppDownloadLink("<Your download link>").setCustomObject(builder.build())

HealthCareLocatorSDK.getInstance().startSDKActivity(this)

```

●         As a Fragment from your Activity:

o       Java:

```Java

int containerId = R.id.fragmentContainer;

HealthCareLocatorCustomObject.Builder builder = new HealthCareLocatorCustomObject.Builder();

/**

* Font(s) must be in assets folder.

* Example: assets/fonts/Roboto-Regular.ttf

**/

HealthCareLocatorViewFontObject fontTitleMain = new HealthCareLocatorViewFontObject.Builder()

        .title("titleMain").fontName("fonts/Roboto-Regular.ttf")

        .weight(Typeface.BOLD).size(20).build();

//...

//Set font(s)

builder.fontTitleMain(fontTitleMain);

//...

//Set color(s)

builder.colorPrimary("#FFFFFF");

builder.colorSecondary("#000000");

HealthCareLocatorSDK.init("<Your api key>").setAppName("<Your app name>")

                .setAppDownloadLink("<Your download link>").setCustomObject(builder.build());

HealthCareLocatorSDK.getInstance().startSDKFragment(this, containerId);

```

o       Kotlin:

```Kotlin

val containerId:Int = R.id.fragmentContainer

val builder = HealthCareLocatorCustomObject.Builder()

/**

* Font(s) must be in assets folder.

* Example: assets/fonts/Roboto-Regular.ttf

**/

val fontTitleMain: HealthCareLocatorViewFontObject = HealthCareLocatorViewFontObject.Builder(

        id = "titleMain", size = 20,fontName= "fonts/Roboto-Regular.ttf",

        weight = Typeface.BOLD).build()

//...

//Set font(s)

builder.fontTitleMain(fontTitleMain)

//...

//Set color(s)

builder.colorPrimary("#FFFFFF")

       .colorSecondary("#000000")

builder.entryScreen(ScreenReference.HOME_FULL)

HealthCareLocatorSDK.init("<Your api key>").setAppName("<Your app name>")

                .setAppDownloadLink("<Your download link>").setCustomObject(builder.build())

HealthCareLocatorSDK.getInstance().startSDKFragment(this, containerId)

```

First screen

By default, the Home screen (and its blocks of content) is first to appear but you can set the Near me search to first appear after the SDK is started, such as by a button or icon within your app UI. For example:

●         Near me search – If you want to land directly on the "Cardiologist near me" or "Near me" search with a pre-configured [specialities](), [specialtyLabel](), then set it as follows:

```Kotlin

fun entryScreen(@ScreenReference screenReference: Int, specialtyLabel: String, specialities: ArrayList<String>) = apply {

                    this.screenReference = screenReference

                    this.specialtyLabel = specialtyLabel

                    this.specialities = specialities

                }

```

```Kotlin

builder.entryScreen(ScreenReference.SEARCH_NEAR_ME,

             "Cardiologist",

             ['XXX', 'YYY'])

```

●         Near me search distance – If you want to do a near me search with a pre-configured [distanceUnit](), [distanceDefault](), then set it as follows:

```Kotlin

fun distanceUnit(distanceUnit: String) = apply {this.distanceUnit = distanceUnit}

fun distanceDefault(distanceDefault: Double) = apply {this.distanceDefault = distanceDefault}

```

```Kotlin

builder.distanceUnit("Kilometer") /** Kilometer or Mile **/

       .distanceDefault(0.0)

```

Dark mode

●         Dark mode for map – To configure dark mode for the map with [darkModeForMap](), then set it as follows:

```Kotlin

fun darkModeForMap(darkModeForMap: Boolean) = apply {this.darkModeForMap = darkModeForMap }

```

```Kotlin

builder.darkModeForMap(true) /** true or false **/

```

For a map service:

o       If [mapService]() is OpenStreetMap:

```Kotlin

mMapView.overlayManager.tilesOverlay.setColorFilter(TilesOverlay.INVERT_COLORS)

```

o       If [mapService]() is Google Maps, then create the google_map_night.json file. Click to show/hide example ...

●         Dark theme for SDK – To configure dark theme for the SDK with [darkMode](), then set it as follows:

```Kotlin

fun darkMode(darkMode: Boolean) = apply {this.darkMode = darkMode}

```

```Kotlin

builder.darkMode(true) /** true or false **/

```

Note that darkMode uses 2 colors to apply dark theme:

```Kotlin

var darkModeColor: String = "#232323"

var darkModeLightColor: String = "#323232"

```

iOS app

Set up in Xcode

To customize the prebuilt screens as part of the UI for your iOS app, see the following:

1.      In the navigation bar of Xcode, click project navigator icon ( ), and select the project name of your app.

2.      HCL targets its search results using the current location of your app, and must prompts users for their permission to use their current location. To set this up, do the following:

●       In the project editor, select a target (your app to build) in the TARGETS section.

●       Click the Info tab. The Info pane appears.

●       Expand Custom iOS Target Properties, and scroll through the list to find the following location permissions:

Privacy - Location Always Usage Description
Privacy - Location Always and When In Use Usage Description
Privacy - Location When In Use Usage Description

●       For each location permission, add a good explanation for the reason why you need to access the current location of users. For example:

```Swift

$(PRODUCT_NAME) wants to know your current location to perform more accurate search results for healthcare providers and organizations.

```

Configure

1.      After installing HealthCare Locator in the Xcode project of your app, you must add a HCLSDK initialization code to your app. To do this, import the HCLSDK module and configure a shared instance as shown:

```Swift

import HCLSDK

```

2.      Configure an HCLManager shared instance, typically in your app's method "application:didFinishLaunchingWithOptions:". For example:

```Swift

let shared = HCLManager.shared

share.initializeWith(apiKey: <your-api-key>)

```

First screen

By default, the Home screen (and its blocks of content) is first to appear but you can set the Near me search to first appear after the SDK is started, such as by a button or icon within your app UI. For example:

●         Home screen – To retrieve/open the HealthCare Locator home screen (and search screens) instance on your app UI whenever you need it, use the following line:

```Swift

// retrieve an instance of HCLHCPSearchNavigationViewController

let HCPSearchVC = HCLManager.shared.getHCPSearchViewController()

// Display the search screen as you want

present(HCPSearchVC, animated: true)

```

Know that "HCLHCPSearchNavigationViewController" is a subclass of "UINavigationViewController".

●         Near me search – If you want to land directly on the "Dentist near me" or "Cardiologist near me" search with a pre-configured [specialtyCode](), [specialtyLabel](), then see the following:

```Swift

let config = HCLSearchConfigure(entry: .nearMe, speciality: "XXX, YYY", specialtyLabel: "Dentistry"))

```

●         Near me search distance – If you want to do a near me search with a pre-configured [distanceDefault](), [distanceUnit](), then see the following:

```Swift

let distanceDefault: Double = 1.0

let distanceUnit: HCLDistanceUnit = .km // or use .mile

let config = HCLSearchConfigure(entry: .nearMe, speciality: "XXX, YYY", specialtyLabel: "Dentistry", distanceDefault: distanceDefault, distanceUnit: distanceUnit)

```

Dark mode

●         Dark theme for SDK – If you want to configure the dark theme for SDK with [darkmode](), [darkmodeForMap](), then set it as follows ...

```Swift

let themeConfig = HCLThemeConfigure(..., darkmode: true, darkmodeForMap: true)

```

Note the following for the dark theme:

o       darkmode – Use 2 colors to apply dark theme:

```Swift

var kDarkColor = UIColor(red: 35/255, green: 35/255, blue: 35/255, alpha: 1.0)

var kDarkLightColor = UIColor(red: 50/255, green: 50/255, blue: 50/255, alpha: 1.0)

```

o       darkmodeForMap – Use the default dark color by Apple (supported in iOS 13.0).

JavaScript app

Configure

Configure SDK – To configure, initialize with your API key, and start the SDK, you must append parameters to the object passed to the HclSdk instance in your JavaScript, React, or Angular app ...

```javascript

const config = {

  <PARAMETER_NAME>: <PARAMETER_VALUE>

}

```

... where "<PARAMETER_NAME>" is one of the following:

Example configuration:

```javascript

HCLSDK.init({

  apiKey: "1234",

  icons: {

    search: `<svg>...</svg>`,

  },

  showSuggestModification: false,

  getCurrentPosition(success, error) {

    success({

      longitude : 43,65107,

      latitude: -79,347015

    })

  }

});

```

First screen

By default, the Home screen (and its blocks of content) is first to appear but you can set the Near me search to first appear after the SDK is started, such as by a button or icon within your app UI. For example:

●         Home screen – The entry screen can be changed by overriding the entry configuration parameter. The default value of entry is the following:

```javascript

entry: {

  screenName: "home";

}

```

●         Near me search – If you want to land directly on the "Near me" search with a pre-configured specialty, then set it as follows ...

```javascript

entry: {

  screenName: 'searchNearMe',

  specialtyCode: ['XXX', 'YYY'],

  specialtyLabel: 'Dentistry'

}

```

... where specialtyCode is a valid specialty code from your subscribed package.

CSS variables

The SDK UI styles are highly customizable using CSS variables. You can override any of our variables by targeting the hcl-sdk element from your stylesheet. For example, to customize the main and secondary colors of the HealthCare Locator UI, just add the following CSS to your website:

```

hcl-sdk {

  --hcl-color-primary: #001f3f;

  --hcl-color-secondary: #39cccc;

}

```

Color variables

Click to show/hide color variables ...

Font variables

Click to show/hide font variables ...

Update without reloading

To update the configuration of the SDK without reloading the page, call the updateConfig method on the SDK instance. For example:

```javascript

const sdkInstance = document.querySelector('hcl-sdk');

sdkInstance.updateConfig(configPatch);

```

"configPatch" is a JavaScript plain object containing the properties/values to update. For example, if you want to change the SDK UI language:

```javascript

sdkInstance.updateConfig({

  locale: 'fr_CA'

});

```

Widget

If you want to display a widget within your app instead of the prebuilt screens of the SDK, then configure a widget for the SDK (only the widget for the map is currently supported):

●         Vanilla JavaScript app:

```html

<body>

  <div class="widget-wrapper">

    <hcl-sdk id="map-instance" widget="map"></hcl-sdk> <!-- Using the same configuration as the Main Instance -->

  </div>

  <script>

    document.getElementById('map-instance').widgetProps = {

      mapHeight: '200px',

      ...

    }

  </script>

</body>

```

●         React app:

```jsx

  function App() {

    return (

      <div class="wrapper">

        <HclSdk config={config} widget="map" widgetProps={widgetProps} />

      </div>

    )

  }

```

●         Angular app:

```javascript

  @Component({

    template: `

      <div class="wrapper">

        <hcl-sdk-component [config]="config" [widget]="'map'" [widgetProps]="widgetProps"></hcl-sdk-component>

      </div>

    `,

  })

```

Next, get a pro version subscription key.