Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve Documentation for parseSchema in the Okta Sign-In Widget #3805

Open
dr-bizz opened this issue Mar 11, 2025 · 0 comments
Open

Improve Documentation for parseSchema in the Okta Sign-In Widget #3805

dr-bizz opened this issue Mar 11, 2025 · 0 comments

Comments

@dr-bizz
Copy link

dr-bizz commented Mar 11, 2025

Describe the feature request

Description

First, I want to express my appreciation for the Okta team’s excellent documentation—it has been incredibly helpful! However, while working on a recent project, I found that understanding all available options within the parseSchema function required extensive source code review. To improve the developer experience and reduce the need for source code exploration, I suggest enhancing the documentation by explicitly detailing key properties of parseSchema.

Suggested Documentation Enhancements

parseSchema Function
Currently, the documentation lacks detailed explanations of some useful properties within parseSchema. Below is an improved version that could serve as a reference for developers:

parseSchema: (schema, onSuccess) => {
  // This example demonstrates how to add an additional field to the registration form.
  schema.push({
    name: 'userProfile.address',
    type: 'text',
    placeholder: 'Enter your street address',
    maxLength: 255,
    label: 'Street Address',
    'label-top': true, // Moves label above the field
    required: true,
    tooltip: 'Tooltip message',
    readOnly: false,
    
    // If the field is a select or radio input, options can be specified.
    options: {
      optionOne: 'Option One',
      optionTwo: 'Option Two'
    },

    // Allows fields to be conditionally displayed based on other field values.
    // Note: This only applies a CSS-based visibility toggle. 
    // If the field is required, custom validation in `preSubmit` may be necessary.
    showWhen: {
      inputName: 'Value'
    },

    // More complex implementation using a function:
    showWhen: {
      'userProfile.country': (value) => value !== 'US'
    }
  });

  onSuccess(schema);
};

Additionally, it would be helpful to explicitly list and describe the available properties in the documentation. For example:

  • label-top: Determines whether the label appears above the field.
  • tooltip: Provides a helper message displayed on hover.
  • showWhen: Conditionally shows/hides a field based on another field’s value (CSS-only).
  • options: Defines selectable values for radio buttons or dropdowns.
  • autoRender: Model attributes change event to trigger rerendering of the input

Additional Resources
For developers who want to explore all available properties, it would be beneficial to reference the relevant source file directly in the documentation:
FormUtil.js

I would love to hear your thoughts! I’d be happy to contribute if needed.

New or Affected Resource(s)

https://github.com/okta/okta-signin-widget/blob/master/README.md

Provide a documentation link

No response

Additional Information?

No response

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant