### Complete Pebble Clay Watchface Configuration Example (JSON, JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

This is a comprehensive example of a Pebble watchface configuration using Pebble Clay. It includes a 'config.json' file defining various UI elements like headings, colors, toggles, inputs, selects, and sliders. The 'index.js' file initializes the Clay instance with the configuration, and PebbleKit JS handles settings retrieval upon watchface startup.

```json
// config.json
[
  {
    "type": "heading",
    "defaultValue": "Weather Watchface",
    "size": 1
  },
  {
    "type": "section",
    "items": [
      {
        "type": "heading",
        "defaultValue": "Appearance"
      },
      {
        "type": "color",
        "messageKey": "bg_color",
        "defaultValue": "000000",
        "label": "Background Color"
      },
      {
        "type": "color",
        "messageKey": "fg_color",
        "defaultValue": "FFFFFF",
        "label": "Text Color"
      },
      {
        "type": "toggle",
        "messageKey": "show_seconds",
        "label": "Show Seconds",
        "defaultValue": false
      }
    ]
  },
  {
    "type": "section",
    "items": [
      {
        "type": "heading",
        "defaultValue": "Weather Settings"
      },
      {
        "type": "input",
        "messageKey": "api_key",
        "label": "API Key",
        "attributes": {
          "type": "text",
          "required": "required"
        }
      },
      {
        "type": "select",
        "messageKey": "temp_units",
        "label": "Temperature Units",
        "defaultValue": "celsius",
        "options": [
          {"label": "Celsius", "value": "celsius"},
          {"label": "Fahrenheit", "value": "fahrenheit"}
        ]
      },
      {
        "type": "slider",
        "messageKey": "update_interval",
        "label": "Update Interval (minutes)",
        "defaultValue": 30,
        "min": 15,
        "max": 120,
        "step": 15
      }
    ]
  },
  {
    "type": "submit",
    "defaultValue": "Save Settings"
  }
]

// index.js
var Clay = require('pebble-clay');
var clayConfig = require('./config.json');
var clay = new Clay(clayConfig);

// Clay automatically handles everything!
// Settings are saved to localStorage
// On watchface startup, retrieve settings:
Pebble.addEventListener('ready', function() {
  console.log('PebbleKit JS ready!');
});

```

--------------------------------

### Radiogroup Configuration Example

Source: https://github.com/pebble/clay/blob/master/README.md

Example of a radiogroup configuration object. This defines a group of radio buttons where the user can select only one option. It requires a unique messageKey for data persistence and an array of options, each with a label and a value.

```javascript
{
  "type": "radiogroup",
  "messageKey": "favorite_food",
  "label": "Favorite Food",
  "options": [
    { 
      "label": "Sushi", 
      "value": "sushi" 
    },
    { 
      "label": "Pizza", 
      "value": "pizza" 
    },
    { 
      "label": "Burgers", 
      "value": "burgers" 
    }
  ]
}
```

--------------------------------

### Checkboxgroup Configuration Example

Source: https://github.com/pebble/clay/blob/master/README.md

Example of a checkboxgroup configuration object. This allows users to select multiple options from a list. It requires a messageKey defined with array syntax in package.json and an array of default boolean values corresponding to the options.

```javascript
{
  "type": "checkboxgroup",
  "messageKey": "favorite_food",
  "label": "Favorite Food",
  "defaultValue": [true, false, true],
  "options": ["Sushi", "Pizza", "Burgers"]
}
```

--------------------------------

### Button Configuration Example

Source: https://github.com/pebble/clay/blob/master/README.md

Example of a generic button configuration object. This component displays a button within the configuration interface, which can be styled as primary (orange) or secondary (gray). It includes a defaultValue for the button's displayed text.

```javascript
{
  "type": "button",
  "primary": true,
  "defaultValue": "Send"
}
```

--------------------------------

### Basic Configuration File Structure (JSON)

Source: https://github.com/pebble/clay/blob/master/README.md

An example of a basic configuration file ('config.json') for Pebble Clay. This JSON structure defines the elements and layout of the configuration page. Developers need to define all 'messageKeys' in their 'package.json' corresponding to these configurations.

```json
{
  "messageKeys": {
    "someKey": {
      "defaultValue": "some default value"
    }
  }
}
```

--------------------------------

### Handle Pebble Configuration Events Manually with Clay

Source: https://github.com/pebble/clay/blob/master/README.md

Example demonstrates how to manually handle 'showConfiguration' and 'webviewclosed' events in Pebble applications using the Clay library. It shows how to override default event handling, load platform-specific configurations, and send settings to the watch.

```javascript
var Clay = require('pebble-clay');
var clayConfig = require('./config');
var clayConfigAplite = require('./config-aplite');
var clay = new Clay(clayConfig, null, { autoHandleEvents: false });

Pebble.addEventListener('showConfiguration', function(e) {
  
  // This is an example of how you might load a different config based on platform.
  var platform = clay.meta.activeWatchInfo.platform || 'aplite';
  if (platform === 'aplite') {
    clay.config = clayConfigAplite;
  }
  
  Pebble.openURL(clay.generateUrl());
});

Pebble.addEventListener('webviewclosed', function(e) {
  if (e && !e.response) {
    return;
  }

  // Get the keys and values from each config item
  var dict = clay.getSettings(e.response);

  // Send settings values to watch side
  Pebble.sendAppMessage(dict, function(e) {
    console.log('Sent config data to Pebble');
  }, function(e) {
    console.log('Failed to send config data!');
    console.log(JSON.stringify(e));
  });
});
```

--------------------------------

### Basic Clay Initialization in JavaScript

Source: https://context7.com/pebble/clay/llms.txt

Demonstrates the fundamental setup for initializing Clay in your Pebble application's JavaScript file. It shows how to require the Clay library and the configuration JSON, and instantiate the Clay object. Clay automatically manages configuration events and settings transmission.

```javascript
var Clay = require('pebble-clay');
var clayConfig = require('./config.json');
var clay = new Clay(clayConfig);

// Clay automatically handles showConfiguration and webviewclosed events
// Settings are automatically transmitted to the watch when the user submits
```

--------------------------------

### Text Component Example (JavaScript)

Source: https://github.com/pebble/clay/blob/master/README.md

Shows the 'text' component, designed for displaying descriptive information or explanations. The 'defaultValue' property can contain plain text or HTML. Optional 'id', 'messageKey', 'capabilities', and 'group' properties are also available for advanced usage.

```javascript
{
  "type": "text",
  "defaultValue": "This will be displayed in the text element!",
}
```

--------------------------------

### ClayConfig API: Get Items and Serialize Settings (JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

Demonstrates how to retrieve configuration items from Clay using message keys, IDs, types, and groups. It also shows how to get all items and serialize the entire configuration into a JSON object. This is useful for accessing user-defined settings within a Pebble application.

```javascript
module.exports = function(minified) {
  var clayConfig = this;

  clayConfig.on(clayConfig.EVENTS.AFTER_BUILD, function() {
    // Get single item by messageKey
    var toggle = clayConfig.getItemByMessageKey('enable_feature');

    // Get single item by ID
    var heading = clayConfig.getItemById('main-heading');

    // Get all items of a specific type
    var allToggles = clayConfig.getItemsByType('toggle');
    allToggles.forEach(function(toggle) {
      console.log(toggle.messageKey, toggle.get());
    });

    // Get items by group
    var advancedSettings = clayConfig.getItemsByGroup('advanced');

    // Get all items
    var allItems = clayConfig.getAllItems();

    // Serialize all settings
    var settings = clayConfig.serialize();
    // Returns: {"messageKey1": {value: "val"}, "messageKey2": {value: true}}
  });
};
```

--------------------------------

### Programmatically Setting Clay Configuration (JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

Provides examples of how to programmatically set configuration values for a Clay instance. It shows how to set a single configuration option by its key and how to set multiple options simultaneously using an object. These settings are persisted in localStorage and loaded the next time the configuration page is opened.

```javascript
var Clay = require('pebble-clay');
var clayConfig = require('./config.json');
var clay = new Clay(clayConfig);

// Set single setting
clay.setSettings('username', 'john_doe');

// Set multiple settings
clay.setSettings({
  username: 'john_doe',
  theme: 'dark',
  notifications_enabled: true
});

// Settings persist in localStorage and are loaded on next config page open
```

--------------------------------

### Message Key Array Syntax Example (JavaScript)

Source: https://github.com/pebble/clay/blob/master/README.md

Demonstrates using array syntax with message keys for components that do not return arrays. This appends a zero-indexed position to the messageKey, allowing specific data points to be accessed with corresponding C code definitions.

```javascript
{
  "type": "toggle",
  "messageKey": "light_switch[1]",
  "label": "Invert Colors",
  "defaultValue": true
}
```

--------------------------------

### Clay Get Settings Default Behavior

Source: https://github.com/pebble/clay/blob/master/README.md

Illustrates the default behavior of `clay.getSettings()` which returns an object with numeric keys corresponding to message keys. This is contrasted with the behavior when `false` is passed as the second argument.

```javascript
Pebble.addEventListener('webviewclosed', function(e) {

  clay.getSettings(e.response);
    /* returns:
    {
      10000: 0,
      10001: 'Jane Doe',
      10002: 1
    }
    */

  clay.getSettings(e.response, false);
    /* returns:
    {
      BACKGROUND_COLOR: {value: 0},
      NAME: {value: 'Jane Doe'},
      ENABLE_TOOLS: {value: true}
    }

    Notice that the value for ENABLE_TOOLS was not converted to a number from a boolean
    */
});
```

--------------------------------

### ClayItem Manipulator: Get, Set, Show/Hide, Enable/Disable, and Events (JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

Illustrates how to interact with individual Clay configuration items, such as color pickers. It covers getting the current value, setting a new value (accepting strings or integers), toggling visibility, enabling/disabling the item, and listening for 'change', 'show', and 'hide' events. Methods are chainable for concise manipulation.

```javascript
module.exports = function(minified) {
  var clayConfig = this;

  clayConfig.on(clayConfig.EVENTS.AFTER_BUILD, function() {
    var colorPicker = clayConfig.getItemByMessageKey('bg_color');

    // Get current value
    var currentColor = colorPicker.get(); // Returns integer

    // Set new value
    colorPicker.set('FF0000'); // Set to red
    colorPicker.set(0xFF0000); // Also accepts integer

    // Show/hide
    colorPicker.hide();
    colorPicker.show();

    // Enable/disable
    colorPicker.disable();
    colorPicker.enable();

    // Listen for events
    colorPicker.on('change', function() {
      console.log('Color changed to:', this.get());
    });

    // Multiple events
    colorPicker.on('show hide', function(event) {
      console.log('Visibility changed');
    });

    // Methods are chainable
    colorPicker.set('0000FF').enable().show();
  });
};
```

--------------------------------

### Section Component Example (JavaScript)

Source: https://github.com/pebble/clay/blob/master/README.md

Illustrates the 'section' component, used for grouping related configuration items. It accepts an 'items' array containing the elements within the section and an optional 'capabilities' array to specify watch features required for the section's visibility.

```javascript
{
  "type": "section",
  "items": [
    {
      "type": "heading",
      "defaultValue": "This is a section"
    },
    {
      "type": "input",
      "messageKey": "email",
      "label": "Email Address"
    },
    {
      "type": "toggle",
      "messageKey": "enableAnimations",
      "label": "Enable Animations"
    }
  ]
}
```

--------------------------------

### Implement Custom Clay Configuration Logic - JavaScript

Source: https://github.com/pebble/clay/blob/master/README.md

Provides an example of a custom function that modifies Clay configuration based on events and user data. It includes event handling, item manipulation, and API requests.

```javascript
module.exports = function(minified) {
  var clayConfig = this;
  var _ = minified._;
  var $ = minified.$; 
  var HTML = minified.HTML;

  function toggleBackground() {
    if (this.get()) {
      clayConfig.getItemByMessageKey('background').enable();
    } else {
      clayConfig.getItemByMessageKey('background').disable();
    }
  }

  clayConfig.on(clayConfig.EVENTS.AFTER_BUILD, function() {
    var coolStuffToggle = clayConfig.getItemByMessageKey('cool_stuff');
    toggleBackground.call(coolStuffToggle);
    coolStuffToggle.on('change', toggleBackground);
    
    // Hide the color picker for aplite
    if (!clayConfig.meta.activeWatchInfo || clayConfig.meta.activeWatchInfo.platform === 'aplite') {
      clayConfig.getItemByMessageKey('background').hide();
    }
    
    // Set the value of an item based on the userData
    $.request('get', 'https://some.cool/api', {token: clayConfig.meta.userData.token})
      .then(function(result) {
        // Do something interesting with the data from the server
      })
      .error(function(status, statusText, responseText) {
        // Handle the error
      });
  });
  
};

```

--------------------------------

### Heading Component Example (JavaScript)

Source: https://github.com/pebble/clay/blob/master/README.md

Demonstrates the 'heading' component, used for creating titles within the configuration. It supports properties like 'id' for lookup, 'messageKey' for data persistence, 'defaultValue' for the heading text, and 'size' to control the text's HTML heading level (1-6).

```javascript
{
  "type": "heading",
  "id": "main-heading",
  "defaultValue": "My Cool Watchface",
  "size": 1
}
```

--------------------------------

### Configuration Page Structure with Sections in JSON

Source: https://context7.com/pebble/clay/llms.txt

Defines the structure of a configuration page using JSON for the Clay framework. This example showcases a hierarchical layout including headings, descriptive text, sections with nested items (like toggles and sliders), and a submit button. Each item is defined by its `type`, `defaultValue`, and relevant properties.

```json
[
  {
    "type": "heading",
    "defaultValue": "My Watchface Settings",
    "size": 1
  },
  {
    "type": "text",
    "defaultValue": "Configure your watchface colors and display options."
  },
  {
    "type": "section",
    "items": [
      {
        "type": "heading",
        "defaultValue": "Display Settings"
      },
      {
        "type": "toggle",
        "messageKey": "invert",
        "label": "Invert Colors",
        "defaultValue": true
      },
      {
        "type": "slider",
        "messageKey": "opacity",
        "defaultValue": 15,
        "label": "Background Opacity",
        "min": 0,
        "max": 100,
        "step": 5
      }
    ]
  },
  {
    "type": "submit",
    "defaultValue": "Save Settings"
  }
]
```

--------------------------------

### JavaScript: Function Declaration Style

Source: https://github.com/pebble/clay/blob/master/CONTRIBUTING.md

Illustrates the preferred style for JavaScript function declarations, avoiding double naming of functions for easier refactoring. This adheres to the project's specific style guide.

```javascript
// bad
var log = function log(msg) {
   console.log(msg);
 };

// good
var log = function(msg) {
   console.log(msg);
 };
```

--------------------------------

### Basic Config Structure (JavaScript)

Source: https://github.com/pebble/clay/blob/master/README.md

Defines the root element of a Pebble Clay configuration file, which must be an array. Each element within the array is an object representing a configuration item with properties to control its display. This example shows a heading and a text item.

```javascript
[
  {
    "type": "heading",
    "defaultValue": "Example Header Item"
  },
  {
    "type": "text",
    "defaultValue": "Example text item."
  }
]
```

--------------------------------

### JavaScript: Self Reference for 'this' Keyword

Source: https://github.com/pebble/clay/blob/master/CONTRIBUTING.md

Demonstrates the correct way to reference the 'this' keyword within nested functions using a 'self' variable, following the project's style guide. Avoids common pitfalls of using '_this' or 'that'.

```javascript
// bad
function() {
  var _this = this;
  return function() {
    console.log(_this);
  };
}

// bad
function() {
  var that = this;
  return function() {
    console.log(that);
  };
}

// good
function() {
  var self = this;
  return function() {
    console.log(self);
  };
}
```

--------------------------------

### Input Component with Validation in JSON

Source: https://context7.com/pebble/clay/llms.txt

Specifies a text input field within a Clay configuration page, defined in JSON. This example includes standard attributes like `label`, `description`, and `defaultValue`, along with HTML5 validation attributes like `placeholder`, `type` (set to 'email'), `required`, and `maxlength` for client-side input validation.

```json
{
  "type": "input",
  "messageKey": "email",
  "defaultValue": "",
  "label": "Email Address",
  "description": "We'll use this to send you notifications",
  "attributes": {
    "placeholder": "user@example.com",
    "type": "email",
    "required": "required",
    "maxlength": "50"
  }
}
```

--------------------------------

### Custom Function with API Requests (JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

Adds functionality to `custom-clay.js` to validate an API key by making a GET request to an external API upon user input. It updates a status text element based on the API response.

```javascript
module.exports = function(minified) {
  var clayConfig = this;
  var $ = minified.$;

  clayConfig.on(clayConfig.EVENTS.AFTER_BUILD, function() {
    var apiKeyInput = clayConfig.getItemByMessageKey('api_key');
    var statusText = clayConfig.getItemById('api-status');

    apiKeyInput.on('change', function() {
      var apiKey = this.get();

      $.request('get', 'https://api.example.com/validate', {key: apiKey})
        .then(function(result) {
          var response = JSON.parse(result);
          if (response.valid) {
            statusText.set('API Key Valid ✓');
          } else {
            statusText.set('API Key Invalid ✗');
          }
        })
        .error(function(status, statusText, responseText) {
          statusText.set('Connection Error: ' + status);
        });
    });
  });
};

```

--------------------------------

### Accessing Pebble Settings and Message Keys (JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

Shows how to retrieve configuration settings sent from a Pebble watchface or app, typically after a webview is closed. It explains how to get converted settings (using numeric message keys) and unconverted settings (using message key names). The code also demonstrates how to handle array-like settings and send processed settings back to the Pebble app.

```javascript
var messageKeys = require('message_keys');

Pebble.addEventListener('webviewclosed', function(e) {
  if (e && !e.response) {
    return;
  }

  // Get converted settings (default behavior)
  var settings = clay.getSettings(e.response);
  // Returns: { 10000: 1, 10001: "text", 10002: 16711680 }
  // Keys are numeric message key values

  console.log('Invert enabled:', settings[messageKeys.invert]); // 1 or 0
  console.log('Email:', settings[messageKeys.email]); // string
  console.log('Background:', settings[messageKeys.background_color]); // integer

  // Get unconverted settings
  var rawSettings = clay.getSettings(e.response, false);
  // Returns: { invert: {value: true}, email: {value: "test"} }
  // Booleans not converted, messageKey names used

  // Array handling example
  // For "notifications[3]" messageKey with [true, false, true]
  console.log(settings[messageKeys.notifications + 0]); // 1
  console.log(settings[messageKeys.notifications + 1]); // 0
  console.log(settings[messageKeys.notifications + 2]); // 1

  Pebble.sendAppMessage(settings,
    function() { console.log('Success'); },
    function(err) { console.log('Error:', JSON.stringify(err)); }
  );
});
```

--------------------------------

### Pass User Data to Pebble Clay Config Page (JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

This example demonstrates how to pass user-specific data to the Pebble Clay configuration page. The 'userData' object is passed during the Clay instance creation and can be accessed within the custom configuration function via 'clayConfig.meta.userData'. This allows for dynamic UI adjustments based on user information.

```javascript
var Clay = require('pebble-clay');
var clayConfig = require('./config.json');
var customFn = require('./custom-fn');

var userData = {
  apiToken: 'abc123xyz',
  userId: 12345,
  isPremium: true
};

var clay = new Clay(clayConfig, customFn, { userData: userData });

// In custom function, access via clayConfig.meta.userData
module.exports = function(minified) {
  var clayConfig = this;

  clayConfig.on(clayConfig.EVENTS.AFTER_BUILD, function() {
    console.log('API Token:', clayConfig.meta.userData.apiToken);
    console.log('User ID:', clayConfig.meta.userData.userId);

    if (!clayConfig.meta.userData.isPremium) {
      // Hide premium features
      clayConfig.getItemsByGroup('premium').forEach(function(item) {
        item.hide();
      });
    }
  });
};

```

--------------------------------

### Initialize Clay with Custom Configuration and User Data - JavaScript

Source: https://github.com/pebble/clay/blob/master/README.md

Shows how to initialize the Clay library with configuration and custom logic. It demonstrates requiring necessary modules and passing user data to the Clay constructor.

```javascript
var Clay = require('pebble-clay');
var clayConfig = require('./config');
var customClay = require('./custom-clay');
var userData = {token: 'abc123'}
var clay = new Clay(clayConfig, customClay, {userData: userData});

```

--------------------------------

### Initialize Clay Configuration (Node.js)

Source: https://github.com/pebble/clay/blob/master/README.md

This snippet shows how to initialize Clay in your main JavaScript file (index.js or app.js) for Pebble apps. It requires the 'pebble-clay' package and your configuration file (config.json or config.js), then creates a new Clay instance. Clay automatically handles configuration events.

```javascript
var Clay = require('pebble-clay');
var clayConfig = require('./config.json');
var clay = new Clay(clayConfig);
```

--------------------------------

### Platform-Specific Components (JSON)

Source: https://context7.com/pebble/clay/llms.txt

Demonstrates conditional rendering of components based on device capabilities like 'RECT', 'MICROPHONE', 'NOT_HEALTH', 'PLATFORM_CHALK', and 'ROUND'.

```json
// Only show for rectangular displays with microphone
{
  "type": "section",
  "capabilities": ["RECT", "MICROPHONE"],
  "items": [
    {
      "type": "text",
      "defaultValue": "Voice commands are available on this device"
    },
    {
      "type": "toggle",
      "messageKey": "voice_enabled",
      "label": "Enable Voice Commands",
      "defaultValue": false
    }
  ]
}

// Only show for devices WITHOUT health support
{
  "type": "text",
  "defaultValue": "Health tracking not available",
  "capabilities": ["NOT_HEALTH"]
}

// Only show for Pebble Time Round
{
  "type": "text",
  "defaultValue": "Round display detected",
  "capabilities": ["PLATFORM_CHALK", "ROUND"]
}
```

--------------------------------

### Manual Event Handling with Clay in JavaScript

Source: https://context7.com/pebble/clay/llms.txt

Illustrates how to manually handle Pebble's `showConfiguration` and `webviewclosed` events when using Clay. This approach provides more control, allowing for platform-specific configurations and custom logic for sending settings to the watch. It requires setting `autoHandleEvents` to `false` during Clay instantiation.

```javascript
var Clay = require('pebble-clay');
var clayConfig = require('./config.json');
var clay = new Clay(clayConfig, null, { autoHandleEvents: false });

Pebble.addEventListener('showConfiguration', function(e) {
  // Load different configs based on platform
  var platform = clay.meta.activeWatchInfo.platform || 'aplite';
  if (platform === 'aplite') {
    clay.config = require('./config-aplite');
  }

  Pebble.openURL(clay.generateUrl());
});

Pebble.addEventListener('webviewclosed', function(e) {
  if (e && !e.response) {
    return;
  }

  // Get the keys and values from each config item
  var dict = clay.getSettings(e.response);

  // Send settings values to watch side
  Pebble.sendAppMessage(dict, function(e) {
    console.log('Sent config data to Pebble');
  }, function(e) {
    console.log('Failed to send config data!');
    console.log(JSON.stringify(e));
  });
});
```

--------------------------------

### Clay Constructor - JavaScript

Source: https://github.com/pebble/clay/blob/master/README.md

Initializes a new Clay configuration instance. It accepts configuration data, an optional custom function, and options for event handling and user data. The custom function is executed within the context of the generated configuration page. Options can control automatic event handling and pass arbitrary user data.

```javascript
const clay = new Clay(config, customFn, options);

// Example with minimal configuration
const config = [
  {
    "type": "text",
    "messageKey": "name",
    "defaultValue": "",
    "label": "Name"
  }
];
const clayInstance = new Clay(config);

// Example with custom function and options
function myCustomFunction() {
  console.log("Custom function executed!");
}

const options = {
  autoHandleEvents: false,
  userData: { userId: 123 }
};

const clayWithOptions = new Clay(config, myCustomFunction, options);
```

--------------------------------

### Configure Select Dropdown in Pebble Clay

Source: https://github.com/pebble/clay/blob/master/README.md

Creates a dropdown menu for selecting one option from a predefined list in the Pebble configuration. The `options` property defines the available choices, each with a `label` and `value`.

```javascript
{
  "type": "select",
  "messageKey": "theme",
  "label": "Select Theme",
  "defaultValue": "dark",
  "options": [
    { "label": "Light", "value": "light" },
    { "label": "Dark", "value": "dark" },
    { "label": "High Contrast", "value": "contrast" }
  ]
}
```

--------------------------------

### Access Settings using Message Keys

Source: https://github.com/pebble/clay/blob/master/README.md

Shows how to retrieve settings from Clay using message keys, particularly after the change where `clay.getSettings()` returns an object with numeric keys by default. It demonstrates using the `message_keys` module to map numeric keys back to their string equivalents.

```javascript
var messageKeys = require('message_keys');

Pebble.addEventListener('webviewclosed', function(e) {
  // Get the keys and values from each config item
  var claySettings = clay.getSettings(e.response);

  // In this example messageKeys.NAME is equal to 10001
  console.log('Name is ' + claySettings[messageKeys.NAME]); // Logs: "Name is Jane Doe"
});
```

--------------------------------

### JavaScript: Polyfill for String.prototype.repeat

Source: https://github.com/pebble/clay/blob/master/dev/uri-test.html

Provides a fallback implementation for the `String.prototype.repeat` method in JavaScript environments where it might not be natively supported. It handles edge cases like non-negative counts and potential string size overflows. Dependencies include native JavaScript `String`, `TypeError`, `RangeError`, and `Math.floor`.

```javascript
if (!String.prototype.repeat) {
  String.prototype.repeat = function(count) {
    'use strict';
    if (this == null) {
      throw new TypeError('can\'t convert ' + this + ' to object');
    }
    var str = '' + this;
    count = +count;
    if (count != count) {
      count = 0;
    }
    if (count < 0) {
      throw new RangeError('repeat count must be non-negative');
    }
    if (count == Infinity) {
      throw new RangeError('repeat count must be less than infinity');
    }
    count = Math.floor(count);
    if (str.length == 0 || count == 0) {
      return '';
    }
    // Ensuring count is a 31-bit integer allows us to heavily optimize the
    // main part. But anyway, most current (August 2014) browsers can't handle
    // strings 1 << 28 chars or longer, so:
    if (str.length * count >= 1 << 28) {
      throw new RangeError('repeat count must not overflow maximum string size');
    }
    var rpt = '';
    for (;;) {
      if ((count & 1) == 1) {
        rpt += str;
      }
      count >>>= 1;
      if (count == 0) {
        break;
      }
      str += str;
    }
    return rpt;
  }
}
```

--------------------------------

### CloudPebble Configuration Root (JavaScript)

Source: https://github.com/pebble/clay/blob/master/README.md

For CloudPebble projects, this JavaScript snippet defines the root array element for your configuration file ('config.js'). This acts as the entry point for building the configuration page's layout and elements.

```javascript
module.exports = [];
```

--------------------------------

### Color Picker Components in JSON

Source: https://context7.com/pebble/clay/llms.txt

Demonstrates various configurations for the color picker component in Clay's JSON configuration. It includes a standard 64-color picker for color devices, a custom layout picker, and a black and white picker with gray support for Aplite devices. Each picker is defined by its `type`, `messageKey`, `defaultValue`, and `label`, with additional options like `sunlight` and `layout`.

```json
// Standard color picker with 64 colors for color Pebble devices
{
  "type": "color",
  "messageKey": "background_color",
  "defaultValue": "0000FF",
  "label": "Background Color",
  "sunlight": true
}

// Custom color picker layout
{
  "type": "color",
  "messageKey": "accent_color",
  "defaultValue": "FF0000",
  "label": "Accent Color",
  "sunlight": false,
  "layout": [
    [false, "FF0000", false],
    ["00FF00", "0000FF", "FFFF00"],
    [false, "FF00FF", false]
  ]
}

// Black and white picker for Aplite with gray support
{
  "type": "color",
  "messageKey": "text_color",
  "defaultValue": "000000",
  "label": "Text Color",
  "allowGray": true,
  "layout": "BLACK_WHITE"
}
```

--------------------------------

### JavaScript: Encoding and Embedding Data URI for iframe

Source: https://github.com/pebble/clay/blob/master/dev/uri-test.html

Demonstrates generating a large HTML string using the `repeat` method, encoding it with Base64, and embedding it into a data URI for an iframe. This showcases dynamic content creation and cross-origin communication bypass via data URIs. Dependencies include `encodeURIComponent`, `window.btoa`, and `document.write`.

```javascript
var test = encodeURIComponent(window.btoa('<html><body>' + '1 '.repeat(389550 / 2) + '</body></html>'));
alert(test.length);
document.write('<iframe src="data:text/html;base64,' + test + '">');
```

--------------------------------

### Register Custom Component with Pebble Clay (JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

This snippet shows how to define and register a custom UI component for use with Pebble Clay. It includes the component's template, styling, default values, and initialization logic. The 'custom-component.js' file defines the component, and 'app.js' registers it with the Clay instance.

```javascript
// custom-component.js
module.exports = {
  name: 'custom-rating',
  template: '<div class="custom-rating" data-manipulator-target>'
            +'<label>{{label}}</label>'
            +'<div class="stars" data-value="{{defaultValue}}"'>
            +'  <span data-star="1">☆</span>'
            +'  <span data-star="2">☆</span>'
            +'  <span data-star="3">☆</span>'
            +'  <span data-star="4">☆</span>'
            +'  <span data-star="5">☆</span>'
            +'</div></div>',
  style: '.custom-rating .stars span { cursor: pointer; font-size: 24px; }'
         +'.custom-rating .stars span.active { color: gold; }',
  manipulator: 'val',
  defaults: {
    label: 'Rating',
    defaultValue: 0
  },
  initialize: function(minified, clayConfig) {
    var self = this;
    var $ = minified.$; 

    this.$element.select('[data-star]').on('click', function(e) {
      var rating = e.target.getAttribute('data-star');
      self.set(rating);
      updateStars(rating);
    });

    function updateStars(rating) {
      self.$element.select('[data-star]').each(function(star, index) {
        if (index < rating) {
          star.classList.add('active');
        } else {
          star.classList.remove('active');
        }
      });
    }

    updateStars(this.get());
  }
};

// app.js
var Clay = require('pebble-clay');
var clayConfig = require('./config.json');
var customRating = require('./custom-component');
var clay = new Clay(clayConfig);

clay.registerComponent(customRating);

```

--------------------------------

### Migrate Toggle Component: appKey to messageKey

Source: https://github.com/pebble/clay/blob/master/README.md

Illustrates the migration of a toggle component's configuration from using `appKey` to `messageKey`. This change is necessary due to SDK updates and ensures compatibility with newer Clay versions.

```json
{
  "type": "toggle",
  "appKey": "invert",
  "label": "Invert Colors",
  "defaultValue": true
}
```

```json
{
  "type": "toggle",
  "messageKey": "invert",
  "label": "Invert Colors",
  "defaultValue": true
}
```

--------------------------------

### Select Menu Configuration (JavaScript)

Source: https://github.com/pebble/clay/blob/master/README.md

Defines a select menu for user input, supporting simple options or optgroups for categorized choices. This JSON structure is used within Pebble's Clay configuration.

```javascript
{
  "type": "select",
  "messageKey": "flavor",
  "defaultValue": "grape",
  "label": "Favorite Flavor",
  "options": [
    { 
      "label": "", 
      "value": "" 
    }, 
    {
      "label": "Fruits",
      "value": [
        { 
          "label": "Berry",
          "value": "berry" 
        },
        { 
          "label": "Grape",
          "value": "grape" 
        },
        { 
          "label": "Banana",
          "value": "banana" 
        }
      ]
    }, 
    {
      "label": "Candy",
      "value": [
        { 
          "label": "Chocolate",
          "value": "chocolate" 
        },
        { 
          "label": "Cream",
          "value": "cream" 
        },
        { 
          "label": "Lollipop",
          "value": "lollipop" 
        }
      ]
    }
  ]
}
```

--------------------------------

### Register Custom Component with Pebble Clay

Source: https://github.com/pebble/clay/blob/master/README.md

Demonstrates how to register a custom component with Pebble Clay after initializing Clay. This involves requiring the 'pebble-clay' library, your configuration file, and the custom component itself, then calling `clay.registerComponent()`.

```javascript
var Clay = require('pebble-clay');
var clayConfig = require('./config.json');
var clay = new Clay(clayConfig);

clay.registerComponent(require('./my-custom-component'));
```

--------------------------------

### Slider Component with Precision (JSON)

Source: https://context7.com/pebble/clay/llms.txt

Defines a slider component for setting temperature with a specific `step` of 0.25. It includes min/max values and a default value. Note the conversion to integer on the C side.

```json
{
  "type": "slider",
  "messageKey": "temperature",
  "defaultValue": 20.5,
  "label": "Temperature Threshold",
  "description": "Set the temperature in degrees Celsius",
  "min": -10,
  "max": 50,
  "step": 0.25
}
```

--------------------------------

### Button Component Click Handler with API Request (JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

Demonstrates how to implement a click handler for a 'button' type component within a Clay configuration. When the button is clicked, it disables itself, updates its text to 'Syncing...', and makes a POST request to a specified API endpoint. It then updates a status text element and resets the button based on the API response (success or error).

```javascript
// In config
{
  "type": "button",
  "id": "sync-button",
  "primary": true,
  "defaultValue": "Sync Now"
}

// In custom function
module.exports = function(minified) {
  var clayConfig = this;
  var $ = minified.$;

  clayConfig.on(clayConfig.EVENTS.AFTER_BUILD, function() {
    var syncButton = clayConfig.getItemById('sync-button');
    var statusText = clayConfig.getItemById('sync-status');

    syncButton.on('click', function() {
      this.disable();
      this.set('Syncing...');

      $.request('post', 'https://api.example.com/sync', {
        token: clayConfig.meta.accountToken
      })
        .then(function(result) {
          statusText.set('Sync complete!');
          syncButton.set('Sync Now');
          syncButton.enable();
        })
        .error(function() {
          statusText.set('Sync failed');
          syncButton.set('Retry');
          syncButton.enable();
        });
    });
  });
};
```

--------------------------------

### Custom Function with Dynamic Interactions (JavaScript)

Source: https://context7.com/pebble/clay/llms.txt

Implements custom logic in `custom-clay.js` to dynamically enable/disable and show/hide a background color picker based on a toggle's state. It also handles platform-specific hiding logic.

```javascript
// custom-clay.js
module.exports = function(minified) {
  var clayConfig = this;
  var _ = minified._;
  var $ = minified.$;

  function toggleBackgroundPicker() {
    var bgPicker = clayConfig.getItemByMessageKey('background_color');
    if (this.get()) {
      bgPicker.enable();
      bgPicker.show();
    } else {
      bgPicker.disable();
      bgPicker.hide();
    }
  }

  clayConfig.on(clayConfig.EVENTS.AFTER_BUILD, function() {
    // Get reference to toggle component
    var customBgToggle = clayConfig.getItemByMessageKey('custom_background');

    // Set initial state
    toggleBackgroundPicker.call(customBgToggle);

    // Listen for changes
    customBgToggle.on('change', toggleBackgroundPicker);

    // Hide color picker on black and white devices
    if (!clayConfig.meta.activeWatchInfo ||
        clayConfig.meta.activeWatchInfo.platform === 'aplite') {
      clayConfig.getItemByMessageKey('background_color').hide();
    }
  });
};

// app.js
var Clay = require('pebble-clay');
var clayConfig = require('./config.json');
var customClay = require('./custom-clay');
var clay = new Clay(clayConfig, customClay);

```

--------------------------------

### Process webviewclosed Response and Convert Values - JavaScript

Source: https://github.com/pebble/clay/blob/master/README.md

Demonstrates how to process a JSON response from webviewclosed and convert it into a format usable by Pebble's message keys. It shows the initial JSON structure and the subsequent conversion logic.

```javascript
// webviewclosed response
{
  "favorite_food": {"value": [1, 0, 1]},
  "cool_things_enabled": {"value": true},
  "user_name": {"value": "Jane Doe"},
  "date_of_birth[0]": {"value": 1989},
  "date_of_birth[1]": {"value": 11},
  "date_of_birth[2]": {"value": 28},
  "rating": {"value": 3.5, "precision": 1},
}

// resulting converted values

var messageKeys = require('message_keys');

messageKeys.favorite_food + 0 = 1;
messageKeys.favorite_food + 1 = 0;
messageKeys.favorite_food + 2 = 1;
messageKeys.cool_things_enabled = 1;
messageKeys.user_name = 'Jane Doe';
messageKeys.date_of_birth + 0 = 1989;
messageKeys.date_of_birth + 1 = 11;
messageKeys.date_of_birth + 2 = 28;
messageKeys.rating = 35;

```

--------------------------------

### Clay.setSettings - JavaScript

Source: https://github.com/pebble/clay/blob/master/README.md

Sets or updates application settings. This method can be used to set individual settings by key and value, or to update multiple settings at once by passing an object of key/value pairs. This is useful for pre-populating settings or modifying them programmatically.

```javascript
const config = [
  {
    "type": "text",
    "messageKey": "user_name",
    "defaultValue": ""
  },
  {
    "type": "toggle",
    "messageKey": "show_animations",
    "defaultValue": false
  }
];

const clayInstance = new Clay(config);

// Set a single setting
clayInstance.setSettings('user_name', 'Alice');

// Set multiple settings at once
clayInstance.setSettings({
  user_name: 'Bob',
  show_animations: true
});

// After setting, you might generate the URL to show the updated settings:
// const url = clayInstance.generateUrl();
// Pebble.openURL(url);
```

--------------------------------

### Clay.getSettings - JavaScript

Source: https://github.com/pebble/clay/blob/master/README.md

Retrieves settings from the response object provided by the 'webviewclosed' event. It can optionally convert settings values to be compatible with `Pebble.sendAppMessage()`. This includes converting booleans to numbers and handling numerical precision.

```javascript
Pebble.addEventListener('webviewclosed', function(e) {
  if (e.response) {
    const settings = Clay.getSettings(JSON.parse(e.response));
    console.log('Retrieved settings:', settings);
    // Example: settings might look like { enable_feature: 1 } if true

    // To send settings to the app:
    Pebble.sendAppMessage(settings);
  }
});

// Example response object structure:
// {
//   "name": "John Doe",
//   "age": 30,
//   "isStudent": true,
//   "score": 95.5,
//   "precisionExample": 12.345
// }

// With default conversion (convert=true):
// settings might be { name: 'John Doe', age: 30, isStudent: 1, score: 95.5, precisionExample: 12.345 }

// With precision option (if set in config, e.g., "precision": 2 for score):
// settings might be { name: 'John Doe', age: 30, isStudent: 1, score: 9550, precisionExample: 1234.5 } -> after flooring precisionExample: 1234

// To disable conversion:
// const rawSettings = Clay.getSettings(JSON.parse(e.response), false);

```

--------------------------------

### Select Dropdown with Option Groups (JSON)

Source: https://context7.com/pebble/clay/llms.txt

Defines a select dropdown component with nested option groups for 'Fruits' and 'Desserts'. It includes labels, values, and a default selection.

```json
{
  "type": "select",
  "messageKey": "favorite_flavor",
  "defaultValue": "chocolate",
  "label": "Favorite Flavor",
  "description": "Choose your preferred flavor",
  "options": [
    {
      "label": "-- Select One --",
      "value": ""
    },
    {
      "label": "Fruits",
      "value": [
        { "label": "Apple", "value": "apple" },
        { "label": "Banana", "value": "banana" },
        { "label": "Orange", "value": "orange" }
      ]
    },
    {
      "label": "Desserts",
      "value": [
        { "label": "Chocolate", "value": "chocolate" },
        { "label": "Vanilla", "value": "vanilla" },
        { "label": "Strawberry", "value": "strawberry" }
      ]
    }
  ]
}
```

--------------------------------

### JavaScript: Parse URL Parameter and Decode Data for Emulator

Source: https://github.com/pebble/clay/blob/master/dev/emulator.html

This JavaScript function retrieves a query parameter from the URL. It then decodes data from the URL hash, checking if it's base64 encoded. The decoded data, with a placeholder replaced, is used to construct a data URI for redirection. Dependencies include browser's `location` object and `window.atob`/`window.btoa` for base64 encoding/decoding.

```javascript
function getQueryParam(variable, defaultValue) {
    var query = location.search.substring(1);
    var vars = query.split('&');
    for (var i = 0; i < vars.length; i++) {
        var pair = vars[i].split('=');
        if (pair[0] === variable) {
            return decodeURIComponent(pair[1]);
        }
    }
    return defaultValue || null;
}

var returnTo = getQueryParam('return_to');
var data = decodeURIComponent(location.hash.substring(1));

// Check if we dealing with a base64 encoded URI
if (data && data.charAt(0) !== '<') {
    data = window.atob(data).replace('$$RETURN_TO$$', returnTo);
    window.location.href = 'data:text/html;base64,' + encodeURIComponent(window.btoa(data));
} else if (data) {
    data = data.replace('$$RETURN_TO$$', returnTo);
    window.location.href = 'data:text/html;charset=utf-8,' + encodeURIComponent(data);
}
```

--------------------------------

### Clay.generateUrl - JavaScript

Source: https://github.com/pebble/clay/blob/master/README.md

Generates a URL that can be used to open the Clay-generated configuration page. This URL is typically opened using `Pebble.openURL()`. It allows users to access and modify the application's settings through the web interface.

```javascript
const config = [
  {
    "type": "toggle",
    "messageKey": "enable_feature",
    "label": "Enable Feature",
    "defaultValue": false
  }
];

const clayInstance = new Clay(config);
const configUrl = clayInstance.generateUrl();

console.log("Configuration URL:", configUrl);
// Example usage with Pebble API:
Pebble.openURL(configUrl);
```

--------------------------------

### Module Path Requirement Change in Pebble SDK 3.13 (JavaScript)

Source: https://github.com/pebble/clay/blob/master/README.md

Illustrates the change in how modules are required in Pebble SDK 3.13 and later. Previously, module names were sufficient, but now paths relative to the current file are mandatory.

```javascript
require('./clay-config.json')
```