ดูต้นฉบับสำหรับ CuneiTable

CuneiTable is designed specifically to enable in-line data entry. Design-wise, it is more limited than CuneiForm since design flexibility is not highly expected from table-rype objects. In essence, CuneiTable is a wrapper for the accompanying CuneiForm, whether that form be the in-line type or the full expansion type.

== Define ==
Defining a CuneiTable is essentially declaring a CuneiForm with a few additional class variables. Below is an example of a very basic CuneiTable:

<syntaxhighlight lang="python" line="1">
class AccCodeTable(CuneiTable):
    MASTER_colsizes = [10, 20, 50, 20]
    MASTER_colnames = ["StID", "Account Code", "Account Name", "Account Group"]
    MASTER_coltypes = ["int", "str", "str", "sel"]
    MASTER_choicecols = ["accgrp"]
    MASTER_choices = [[
                         ("1", "Asset"),
                         ("2", "Liability"),
                         ("3", "Equity"),
                         ("4", "Revenue"),
                         ("5", "Expense")
                     ]]
    MASTER_firstonly = ["stid"]
    class SubForm(FlaskForm, CuneiSubForm):
        stid = StringField("StID")
        code = StringField("Code", validators=[InputRequired("Required!")])
        name = StringField("Name", validators=[InputRequired("Required!")])
        accgrp = SelectField("Group", default=1)
        def validate_stid(self, stid):
            # Validation goes here
</syntaxhighlight>

''The subclass '''SubForm''' is defined like the stripped down version of [[CuneiForm]]. Only put fields and validation logics here. All other behaviours are controlled by the MASTER variables from the CuneiTable level.''

'''NOTE THAT''' neither of the '''[[CuneiForm#Submit-delete Field Set|Submit-delete Field Set]]''' ('''{{code|submit}}''', '''{{code|is_del}}''', and '''{{code|del_submit}}''') is declared in the SubForm. These fields are taken care of automatically during CuneiTable initiation.

=== The Holy Trinity of CuneiTable ===
The 3 MASTER variables listed below are '''''required''''' for all CuneiTable classes.
* '''{{code|MASTER_colnames}}''' ''([str,])'': The list of column headers to appear on the page.
* '''{{code|MASTER_coltypes}}''' ''([str,])'': The list of column value types. Available types include:
** All types listed in the main article for [[CuneiForm#Available Types|CuneiForm]].
** '''{{code|lang=python|'str'}}''': Normal ''string'' value.
** '''{{code|lang=python|'check'}}''': Value represented by a checkbox.
** '''{{code|lang=python|'sel'}}''': Value with multiple choices. In other words, this is equivalent to a ''drop-list field'' in forms. In the same fashion, the displayed values for this type is not exactly the same as the values stored in the database. The raw value must pass through a map first before being displayed.
** '''{{code|lang=python|'rad'}}''': Similar to {{code|lang=python|'sel'}}, but this value type is represented by ''radio buttons'' in multiple sub-columns instead.
** '''{{code|lang=python|'submit'}}''', '''{{code|lang=python|'del_submit'}}''': ''Submit button.'' ''(Not handled manually, they are handled automatically during initiation.)''
* '''{{code|MASTER_colsizes}}''' ''([float/int,])'': The list of relative column sizes. CuneiFox will calculate the display sizes automatically.

'''NOTE #1:''' The member order in each of these lists follow the definition order of fields in the SubForm. '''DO CHECK''' that all of these 3 lists and the SubForm fields share the same length.

'''NOTE #2:''' On the client-side, a radio field ('''{{code|lang=python|'rad'}}''') is displayed as multiple sub-columns (one for each choice). Hence:
* The display headers of sub-columns are not dictated by the corresponding value in '''MASTER_colnames''', but by the values in '''MASTER_radios''' (Detailed in [[#Choices and Radios|a sub-section below]]) instead.
* The corresponding member in the '''MASTER_colsizes''' list is '''NOT''' merely ''one numerical value'', '''BUT''' a ''list of numerical values'' instead.

=== Choices and Radios ===
Columns with limited choices of predesignated values should utilize 'choice' or 'radio' representation; especially when the stored values must be mapped to another set of more readable or localizable display values. Ideally:
* Columns utilizing '''choice''' representation is typed {{code|lang=python|'sel'}} ({{code|lang=python|1= MASTER_coltypes[i] = 'sel'}}), and the corresponding field in the SubForm is a SelectField.
* Columns utilizing '''radio''' representation is typed {{code|lang=python|'rad'}} ({{code|lang=python|1= MASTER_coltypes[i] = 'rad'}}), and the corresponding field in the SubForm is a RadioField.

<syntaxhighlight lang="python">
MASTER_choicecols = [str choice_col0, str choice_col1, ...]
MASTER_choices    = [
                        [ (str col0_choice0, str col0_display0),
                          (str col0_choice1, str col0_display1),
                          ... ],
                        [ (str col1_choice0, str col1_display0),
                          (str col1_choice1, str col1_display1),
                          ... ],
                        ...
                    ]

MASTER_radiocols  = [str choice_col0, str choice_col1, ...]
MASTER_radios     = [
                        [ (str col0_choice0, str col0_display0),
                          (str col0_choice1, str col0_display1),
                          ... ],
                        [ (str col1_choice0, str col1_display0),
                          (str col1_choice1, str col1_display1),
                          ... ],
                        ...
                    ]
</syntaxhighlight>
''An example can be seen in the code [[#Define|at the top of the article]].''

'''NOTE #1:'''  Take care that '''MASTER_choicecols''' and '''MASTER_choices''' have the same length. Similarly for '''MASTER_radiocols''' and '''MASTER_radios'''.

'''NOTE #2:''' The SelectField and RadioField defined in the SubForm '''DOES NOT''' include the choices. (Again, see example [[#Define|at the top]].)

=== Search and Fill ===
Since the in-line form of a table is programmatically generated, the search-fill function cannot wait until the designing step like [[CuneiForm]]'s does. The search-fill function of an in-line form is defined in this step via the variable '''MASTER_schfill'''.

<syntaxhighlight lang="python">
MASTER_schfill = {
                     str search_col0: [str search_spec0, str fill_spec0],
                     str search_col1: [str search_spec1, str fill_spec1],
                     ...
                 }

# Example from Bank Account table
MASTER_schfill = {
                     "bank_code":    ["ModalBank:code",
                                      "bank_stid:stid,bank_name:name,bank_branch:branch"],
                     "acccode_code": ["ModalAccCode:code",
                                      "acccode_name:name,acccode_stid:stid"]
                 }
</syntaxhighlight>

'''NOTE:''' The formats of '''search_specX''' and '''fill_specX''' is similar to arguments ''search'' and ''fill'' in CuneiForm's '''[[CuneiForm#String & Text Area Fields|render_blank]]''' macro.

=== Instant Calculation ===
Instant calculation function within in-line forms, or 'instacalc', allows a change in one form field to initiate a small calculation request to the server and update other affected fields based on the calculation result. It is specified in the variable {{code|MASTER_instacalc}} '''of the CuneiTable.'''

''(Refer to [[CuneiForm#Instant Calculation|the dedicated sub-section in CuneiForm article]] for format and example.)''

=== Auto-numbering Function ===
In-line forms with auto-numbering specifications work with CuneiFox core system to serve auto running numbers in a particular format (usually for document numbers). The specifications for this feature are embedded within {{code|MASTER_autorun}} '''of the CuneiTable.'''

''(Refer to [[CuneiForm#Auto-numbering Function|the dedicated sub-section in CuneiForm article]] for format and example.)''

=== Table with a Separate Form Modal ===
Sometimes, the entries have either too many columns or columns not suitable for display in the table format. In such cases, developers can use the '''full-form''' option. CuneiTable with an associated full-form is only defined with essential columns for a 'quick glance' view. The full form is shown in a pop-up modal for entry addition/edit.

A CuneiTable can be linked to a full-form via the class variable '''MASTER_fullform''' which takes the following format:

<syntaxhighlight lang="python">
MASTER_fullform = [str module_code, str fullform_class_name,
                   str fullform_modal_header_text, str modal_size]

# Example from Product table
MASTER_fullform = ['cunei_iv', 'ProductFullForm', 'Product Information', 'xl']
</syntaxhighlight>
* '''size''' dictates the modal size displayed on the client-side. It utilizes BootStrap 4's {{code|lang=javascript|'modal-<size>'}} classes. Available choices are {{code|lang=python|'sm'}}, {{code|lang=python|'md'}} ''(corresponds to default modal size)'', {{code|lang=python|'lg'}}, and {{code|lang=python|'xl'}}.

'''NOTES''' on full-form class and macro:
* The CuneiForm class '''{{code|fullform_class_name}}''' must be found under '''{{code|module_code}}''' in the file {{code|cuneifox/<module_code>/forms.py}} or {{code|cuneifox/<module_code>/forms.pyc}}.
* The definition of the full-form class '''DOES NOT include the [[CuneiForm#Submit-delete Field Set|Submit-delete Field Set]]'''
* The Jinja2 macro for the full-form design must also be named '''{{code|fullform_class_name}}''' and must be found under '''{{code|module_code}}''' in the file {{code|cuneifox/<module_code>/template/<module_code>/form_macro.html}}.
* Refer to the main [[CuneiForm]] article for more details on form definition and design. For information specific the full-form macros, refer to [[#Full-form Macro|a dedicated sub-section]] below.

=== In-line Form with Expansion ===
Some tables contain just a tab too many columns, but not enough to warrant a fully-fledged separate form. In this case, CuneiTable allows its in-line form to have some fields drawn separately in an expansion modal. This behaviour is controlled by the variables '''MASTER_expand''', '''MASTER_tbexpand''', and '''MASTER_manualdraw'''.

<syntaxhighlight lang="python">
MASTER_expand = {str trigger_field0: str expand_spec0,
                 str trigger_field1: str expand_spec1,
                 ...}
MASTER_tbexpand = str expand_spec
MASTER_manualdraw = [str expand_field0, str expand_field1, ...]

# Example from the product table on the 'Product Delivery' page
MASTER_expand = {"product_code_mock":"BodyEx1:product_name"}
MASTER_tbexpand = "BodyEx1:product_name"
MASTER_manualdraw = ["product_code", "product_name", "desc", "manage_serial", "serial_nos"]
</syntaxhighlight>

* '''trigger_field''': The field with an ''Expand'' button {{code|lang=javascript|'<expand_modal_id>:<first_expand_field>'}} attached when the form is triggered.
* '''expand_spec''': The modal and field to focus on once the ''Expand'' button is presses. (Shares the format with the argument ''expand'' in CuneiForm's '''[[CuneiForm#String & Text Area Fields|render_blank]]''' macro.)
* '''expand_field''': The field to be skipped during dynamic in-line form generation. Fields listed in '''MASTER_manualdraw''' must be put on the page manually.

=== Injections & Post-submission Logics ===
Some columns, while not stored directly in the database, are quite essential, or at least useful, to display on the client-side table. In CuneiFox's normal operation, whether it be a data fetch request or a display table update after a database commission, the server returns (representation of) entries from within the database. This ensures the client-side is shown the most updated data, but it also means that columns not in the database do not show up by default. Variables '''MASTER_preserve_across''' and '''MASTER_inject_func''' seek to better this behaviour.

Employing a similar routine, variable '''MASTER_post_submit_func''' allows additional logic to be run after a database commit from a CuneiTable.

* '''{{code|MASTER_preserve_across}}''': (This feature is active ''AFTER SUBMISSION'') A list of field names, present in the in-line form but not in the database, whose values are read from the form and reinjected into the data sent to client for table manipulation.
* '''{{code|MASTER_inject_func}}''': (This feature is active ''ON SINGLE-ENTRY FETCH'') A list of functions (and their arguments) to run just before the fetched entry is sent to the client-side.
* '''{{code|MASTER_post_submit_func}}''': (This feature is active ''AFTER SUBMISSION'') A list of functions (and their arguments) to run just after a database commit. This feature is useful both for additional logic run and to modify the returned entry (in the same vein as ''inject_func'' does for a fetch request).

<syntaxhighlight lang="python">
MASTER_preserve_across = [str field_name0, str field_name1, ...]
MASTER_inject_func =      {'func': <function_object>,
                           'args': <list_of_ordered_arguments>}
MASTER_post_submit_func = {'func': <function_object>,
                           'args': <list_of_ordered_arguments>}

# Example from (former) tax ID table
MASTER_preserve_across = ["bcount"]
# Example from product group table
MASTER_inject_func = {"func":defvat_inject, "args":[]}
# Example from account book table
MASTER_post_submit_func = {"func":accbook_to_docseries, "args":[]}
</syntaxhighlight>

''' NOTE #1:''' ''preserve_across'' feature is automatically assumed for columns covered by CuneiModel's [[CuneiModel#Cross-table references|Cross-table references]]. There is no need to list such columns in ''MASTER_preserve_across''.

'''NOTE #2:''' At the time of writing, CuneiTable's injections & post-submission logics are handled automatically only on the [[#Shortcut Route for Single-table Page & Search Table]]''.

=== Other Table Definition Variables ===
Other notable MASTER variables that can be set upon form definition include:
* '''{{code|MASTER_firstonly}}''': A list of field names that are only active (editable) for a new entry, but inactive (not editable) when editing an old entry.
* '''{{code|MASTER_pseudohides}}''': A list of field names for which the corresponding fields are not rendered on form triggering.
* '''{{code|MASTER_delconfirm}}''': The specification for the delete confirmation modal. This value shares the format with the argument ''confirm_first'' in CuneiForm's '''[[CuneiForm#String & Text Area Fields|render_blank]]''' macro. The default value is {{code|lang=python|['This will delete...', 'code']}}

<syntaxhighlight lang="python">
MASTER_firstonly = [str field_name0, str field_name1, ...]
MASTER_pseudohides = [str field_name0, str field_name1, ...]
MASTER_delconfirm = [str confirm_modal_header, str field_name_to_confirm]

# Example from account code table
MASTER_firstonly = ["stid"]
# Example from journal setting table
MASTER_pseudohides = ["book", "colspec"]
# Example from Accounting Journal's VAT table
MASTER_delconfirm = ["This will delete...", "taxdoc"]
</syntaxhighlight>

== Initiate ==
CuneiTable class has its own {{code|__init__}} function.

'''{{code|lang=python|1= __init__(self, prefix="", **kwargs)}}'''

{| style="margin-left:20px;"
|- style="vertical-align:top;"
| style="width:120px;" | '''Parameters''' ||
* '''prefix''' ''(str)'': This value is reflected in CuneiForm's {{code|_id}} attribute during initiation. It is also used as the basis to name corresponding forms, modals, and other elements.
* '''Other keyword arguments''': See notes under sections below.
|}

The rough step-by-step of a CuneiTable's initiation is as follows:
# Assign the following MASTER variables to corresponding attributes of the CuneiTable instance (if the attributes are not specified otherwise):
#* [[#Search and Fill|Search and fill group]]
#* [[#In-line Form with Expansion|Expansion form group]]
#* [[#Injections & Post-submission Logics|Injection & post-submission group]]
#* [[#Other Table Definition Variables|Miscellaneous masters]]
# Modify the full-form class with [[#Standard Column Set|standard field set]], initiate the full-form, and modify the form instance's attributes (where applicable).
# Modify the in-line ''SubForm'' class with [[#Standard Column Set|standard field set]], initiate the in-line form, and modify the form instance's attributes.
# Assign the [[#Choices and Radios|choice and radio]] MASTER variables to corresponding attributes of the CuneiTable instance (if the attributes are not specified otherwise). Then, use the attributes to modify the choices of the in-line form fields.
# Add values corresponding to the [[#Standard Column Set|standard column set]] to the [[#The Holy Trinity of CuneiTable|3 main MASTERs]].

=== Standard Column Set ===
CuneiTable requires a few standard columns in order to function properly. These columns need not be defined explicitly, but are programmatically generated and integrated into all CuneiTable instances. The 4 standard columns include:
* '''id, submit, is_del''': These columns correspond to the [[#Submit-delete Field Set]] of the corresponding in-line form or full-form. Developers can also choose to explicitly define these columns in the class definition ''(especially the '''id''' column)'' if they desire.
* '''The multi-selection column''': This column is only created for a table with multi-selection enabled. It is displayed as the leftmost column of the table. (See the note on '''multi''' attribute below.)

=== Column Sizes & Post-init Modification ===
assign_csize
tune_cols

=== Notes on Keyword Arguments ===

== Design & Pre-made Scripts ==


=== Full-form Macro ===

=== Form Expansion Modal ===

== Notable Sub-routines ==

== Useful Server-side Patterns ==

=== Shortcut Route for Single-table Page & Search Table ===


{{The Tenko Shrine}}