Create Programmatic Dynamic Forms

Graph Studio allows you to programmatically create dynamic forms using the Java (PGX) and Python (PGX) interpreters.

You can pass dynamic values (such as variables, arrays, and so on) through Java or Python code to generate dynamic forms.

As a prerequisite step, you must first import the context that allows you to display the forms and define your own variable name and instantiate your context.

• %java-pgx
• %python-pgx

import oracle.datastudio.interpreter.common.context.JavaDataStudioContext
JavaDataStudioContext ds = interpreter.getJavaDataStudioContext()

from ds_interpreter_client.context.ds_context import PyDataStudioContext
ds = PyDataStudioContext()

The ds context allows you to display the forms and define your own variable name.

The following steps describe the programmatic creation of the Textbox, Select, Select Multiple, Slider, Checkbox, Date Picker, Time Picker, and DateTime Picker forms. It is important to note that only when you run the notebook paragraph with the dynamic form value (or the default value), then the values are persisted on page reload.

• Create a Textbox dynamic form which allows you to input any string of characters.

  • %java-pgx
  • %python-pgx

  ds.textbox("<name>", "<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • default_value (optional): The default value that is given to the dynamic form when it is first created.

  For example:

  

  Description of the illustration java_text_box.png

  ds.textbox(name="<name>", default_value="<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • default_value (optional): The default value that is given to the dynamic form when it is first created.

  For example:

  

  Description of the illustration python_text_box.png

• Create a Select dynamic form which allows you to select a value from a drop-down menu.

  • %java-pgx
  • %python-pgx

  import oracle.datastudio.common.forms.ParamOption
  List<ParamOption<String>> options = new ArrayList<>()
  options.add(new ParamOption<>("<option_value_a>", "<option_label_a>"))
  options.add(new ParamOption<>("<option_value_b>", "<option_label_b>"))
  ds.select("<name>", options, "<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • default_value (optional): The default value that is given to the dynamic form when it is first created.

  For example:

  

  Description of the illustration java_select.png

  options = [("<option_value_a>", "<option_label_a>"),("<option_value_b>", "<option_label_b>")]
  ds.select(name="<name>", options=options, default_value="<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • default_value (optional): The default value that is given to the dynamic form when it is first created.

  For example:

  

  Description of the illustration python_select.png

• Create a Select Mulitple dynamic form which allows you to select one or more values from a drop-down list.

  • %java-pgx
  • %python-pgx

  List<ParamOption<String>> options = new ArrayList<>();
  options.add(new ParamOption<>("<option_value_a>", "<option_label_a>"));
  options.add(new ParamOption<>("<option_value_b>", "<option_label_b>"));
  List<String> defaultValues = new ArrayList<>();
  defaultValues.add("<default_value>");
  ds.selectMultiple("<name>", options, defaultValues, "<label>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • label (optional): The label that is displayed on top of the dynamic form.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be one of the option values.

  • An option comprises option_value and option_label. The option_value is used to reference which default_value should be selected, and the (optional) option_label is displayed in the drop-down list.

  • An option_value can be either a string or a numeric value.

    • Options are separated with the | character in parsed forms.

  For example:

  

  Description of the illustration java_multiple_select.png

  options = [('<option_value_a>', '<option_label_a>'),('<option_value_b>', '<option_label_b>')]
  ds.select_multiple(name='<name>', options=options, default_value=['<default_value>'], label='<label>')

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • label (optional): The label that is displayed on top of the dynamic form.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be one of the option values.

  • An option comprises option_value and option_label. The option_value is used to reference which default_value should be selected, and the (optional) option_label is displayed in the drop-down list.

  • An option_value can be either a string or a numeric value.

    • Options are separated with the | character in parsed forms.

  For example:

  

  Description of the illustration python_multiple_select.png

• Create a Slider dynamic form which allows you to choose a number from a given range.

  • %java-pgx
  • %python-pgx

  ds.slider("<name>", <minimum>, <maximum>, <step_size>, <default_value>)

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • minimum: The minimum value of the slider. Must be a number.

  • maximum: The maximum value of the slider. Must be a number.

  • step_size: The step size of the slider. Must be a number and divider of (maximum - minimum).

  • default_value (optional): The default value that is given to the dynamic form when it is first created (minimum <= default_value <= maximum).

  For example:

  

  Description of the illustration java_slider.png

  ds.slider(name="<name>", min=<minimum>, max=<maximum>, step=<step_size>, default_value=<default_value>)

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • minimum: The minimum value of the slider. Must be a number.

  • maximum: The maximum value of the slider. Must be a number.

  • step_size: The step size of the slider. Must be a number and divider of (maximum - minimum).

  • default_value (optional): The default value that is given to the dynamic form when it is first created (minimum <= default_value <= maximum).

  For example:

  

  Description of the illustration python_slider.png

• Create a Checkbox dynamic form which allows you to select one or multiple values.

  • %java-pgx
  • %python-pgx

  import oracle.datastudio.common.forms.ParamOption
  
  List<ParamOption<String>> options = new ArrayList<>()
  options.add(new ParamOption<>("<option_value_a>", "<option_label_a>"))
  options.add(new ParamOption<>("<option_value_b>", "<option_label_b>"))
  List<String> defaultValues = new ArrayList<>()
  defaultValues.add("<default_value>")
  ds.checkbox("<name>", options, defaultValues)

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be one of the option values:

  • An option comprises option_value and option_label. The option_value is used to reference which default_value should be selected, and the (optional) option_label is displayed in respective boxes created by a checkbox.

  • An option_value can be either a string or a numeric value.

    • Options are separated with the | character in parsed forms.

  For example:

  

  Description of the illustration java_checkbox.bmp

  options = [("<option_value_a>", "<option_label_a>"),("<option_value_b>", "<option_label_b>")]
  ds.checkbox(name="<name>", options=options, default_value=["<default_value>"])

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be one of the option values:

  • An option comprises option_value and option_label. The option_value is used to reference which default_value should be selected, and the (optional) option_label is displayed in respective boxes created by a checkbox.

  • An option_value can be either a string or a numeric value.

    • Options are separated with the | character in parsed forms.

  For example:

  

  Description of the illustration python_checkbox.png

• Create a Date Picker dynamic form which allows you to select a date.

  • %java-pgx
  • %python-pgx

  ds.datePicker("<name>", "<date_format>", "<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • date_format (optional, recommended): The date format that is used for displaying the selected date in the input field and for formatting the resulting date when the paragraph is run.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be specified according to the date_format or in yyyy-MM-dd format if the date_format is not provided.

  For example:

  

  Description of the illustration java_date.png

  ds.date_picker(name="<name>", format="<date_format>", default_value="<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • date_format (optional, recommended): The date format that is used for displaying the selected date in the input field and for formatting the resulting date when the paragraph is run.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be specified according to the date_format or in yyyy-MM-dd format if the date_format is not provided.

  For example:

  

  Description of the illustration python_date_picker.png

• Create a Time Picker dynamic form which allows you to select a time.

  • %java-pgx
  • %python-pgx

  ds.timePicker("<name>", "<time_format>", "<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • time_format (optional, recommended): The time format that is used for displaying the selected time in the input field and for formatting the resulting time when the paragraph is run.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be specified according to the time_format or in HH:mm format if the time_format is not provided.

  For example:

  

  Description of the illustration java_time.png

  ds.time_picker(name="<name>", format="<time_format>", default_value="<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • time_format (optional, recommended): The time format that is used for displaying the selected time in the input field and for formatting the resulting time when the paragraph is run.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be specified according to the time_format or in HH:mm format if no time_format is provided.

  For example:

  

  Description of the illustration python_time_picker.png

• Define a DateTime Picker dynamic form which allows you to select a date and a time.

  • %java-pgx
  • %python-pgx

  ds.dateTimePicker("<name>", "<dateTime_format>", "<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • dateTime_format (optional, recommended): The dateTime format that is used for displaying the selected date and time in the input field and for formatting the resulting date and time when the paragraph is run.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be specified according to the dateTime_format or in yyyy-MM-dd HH:mm format if the dateTime_format is not provided.

  For example:

  

  Description of the illustration java_date_time.png

  ds.date_time_picker("<name>", format="<dateTime_format>", default_value="<default_value>")

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • dateTime_format (optional, recommended): The dateTime format that is used for displaying the selected date and time in the input field and for formatting the resulting date and time when the paragraph is run.

  • default_value (optional): The default value that is given to the dynamic form when it is first created. It must be specified according to the dateTime_format or in yyyy-MM-dd HH:mm format if the dateTime_format is not provided.

  For example:

  

  Description of the illustration python_date_time_picker.png

Customize Dynamic Form Layout

You can use the columnSpan and nextRow parameters to enhance data entry and readability in dynamic form layouts.

The layout of a dynamic form is based on a 12-column grid. By default, each form spans four columns, allowing up to three forms per row. When the total column width exceeds 12, forms automatically wrap to the next row. The layout is responsive:

• Small screens: Forms collapse to four columns (one form per row).

• Medium screens: 8-column grid (two forms per row).

• Large screens: Full 12-column grid (three forms per row).

As a prerequisite step, you must first import the context that allows you to display the forms and define your own variable name and instantiate your context.

• %java-pgx
• %python-pgx

import oracle.datastudio.interpreter.common.context.JavaDataStudioContext
JavaDataStudioContext ds = interpreter.getJavaDataStudioContext()

from ds_interpreter_client.context.ds_context import PyDataStudioContext
ds = PyDataStudioContext()

• The following example describes how to programmatically create a half-width Textbox (6 columns):

  • %java-pgx
  • %python-pgx

  ds.textbox("<name>", "<defaultValue>", <"label">, <columnSpan> )

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form if no <label> is set. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • defaultValue (optional): The default value that is given to the dynamic form when it is first created.

  • label (optional): The label that is displayed on top of the dynamic form.

  • columnSpan: Number of columns (out of 12) a form occupies. The default value is four (three forms per row).

  For example:

  

  Description of the illustration df_colspan_java.png

  ds.textbox(name="<name>", default_value="<default_value>", label="<label>", column_span="<column_span_value>"))

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form if no <label> is set. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • default_value (optional): The default value that is given to the dynamic form when it is first created.

  • label (optional): The label that is displayed on top of the dynamic form.

  • column_span: Number of columns (out of 12) a form occupies. The default value is four (three forms per row).

  For example:

  

  Description of the illustration df_colspan_python.png

• The following example describes how to programmatically create a form on a new row:

  • %java-pgx
  • %python-pgx

  ds.textbox("<name>", "<defaultValue>", <"label">, <columnSpan>, <nextRow> )

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form if no <label> is set. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • defaultValue (optional): The default value that is given to the dynamic form when it is first created.

  • label (optional): The label that is displayed on top of the dynamic form.

  • columnSpan: Number of columns (out of 12) a form occupies. The default value is four (three forms per row).

  • nextRow: A boolean parameter that determines if the form should start on a new row or not. Note that you must explicitly set columnSpan when using nextRow.

  For example:

  

  Description of the illustration df_nextrow_java.png

  ds.textbox(name="<name>", default_value="<default_value>", label="<label>", column_span="<column_span_value>, next_row="<next_row_value>"))

  In the preceding code:

  • name: The name of the dynamic form. It is displayed on top of the dynamic form if no <label> is set. If you want to reference a dynamic form multiple times in a paragraph, you can assign the same name to do so and it will only be displayed once.

  • default_value (optional): The default value that is given to the dynamic form when it is first created.

  • label (optional): The label that is displayed on top of the dynamic form.

  • column_span: Number of columns (out of 12) a form occupies. The default value is four (three forms per row).

  • next_row: A boolean parameter that determines if the form should start on a new row or not.

  For example:

  

  Description of the illustration df_nextrow_python.png