Note. UF/BrowserUI is currently being upgraded to Vercengen. Please continue using that library until full migration.
- To view all Documentation as a single-page, see the related page Vercengen (Full Documentation).
Main article(s): Vercengen TODO
Vercengen is a class-based frontend software engine that integrates both boostrap CSS + HTML/JS into a single coherent framework that requires coding in only JSON5/JSOL (Javascript Object Literals) for rapid prototyping. For more information, see Vercengen.
All interfaces are stored in main.vercengen, though bindings are not. The default JS Object for all Vercengen functions is ve, i.e. ve.addClass("<class_key>", { … });. The default CSS identifier is [ve=true] on the outermost parent. Additionally, all Vercengen Instances and attached Interfaces are given unique numeric IDs. Although code is salvaged from UF/BrowserUI, ve is effectively a total overhaul of it with JSON5DSL support. Any missing boilerplate is auto-generated.
Note. JS-level function binding for constructing and modifying Vercengen UIs are still under construction. Parental boilerplate is always auto-generated; i.e. you should only use Classes if you intend on using multiple instances of it or have a good reason to do so.
¶ 1. Classes and Inheritance
main.vercengen.classes: (Object)
- <class_key>: (Object)
- class_interface: (Object, WindowDictionary) - Interface for managing class-wide state.
- constructor: (Function) - The constructor to be called upon instance initialisation. Takes in named parameters via
arg0_options.
- inherits: (List<String>) - The classes the current Class inherits.
- interface: (Object, WindowDictionary) - Interface for managing instance-based state.
- namespace: (String) - Determines where in
main class instances should be saved as an Object dictionary.
- class_render: (Function) - The function to use for class-wide rendering. Special function.
- class_state: (Function/Object) - Serves as the main constructor for the Class, defining class-wide variables.
- instance_render: (Function) - The function to use for instance rendering. Special function.
- instance_state: (Function/Object) - Serves as the main constructor for any Class instances, defining instance-wide variables.
Classes with a set .inherits field inherit parental attributes via Object smart-merging. This means that lower Classes override the most nested objects only by default unless specified by an object-specific .override flag, which prunes off inherited attributes at and beneath that level.
Inherits Effects from JSON5DSL.
(Object, Effect): ve.parseEffect(arg0_element, arg1_options)
- close_ui: (List<String>)
- hide_component: (List<String>)
- new_instance: (Object)
- class: (String)
- display_interface: (Boolean) - Optional. Whether to display the attached interfaces for the new instance. False by default.
- options: (Function/Object) - Functions must return a type Object to use for the constructor.
- open_modal: (String) - Opens a popup modal in the centre of the screen. This is basically a Window that is pinned and anchored to the centre.
- open_modal: (Object) - Opens up a Modal. (See 6. Tooltips and Modals for more information).
- type: (String) - Determines the type of Modal to fire.
- onload: (Function) - The function to be executed upon modal load.
- special_function: (Function) - The function that is executed upon modal confirmation.
- open_ui: (List<String>)
- reload: (Boolean) - Reloads any present interface attached.
- reload_recursively: (Boolean) - Reloads any present interface attached and all of its dependents.
- show_component: (List<String>)
Inherits Limits from JSON5DSL.
(Object, Limit): ve.parseLimit(arg0_element, arg1_options)
- and_<key>/or_<key>/not_<key>/xor_<key>: (Object)
- and_<key>/or_<key>/not_<key>/xor_<key>: (Object)
- is_ui_open: (List<String>)
- not_is_ui_open: (List<String>)
(Object, WindowDictionary)
- <window_key>: (Object, Window)
- can_rename: (Boolean)
- on_rename: (Function)
- on_rename_effect: (Object, Effect)
- name: (String)
- can_close: (Boolean)
- close_on_outside_click: (Boolean)
- css_class: (String) - The CSS class to apply to windows. .ve-dark by default.
- draggable: (Boolean)
- resizeable: (Boolean)
- header_components: (Object, Row) - Used to attach header components anchored to the right of the header, typically for the purposes of icons such as pins, bookmarks, etc.
- …
- position_at_cursor: (Boolean) - Optional. False by default. When this flag is false, it attempts to position at a fallback (top right, 1rem, 1rem by default if unspecified).
- height: (Number/String) - Attempts to display all content by default.
- width: (Number/String) - 20rem by default.
- bottom: (Number/String) - Bottom in rem. Uses CSS's
calc if a number is not provided.
- left: (Number/String) - Left in rem. Uses CSS's
calc if a number is not provided.
- right: (Number/String) - Right in rem. Uses CSS's
calc if a number is not provided.
- top: (Number/String) - Top in rem. Uses CSS's
calc if a number is not provided.
- tabs: (Object, PaneDictionary)
- <pane_key>: (Object, Pane)
<pane_key>: (Object, Pane) - Note that there can be class-wide panes as well.
- anchor: (String) - Optional. Used to define a custom HTML container. Panes are instantiated via Windows by default.
- css_class: (String) - Optional. The CSS class to apply.
- group: (List<String>) - Used for grouping context menus together. This allows for dynamic X offsets from previous context menus instantiated upon cursor clicks.
- order: (Number) - The order the pane should be in within the group. Sequential by default.
- name: (String, Localisation) - The name of the pane. Used for displaying
.tabs if relevant from the preceding window.
- interface_<key>: (Object, Interface)
- tooltip: (Object, Tooltip/String, Localisation)
- onclick: (Function)
- onhover: (Function)
- onload: (Function) - Note. If
.onload returns a type (Object), it will be used to populate the Pane and replace current content.
(Object, Interface):
- defines: (Object) - Stores any constant reference variables.
- effect: (Object, Effect) - The effect to execute upon interface load.
- limit: (Function/Object, Limit) - The limit under which to actually display this interface. Disables the interface if not fulfilled, making it invisible.
- blank_<key>: (Boolean) - Used to specify a separator gap if necessary.
- <folder_key>: (Object, Folder)
- <folder_key>: (Object, Folder) - Allows for nested folders.
- css_class: (String) - Optional.
- is_collapsible: (Boolean) - Optional. Whether the given folder is collapsible. True by default. False by default if there is only one folder in the entire Interface, in which case the folder will not show.
- is_tab: (String) - Optional. Whether the given folder is a tab. If so, it should match
<row_key>, which will turn into a Tab Row with nested Interfaces underneath. If it does not match a <row_key>, a new Tab Row is created to house all folders with this .is_tab field.
- name: (String) - The name of the folder. Allows for minimisation.
- <row_key>: (Object, Row)
- css_class: (String) - Optional.
- name: (String) - Optional. Specifies a first label for this row.
- <component_key>: (Object, Component)
- <component_key>: (Object, Component) - If no preceding Row is specified, a separate row for only this Component is created.
- <interface_key>: (Object, Interface) - Allows for nested interfaces.
- <row_key>: (Object, Row)
Port over Components from BrowserUI and turn Hierarchies/FileExplorer into a type of class-based Component.
Note. The Object, Component class is determined by the .type annotation next to it, not by the PascalCased class name of that component. For the purposes of brevity, Component Documentation pages are linked and split off from main Documentation.
(Object, Component): All subsequent classes inherit these properties.
- id: (String) - Overrides component_key when fetching state for this Class/Instance.
- name: (String, Localisation) - Optional. The label to attach to this component.
- css_class: (String) - Optional.
- defines: (Object) - Stores any constant reference variables.
- disabled: (Boolean) - Optional. Whether the given component is for display only. False by default.
- do_not_change: (Boolean) - Whether the binding should not be changed immediately upon user changed upon user change. False by default.
- type: (String) - Determines the Component's
.type (see 5. Components for more information).
- variable: (Variable) - The binding/variable the read output should be bound to. Also populates the default placeholder accordingly.
- attributes: (Object) - Passes down any attributes specified to the Component.
- <attribute_key>: (Variable)
- height: (Number) - Optional. 1 by default.
- width: (Number) - Optional. 1 by default.
- x: (Number) - Optional. Sequential by default.
- y: (Number) - Optional. 0 by default.
- onclick: (Function)
- onhover: (Function)
- onload: (Function) - Note. If
.onload returns a type (Object), it will be used to populate the Component and replace current content.
(Object, Component<BIUF>): .type = ‘biuf’
(Object, Component<WYSIWYG>): .type = ‘wysiwyg’
(Object, Component<BasicColour>): .type = ‘basic_colour’
(Object, Component<Button>): .type = ‘button’
(Object, Component<Checkbox>): .type = ‘checkbox’
(Object, Component<Colour>): .type = ‘color’/'colour'
(Object, Component<Datalist>): .type = ‘datalist’
(Object, Component<Date>): .type = ‘date’ - Note: This also includes advanced Calendar optioning.
(Object, Component<DateLength>): .type = ‘date_length’
(Object, Component<Email>): .type = ‘email’
(Object, Component<File>): .type = ‘file'
(Object, Component<Hierarchy>): .type = ‘hierarchy’
(Object, Component<HTML>): .type = ‘html’
(Object, Component<Image>): .type = ‘image’
(Object, Component<Map>): .type = ‘map’
(Object, Component<MultiTag>): .type = ‘multi_tag’
(Object, Component<Number>): .type = ‘number’
(Object, Component<Password>): .type = ‘password’
(Object, Component<Radio>): .type = ‘radio’
(Object, Component<Range>): .type = ‘range’
(Object, Component<Reset>): .type = ‘reset’
(Object, Component<ScriptManager>): .type = ‘script_manager’ - Specification for ScriptManager Block/Node/Text editors are not yet complete.
(Object, Component<SearchSelect>): .type = ‘search_select’
(Object, Component<Select>): .type = ‘select’
(Object, Component<SortableList>): .type = ‘sortable_list’
(Object, Component<Submit>): .type = ‘submit’
(Object, Component<Table>): .type = ‘table’
(Object, Component<Telephone>): .type = ‘tel’/'telephone'
(Object, Component<Text>): .type = ‘text’. Default Component if .type is left unspecified.
(Object, Component<Time>): .type = ‘time'
(Object, Component<URL>): .type = ‘url’
(Object, Modal): All subsequent classes inherit these properties.
- can_close: (Boolean) - Optional. False by default.
- draggable: (Boolean) - Optional. False by default.
- resizable: (Boolean) - Optional. False by default.
- interface: (Object, Interface)
(Object, Modal<Alert>): .type = ‘alert’
- name: (String, Localisation) - Optional. ‘Alert’ by default.
- description: (String, Localisation)
- icon: (String) - Optional. File path to any icon to display in the top left of the Alert. Not displayed by default.
- accept_button_name: (String) - Optional. ‘OK’ by default.
- accept_function: (Function)
- can_close: (Boolean) - Optional. True by default.
(Object, Modal<Confirm>) .type = ‘confirm’
- name: (String, Localisation) - Optional. ‘Alert’ by default.
- description: (String, Localisation)
- icon: (String) - Optional. File path to any icon to display in the top left of the Alert. Not displayed by default.
- accept_button_name: (String) - Optional. ‘Accept’ by default.
- accept_function: (Function)
- can_close: (Boolean) - Optional. True by default.
- reject_button_name: (String) - Optional. ‘Reject’ by default.
- reject_function: (Function)
(Object, Modal<Prompt>) .type = ‘prompt’
- name: (String, Localisation) - Optional. ‘Alert’ by default.
- description: (String, Localisation)
- icon: (String) - Optional. File path to any icon to display in the top left of the Alert. Not displayed by default.
- interface: (Object) - Optional. Whether to display an interface in the modal instead of a simple Text component. Undefined by default.
- placeholder: (String) - Optional. The placeholder to show in the Component<Text> bound to the Modal<Prompt>. ‘Enter text …’ by default.
- accept_button_name: (String) - Optional. ‘OK’ by default.
- accept_function: (Function)
- can_close: (Boolean) - Optional. True by default.
(Object, Tooltip) - Used to express a nested tooltip.
If (Object):
- Inherits all attributes from: (Object, Pane).
If (String): Display as (String, Localisation)
¶ 7. Localisation and Variable Resolution
Localisation and Variable Resolution are managed similarly to template strings; that is that they resolve all values inside of them with the arg0_options parameter being accessible as options. Variables may be passed down in curly braces like so: {<variable_key>}.
In addition, HTML formatting will be resolved inline for localisation.
(String, Localisation):
£:en - Delimits the current string as being in English, the default locale.£:<locale> - Delimits the current locale. Used to additionally close the locale ending, i.e. £:enThis is a test.£:en£de:Dies ist ein Test.£:de.£b - Bolds text.£i - Italicises text.£u - Underlines text.£s - Strikethrough text.£r - Resets all text formatting.£w:<number> - Changes the font weight. If no number is specified, i.e. £w or £w:, it defaults to 400.£<colour_key> - Picks a colour for localisation from a series of defaults. See below for options:
- ‘black’
- ‘blue’
- ‘green’
- ‘light_grey’
- ‘orange'
- ‘red’
- ‘white’
- ‘yellow’
- ‘reset’ - Resets colour.
£opacity:<number> - Specifies opacity from 0 to 1. If it is above 1, opacity is assumed to range from 0-255.£rgb<number, number, number> - Specifies a custom RGB number for colour.{<variable_key>} - Delimits an expression/variable to resolve and embed inline. Creates an embedded JS Function behind the hood.
defines - Accesses any inherited defines from the Class/Window/Interface/Component.options - Accesses the current inherited state from the Class/Window/Interface/Component.
options.value - Accesses the local value of the Component or its binding (if available).options.value_string - Accesses the local value of the Component or its binding as rendered in String format (if available).
{{<variable_key>}} - Signals that the string the variable is attached to should be resolved as a (String, Localisation). Useful for minifying locales or nested resolution.
Special Functions are used nearly entirely for JS bindings - and are applied whereever you see (Function) as a valid type in documentation. As such they have various e and arg0_options info passed along to them that contains all relevant information and state bindings.
e: (HTMLElement) - Same as arg0_options.element.
arg0_options: (Object)
- class_config: (Object)
- class_state: (Object) - Includes
.defines as a reserved keyword.
- component_config: (Object)
- component_state: (Object) - Same as
.value. Includes .defines as a reserved keyword.
- element: (HTMLElement) - The immediate HTMLElement for the scope.
- instance_config: (Object)
- instance_state: (Object) - Includes
.defines as a reserved keyword.
- value: (Object) - The resolved value of the Component if available; otherwise go through either
.class_state or .instance_state.
CSS styling principally depends on the root [ve=true] element's variables, which are inherited by its children. By default, .ve-light and .ve-dark are the main themes available for CSS styling, with the ability to define additional themes, and apply them via the use of .css_class elsewhere. Note that most of the time, you will wish to target the .css_class field in 2. Windows.