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.
|
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.
- head_class (
- 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.)
- modal_ele: Points to the corresponding modal
- 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>]
orfalse
): 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]
- table-typed modals:
- 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
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.
|