Enum Values

EMPS has a lightweight system for defining named sets of codes — enums. They are used throughout the application to translate codes (numeric or string) into human-readable labels, both on the server (PHP/Smarty) and on the client (Vue.js).

---

Defining Enums

Enums are defined in a plain text file:

modules/_common/config/enum.nn.txt

Each line defines one enum set in the format name:code=label;code=label;.... Codes can be integers or strings — whatever makes sense for the domain:

# Integer codes — leave gaps for future values
order_status:100=New;200=Processing;300=Completed;400=Cancelled
position_role:0=Guest;10=Linguist;20=Editor;50=Administrator;100=Project Manager

# Short string codes
vo_provider:aws=AWS;azure=Azure
section_type:p=Paragraph;q=Blockquote
confirmed:yes=Yes;no=No

# Locale codes (with dashes)
languages:en-US=English (US);en-GB=English (GB);ru-RU=Russian;de-DE=German

# Compound codes — numeric prefix controls sort order, string suffix is the key
billing_interval:0000_one=One time;0030_month=Month;0365_year=Year

# Empty label — the code itself carries the display value in context
billing_per:0000_one=;0030_month=/month;0365_year=/year

Conventions:

• For integer codes, use steps of 100 (or 10) to leave room for inserting new values later without renumbering.
• For string codes, choose short descriptive keys (aws/azure, p/q, yes/no).
• Compound codes like 0030_month are useful when you need both a stable string key and a predictable sort order — enum_val matches on the full string.
• A label can be empty if the code is used programmatically and no display label is needed in that enum set.
• Keep the label file neutral-language (nn) and add language-specific files (enum.en.txt, enum.ru.txt) if you need translations.
• The file is loaded once per request and cached internally by EMPS.

---

Using Enums in PHP / Smarty

Read a single label

$label = $emps->get_enum_value("order_status", $row['status']);
// e.g. "Processing"

Assign the full enum set to Smarty

$smarty->assign("order_statuses", $emps->get_enum("order_status"));

<select name="status">
    {{foreach $order_statuses as $item}}
        <option value="{{$item.code}}" {{if $row.status == $item.code}}selected{{/if}}>
            {{$item.value}}
        </option>
    {{/foreach}}
</select>

---

Using Enums in Vue.js

Loading enums

In your Vue mixin's mounted hook, load one or more enum sets into the component's enums data object:

data: function () {
    return {
        lst: [],
        row: {},
        enums: { order_status: [], payment_type: [] }  // pre-declare for Vue reactivity
    };
},
mounted: function () {
    EMPS.vue_load_enums(this, "order_status,payment_type");
}

Pre-declaring the enum arrays in data ensures Vue's reactivity system tracks them from the start. Adding a new key to an empty {} after mount works in Vue 2 with Vue.set, but pre-declaring is simpler and works correctly in both Vue 2 and Vue 3.

EMPS.vue_load_enums(component, "comma,separated,names") fetches each enum from /json/enum/?code=name and stores the result as this.enums["name"].

Displaying a label

Include the common_mixin (from /mjs/comp-mixins/common.js) which provides the enum_val method, then use it in templates:

<td>{{ enum_val('order_status', row.status) }}</td>

If the enum is not yet loaded or the code is not found, enum_val returns [no_enum] or [no_value] — useful for spotting missing definitions during development.

Rendering a <select> from an enum

<select v-model="row.status">
    <option v-for="item in enums['order_status']"
            :key="item.code"
            :value="item.code">
        {{ item.value }}
    </option>
</select>

Using a <selector> component

For enum-based selectors in admin interfaces, EMPS provides a built-in <selector> component. Include it on the page:

{{include file="db:_comp/selector"}}

<selector type="order_status" v-model="row.status"></selector>

---

Enum API Endpoint

Enums are served to the browser via a built-in JSON endpoint:

GET /json/enum/?code=order_status

Response:

{
  "code": "OK",
  "enum": [
    {"code": 100, "value": "New"},
    {"code": 200, "value": "Processing"},
    {"code": 300, "value": "Completed"},
    {"code": 400, "value": "Cancelled"}
  ]
}

---

Multiple Enum Files

If your project is large, you can split enums across multiple files and load the extras from your controller or webinit.php:

$emps->load_enums_from_file($emps->page_file_name("_common/config,enum_billing", "inc"));

All enum sets from all loaded files are merged into $emps->enum.