CuneiModal

CuneiModals are basically pop-up windows with pre-defined scripts and event handlers to make them work fluently with CuneiForms and CuneiTables. They are purely client-side constructs, so there are no needs to define and initiate them on the server side. It is, however, necessary for the server-side developer to anticipate their existence and, in most cases, their IDs in the server-side code. (See attributes in_modal of CuneiForms and in_modal/bound_modal of CuneiTables.)

Design & Pre-made Scripts

The process of putting up a CuneiModal is designed to be as straigtforward as possible, at least for the most common use cases (see notes on CuneiModal types below). All one has to do is to surround whatever that go in a modal with 2 extra lines of Jinja2 macros.

{{ CuneiModals.modal_upper_half("<ModalID>", ...) }}
    /* Modal content goes here. */
{{ CuneiModals.modal_lower_half("<ModalID>", ...) }}

Modal Upper Macro & Modal Object

This half of the CuneiModal macros takes care of creating the CuneiModal object and initiating the modal HTML elements up to the open tag of the <div> for modal-content.

modal_upper_half(modalid, type="table", title="Look up", 
				 class="primary", head_bg=false, size=false,
				 first_focus=false)

Parameters

DO NOT rely on argument order farther than modalid and type, ALWAYS PROVIDE argument keywords. modalid (str): The ID of the CuneiModal object and the modal <div>. type (str): The type or main function of the modal. This value determines the modal's interaction with other elements (both inside and outside of itself). The value can be one of: 'table': Used for search modals. Note that manually drawn search modals/tables are quite rare, since another wrapper macro draw_sctbs is used to draw all search modals en-masse. (See Multi-component Page.) 'form': Used for modals with a standalone form inside. A modal of this type submits its main form when the modal's OK button is clicked. 'exform': Used for modals holding extension parts of forms. This type of modals interacts very little with other page elements with only its show/hide routine linked with the form's navigation routine. 'modal': A blank slate. title (str): The modal header text. If this is an empty string or null, the resulting modal is drawn without the modal-header <div>. class and head_bg take the formats of class and custom_color arguments of CuneiForm's render_btn respectively. They dictates the colour of the table header as well as the color scheme of the full-form modal (when applicable). Note that, if both are given, head_bg takes precedence. size (str): The size of the modal can be specified as either: '' or null: Use the Bootstrap 4's default size. 'sm', 'lg', or 'xl': Use Bootstrap 4's modal-sm, modal-lg, or modal-xl class respectively. Any other string interpretable as a CSS size: Explicitly specify the width of the modal. first_focus (str): The ID of the element that should take the focus once the modal is shown. If not given, CuneiFox assumes the first focus element of the modal as follows: Table-typed modal: If the main table has any record, the first row gets the focus. Otherwise, the table header row gets the focus. Form-typed modal: The first unhidden and enabled field of the main form gets the focus.

Modal Object Attributes

Below is the list of and notes on modal object attributes:

• Basic Attributes
  • id (str): The ID of the CuneiModal.
  • self_type: Takes on the value 'modal'.
  • type: Takes on the value of type argument of the Jinja2 macro.

• Colours & Classes
  • head_class (false): (Obsolete)
  • ok_class (str): Specifies the class to be used by the modal's OK button. The Bootstrap class btn-<ok_class> is applied.

• References to Modal Elements
  • modal_ele: Points to the corresponding modal <div> DOM element.
  • ok_ele: Points to the modal's OK <button> element.
  • close_ele: Points to the modal's Cancel <button> element.
  • x_ele: Points to the modal's top-right X <button> element.
  • main_comp_obj: Points to the modal's main table or form object. (Only applies for form- and table-typed modals.)

• References to Other Elements
  • first_focus (str): Takes on the value of first_focus argument of the Jinja2 macro.
  • next_focus ([<field element>, <form object>] or false): Field to focus once the modal is shown. If both this attribute and first_focus are set, first_focus takes priority.
  • invoker (array): The information about the element that triggers the modal. This value is necessary for a modal to call the proper routine upon closing. This attribute takes the following format:
    • table-typed modals: ['form', <object:form object>, <int:field index>, <str:instant search column name>]
    • exform-typed modals: ['table', <object:table object>, null]
  • fillers (array): Works with invoker attribute for table-typed modals. This is the processed version of the invoker field's fill argument (see CuneiForm#String & Text Area Fields). Each member of the array is a 2-array [<int:field index>, <str:fill column>].

• Status Attributes
  • hold_modal (bool): Whether the modal is being prevented from closing, due to a dependent modal being shown.
  • release_modal (modal object or false): The modal that this exact one is depedent on. Once this modal is closed, the base modal held in this variable is released.
  • shown_status (bool): Whether the modal is in 'shown' state.
  • about_to_show (bool): Whether the modal is in 'show' state.
  • instant_trigger (bool): (Only applies to search modals.) Set to true just before the modal is shown. This attribute might look redundant with the previous two at first glance, but it marks the search modal as 'ready to be closed' within the quick-search routine of the invoking form.
  • post_fill_nav (str): Only applies to search modals. Dictates focus behaviour after the modal is closed. Its value is automatically set as a part of the invoker form's navigation routine and can be any of the values listed below:
    • 'f': Go forward in the invoker form's sequence, simulating a simple Tab ↹ on the invoker field.
    • 'r': Go backward in the invoker form's sequence, simulating a simple ⇧ Shift+Tab ↹ on the invoker field.
    • 'fe': Go forward in the invoker form's sequence, simulating a simple ↵ Enter on the invoker field.
    • 'fex': Immediately submit the invoker form.
    • 'n': Do nothing and let the browser handle the focus. (Usually the focus falls to the element clicked on just before the search modal is triggered.)
    • Other values: Put the focus back on the invoker field itself.
  • hide_mode (str): Indicates the nature of the modal's closing action. This attribute dictates the post-close behaviour of the modal.
    • 'ok': Implies that the user approves of the modal's state just before closing. (Usually means the modal's OK button is clicked.)
      • For a search modal: The selection result is requested and the modal will start filling the invoker form.
      • For a form modal: Skip closing the modal for now and submit the form first. Modal closing is handled by the form's submission routine once the submission request returns success.
    • 'qs': Implies that the invoking quick-search is successful and the modal might not even show in the first place. A modal closed in this mode will skip right to the form filling step.
    • 'plain': Nothing special here. Just close the modal.
    • 'cancel': Modal was closed via the Cancel button, the X button, the Esc key, or by clicking outside of the modal.
      • For a search modal: Fill relevant form fields with blanks.
      • For a form modal: If the form is the full-form of a table, also simulate a click on the table's Cancel button.
  • promptly_submit (bool): Only applies to search modals. Whether the modal is closed on a affirmative note ('ok' or 'qs' hide_mode) with successful result retrieval. The value is set to true if:
    • The invoking quick-search is successful. (The value flipping for this case is found twice in the code base. This is because some slower quick-search operations already have the modal opened while the quicker ones are realized as successful before that.)
    • The quick-search fails, but the subsequent selection result is successful.
    • (This value is reset to false after post-hide routines are finished.)

Modal Lower Macro

This lower half of the CuneiModal macros takes care of the closing tags of all modal's structural components and the closing script to finish the CuneiModal object.

modal_lower_half(modalid, class="success", head_bg=false, hidden=false,
				 ok_btn="OK", hide_ok=false, addi_btns=[],
				 close_btn="Close", hide_cancel=false)

Parameters

DO NOT rely on argument order farther than modalid and type, ALWAYS PROVIDE argument keywords. modalid (str): The ID of the CuneiModal object and the modal <div>. class and head_bg take the formats of class and custom_color arguments of CuneiForm's render_btn respectively. They dictates the colour of the table header as well as the color scheme of the full-form modal (when applicable). Note that, if both are given, head_bg takes precedence. In this lower half macro, both arguments affect the modal's OK and Cancel button. hidden (bool): Whether the modal footer element is hidden. ok_btn (str): The text within the OK button. hide_ok (bool): Whether the OK button is drawn. addi_btns (array): The array of specifications for additional buttons to show along side the OK and Cancel buttons. Each member is a 4-membered array: btnname (str): The short reference to the button. The real <button> element will have the ID '<modalid>-<btnname>btn'. btnlab (str): The text within the button. btnclass (str): The colour class of the button. (See valid options under CuneiForm#Buttons & Submits.) btncmd (str): The name of the function (arguments not supported) to run when the button is clicked. close_btn (str): The text within the Cancel button. hide_cancel (bool): Whether the Cancel button is drawn.