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': The most generic type of modals. A modal of this type interacts very little with other page elements and thus can be viewed as a 'blank slate' of sort. 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
  • hide_mode
  • promptly_submit

Modal Lower Macro

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) 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. hidden (bool): ok_btn (str): hide_ok (bool): addi_btns (array): close_btn (str): hide_cancel (bool):