Step 3: Review the Structure of Local Component Settings

In this step we review the structure of the settings specified for a local component.

Similar to the render.js file in the /assets directory, there is a pre-created settings.html file in the same directory. The settings.html file renders any custom settings data for your component. In the default implementation, there is a single property imageWidth in the custom settings data.

To review the structure of your local component:

Using the Oracle Content Management desktop sync client, locate your component and sync it with the file system.

If you don’t have the desktop sync client, you can select the component on the Components tab of the Oracle Content Management web interface and drill down to see the files.

If you list the files under the component, you’ll see these files:

assets
    render.js
    settings.html
appinfo.json
_folder_icon.jpg

Open the settings.html file under the /assets directory and review the content. Unlike the render.js file, the settings.html file uses an inline frame in the Settings panel in Site Builder, which is why it also needs access to the supporting files to render correctly within the inline frame. Site Builder is needed to manage your site so any errors in your JavaScript code can be isolated from Site Builder, which is why the settings.html file uses an inline frame.

These are the main areas of the settings.html file:

Knockout Template to render the Settings panel.

<!-- ko if: initialized() -->
<div class="scs-component-settings">
  <div>
    <!-- Width -->
    <label id="widthLabel" for="width" class="settings-heading" data-bind="text: 'Image Width'"></label>
    <input id="width" data-bind="value: width" placeholder="example: 200px or 33%" class="settings-text-box">
  </div>
</div>
<div data-bind="setSettingsHeight: true"></div>
<!-- /ko -->

Custom Binding Handler to adjust the height of the inline frame once the Settings panel has been rendered.
```
ko.bindingHandlers.scsCompComponentImpl
```
A Knockout ViewModel to apply to the Knockout Template.
```
SettingsViewModel
```

These are the main elements of SettingsViewModel :

Subscriptions to component lifecycle.

Component initialization:

Make sure the component doesn't render until all data has been fetched. This is handled through Knockout observables.
```
self.initialized = ko.observable(false);
```
Make sure we don't attempt to update the data until we're ready.
```
self.saveData = false;
```

Get the initial values for any required properties. This is handled by callbacks to retrieve the data.

    SitesSDK.getProperty('customSettingsData', function (data) {
      //update observable
      self.width(data.width);

      // note that viewModel is initialized and can start saving data
      self.initialized(true);
      self.saveData = true;
    });

Save any property changes to the custom settings data.

    self.save = ko.computed(function () {
      var saveconfig = {
        'width': isNaN(self.width()) ? self.width() : self.width() + 'px'
      };

      // save data in page
      if (self.saveData) {
        SitesSDK.setProperty('customSettingsData', saveconfig);
      }
    }, self);

To add another property that you want to capture, several steps are required:

Update the user interface to display the new value.
Initialize the value to the current value stored against the component.
Save any changes to the value back to the component.

To add another property to your custom component, make these changes to the settings.html file:

Add another observable to handle the new property. Change this code:

self.width = ko.observable();

Use this code instead:

self.width = ko.observable();
self.imageBannerText = ko.observable();

Get any current value for the new property when the settings panel is first displayed. Change this code:
```
self.width(data.width);
```
Use this code instead:
```
self.width(data.width);
self.imageBannerText(data.imageBannerText);
```

Save any change to this new property. Change this code:

    'width': isNaN(self.width()) ? self.width() : self.width() + 'px'

Use this code instead:

'width': isNaN(self.width()) ? self.width() : self.width() + 'px',
'imageBannerText': self.imageBannerText()

Add a user interface to display the new field. Change this code:

<label id="widthLabel" for="width" class="settings-heading" data-bind="text: 'Image Width'"></label>
<input id="width" data-bind="value: width" placeholder="example: 200px or 33%" class="settings-text-box">

Use this code instead:

<label id="widthLabel" for="width" class="settings-heading" data-bind="text: 'Image Width'"></label>
<input id="width" data-bind="value: width" placeholder="example: 200px or 33%" class="settings-text-box">

<label id="imageBannerTextLabel" for="imageBannerText" class="settings-heading" data-bind="text: 'Image Banner'"></label>
<input id="imageBannerText" data-bind="value: imageBannerText" placeholder="Text to display above an image" class="settings-text-box">

Sync or upload the settings.html file.

If you were to run this now, the field would display. However, the size of the Settings panel doesn’t change automatically. Because you increased the size of the panel, you also must update the components.json registration entry to the new size.

Download the appinfo.json file, which is at the same level as the assets/ directory for you component, and update the size of the settings panel. Change this code:
```
"settingsHeight": 90,
```
Use this code instead:
```
"settingsHeight": 160,
```
Sync or upload the appinfo.json file.

Check the Results for Step 3

You should now be able to see and enter the new property you added to the Settings panel.

Refresh your page in your site so Site Builder can pick up changes to the component.
Take the page into Edit mode.
Drag and drop your component onto the page.
Bring up the Settings panel against your component.
Click the Custom Settings button.

You will see two fields displayed for each of the properties you have in your settings.html file.

Continue to Step 4: Display the New Property in the Component.