¶ Summary.
BrowserUI is considered legacy infrastructure. Even though legacy infrastructure is highly developed, you should consider updating it to Vercengen specifications to write no-code end-to-end software in JSON5 only.
BrowserUI has no dependencies for its components and context menus, although it recommends the use of Tippy.js for tooltips.
Due to their lengths, various documentation sections have been moved to separate pages. If you would like to view them inline alongside comprehensive documentation as a single page, please visit BrowserUI - Comprehensive Documentation. This page is for core documentation only.
|
|
BrowserUI (sometimes stylised UF/BrowserUI) is the main frontend UI library module and component of Universal Framework, Confoederatio's main software engine. It typically contains regular DOM functions as well as more advanced context menus and dynamic custom frontend UIs that can be spawned into various containers utilising JSON5 logic.
These functions, alongside their documentation, are generally presented below in order of importance. There is currently work underway to make sure that createContextMenu() can be easily recursive with collapsible folders and subfolders without the use of .type = 'html' components.
¶ 0. Documentation - UI Functions
¶ Context Menu Functions
createContextMenu() - Creates a context menu within the DOM.
- arg0_options: (Object)
- anchor: (String/HTMLElement) - The query selector to pin a context menu to.
- class: (String) - The CSS class prefix to prepend.
- do_not_append: (Boolean) - Whether to append to the existing element's HTML or not.
- id: (String) - The ID of the context menu.
- name: (String) - Optional. Title of the context menu. Undefined; will not display by default.
- maximum_height: (String) - Optional. The height after which a scrollbar should appear in CSS units.
- maximum_width: (String) - Optional. Maximum width in CSS units.
- <input_key>: (Object, Component)
- return_html: (Boolean) - Optional. Whether to return the html_string instead of modifying the anchor element. False by default.
- Returns: (HTMLElement/String)
createContextMenuIndex() - Creates a nested context menu index framework to read from global.config.<config_key>, i.e. ‘global.config.group_actions’. Requires config and config.defines.common to be defined in your project.
Note. This should almost always be used in conjunction with createContextMenuInterface() unless you wish to implement the associated interface logic yourself.
- arg0_options: (Object)
- config_key: (String) - The main global.config key where categories are stored.
- namespace: (String) - The global-level namespace in which dynamically created functions using createContextMenuInterface() will be placed.
- Returns: (Void, dynamically-created Global Functions):
- global.
getAll<options.namespace>s: (Function) - Returns all Object, ContextMenus within a given JSON config/namespace.- arg0_options: (Object)
- return_keys: (Boolean) - Optional. Whether to return the keys of all flattened Object, ContextMenu objects in the JSON config. False by default.
- Returns: (Array<Object, ContextMenu>/Array<String>)
- arg0_options: (Object)
- global.
get<options.namespace>: (Function) - Returns an Object, ContextMenu within a given JSON config/namespace.- arg0_name: (String) - The name of the ContextMenu to look for within the JSON config.
- arg1_options: (Object)
- return_key: (Boolean) - Optional. Whether to return the key of the interface instead of the actual Object, ContextMenu.
- Returns: (Object, ContextMenu/String)
- global.
get<options.namespace>sAtOrder: (Function) - Returns an Array<Object, ContextMenu> within a given JSON config/namespace.- arg0_options: (Object)
- order: (Number) - The .order field at which to return Context Menu bindings.
- return_object: (Boolean) - Optional. Whether to return an Object containing all Context Menus that have this .order. False by default.
- return_keys: (Boolean) - Optional. Whether to return all flattened keys instead of an Array<Object, ContextMenu>, which is default behaviour. False by default.
- Returns: (Array<Object, ContextMenu>/Array<String>/Object, ContextMenuDictionary)
- arg0_options: (Object)
- global.
get<options.namespace>sCategory: (Function) - Returns a Context Menu category, usually all set at the same order. These Context Menu categories are used to define orders with multiple Context Menu bindings.- arg0_name: (String) - The given Context Menu category name.
- arg1_options: (Object)
- return_key: (Boolean) - Optional. Whether to return the key instead. False by default.
- Returns: (Object, ContextMenuCategory)
- global.
get<options.namespace>sInput: (Function) - Returns the element of an input within a context menu JSON config if available.- arg0_namespace_id: (String) - The namespace of the given context menu types you assigned.
- arg1_input_id: (String) - The ID/key name of the input to fetch the HTMLElement for.
- Returns: (HTMLElement)
- global.
get<options.namesace>sLowestOrder: (Function) - Returns the lowest .order in the given context menu JSON config.- Returns: (Number)
- global.
get<options.namespace>sNavigationObject: (Function) - Returns the root navigation menu for use in creating that interface.- Returns: (Object, ContextMenu)
- global.
createContextMenuInterface() - Creates a nested context menu interface framework to read from global.config.<config_key>, i.e. ‘global.config.group_actions’. Requires config and config.defines.common to be defined in your project. Requires createContextMenuIndex().
- arg0_options: (Object)
- anchor: (String) - The default anchor query selector for where your recursive Context Menus from this JSON config will be bound.
- class: (String) - The class to apply to Context Menus spawned from the given namespace. If you wish to avoid default UF styling, append ‘ unique’ onto the end of your .class String.
- config_key: (String) - Typically the given options.namespace from createContextMenuIndex(). Always refers to global.config.<config_key>.
- interface_key: (String) - Optional. Same as options.config_key by default. Where variable bindings are stored. Always refers to global.interfaces.<interface_key>.
- left_margin: (String) - Optional. The CSS calc attribute to prepend when calculating offset margins.
- limit_key: (String) - Limit key if applicable, first argument fed into parseLimit() from JSON5DSL.
- right_margin: (String) - Optional. The CSS calc attribute to prepend when calculating offset margins.
- namespace: (String) - Used for global function names, i.e. .namespace = ‘BrushAction’ results in closeBrushActionContextMenu() being defined.
- navigation_mode: (String) - Optional. Either ‘icons’/'list'/'list_icons'. ‘list’ by default.
- type: (String) - Optional. Either ‘default’/'entity'/'group'. ‘default’ by default.
- Returns: (Void, dynamically-created Global Functions):
- global.
close<options.namespace>ContextMenu()- Closes a ContextMenu at a given order.- arg0_order: (Number)
- arg1_options: (Object) - The .options field to pass onto get<options.namespace>sAnchorElement() and refresh<options.namespace>sContextMenus().
- global.
close<options.namespace>ContextMenus()- Closes all ContextMenus currently open for this namespace.- arg0_options: (Object) - The .options field to pass onto get<options.namespace>sAnchorElement().
- global.
close<options.namespace>LastContextMenu()- Closest the last opened ContextMenu for this namespace.- arg0_options: (Object) - The .options field to pass onto get<options.namespace>sOpenOrders() and close<options.namespace>ContextMenu().
- global.
get<options.namespace>sAnchorElement()- Fetches the given anchor element specified for ContextMenus in the namespace.- arg0_options: (Object)
- return_selector: (Boolean) - Optional. Whether to return the query selector instead of the actual HTMLElement. False by default.
- Returns: (HTMLElement/String)
- arg0_options: (Object)
- global.
get<options.namespace>sOpenOrders()- Returns an array of all open orders for a given namespace's ContextMenus.- Returns: Array<Number>
- global.
get<options.namespace>sInputObject()- Returns the given state object for a ContextMenu namespace.- arg0_options: (Object) - The .options field to pass onto get<options.namespace>sAnchorElement().
- Returns: (Object)
- <context_menu_key>: (Object)
- <variable_key>: (Variable)
- <context_menu_key>: (Object)
- global.
print<options.namespace>sContextMenu()- Prints a given ContextMenu for the namespace's JSON config.- arg0_namespace_obj: (Object) - The given ContextMenu JSON object to render.
- arg1_options: (Object)
- type: Either ‘default’/'entity'/group'. Extendable to different data types within your project.
- entity_id: (String) - Optional. The entity ID/entity object to fetch custom render logic for. Naissance GIS option.
- group_id: (String) - Optional. The hierarchy group ID to fetch custom render logic for.
- options: (Object)
- <variable_key>: (Variable) - Used for .placeholder bindings to populate default input information with.
- timestamp: (Number) - Optional. The current timestamp to pass to ContextMenu population functions. Naissance GIS option.
- <variable_key>: (Variable) - Also added to HTMLAttributes for the given namespace anchor element.
- type: Either ‘default’/'entity'/group'. Extendable to different data types within your project.
- global.
print<options.namespace>sNavigationMenu()- Prints the root navigation ContextMenu for the namespace's JSON config.- arg0_parent_el: (HTMLElement) - The parent element/container for the root navigation ContextMenu to be displayed in.
- arg1_options: (Object) - The .options field to pass onto get<options.namespace>sAnchorElement(), as well as JSON5DSL's parseEffect().
- limit_key: (String) - Used for JSON5DSL's parseLimit(). Determines the type of limit scope to parse if applicable.
- scroll_selector: (String) - The query selector if the ContextMenu is bound to a scrollable container so that it vertically adjusts to the spawnpoint of the ContextMenu.
- y: (Number) - The raw y adjustment in px to apply using CSS.
- <variable_key>: (Variable) - Also added to HTMLAttributes for the given namespace anchor element.
- global.
refresh<options.namespace>sContextMenus()- Refreshes all ContextMenus for the given namespace, including any state/layout changes.- arg0_options: (Object) - The .options field to pass onto get<options.namespace>sAnchorElement().
- Returns: (Number) - The total layout width of all ContextMenus for this JSON namespace in px.
- global.
refresh<options.namespace>sContextMenuInputs()- Refreshes only state changes for a given namespace.- arg0_options: (Object) - The .options field to pass onto get<options.namespace>sAnchorElement().
- global.
createPageMenu() - Creates a page menu within the DOM with multiple tabs.
- arg0_options: (Object)
- id: (String)
- anchor: (String) - The query selector anchor in which the page menu is created. If
options.tab_anchoris specified, this is just where page content is displayed instead. - tab_anchor: (String) - Optional. The query selector where the tabs menu is created. Defaults to creating two elements in anchor if not available.
- default: (String) - Optional. The default tab for the page menu to rest on. This is the first key by default.
- pages: (Object, PageDictionary)
- <page_key>: (Object, ContextMenu) - Inherits
arg0_optionsfromcreateContextMenu().- name: (String)
- html: (Array<String>/String) - Optional. Any custom HTML to load into the page instead of ContextMenu options.
- <key>: (Variable) - Optional. The same as most context menus. Does not apply if local .html is defined.
- special_function: (Function) - The function to execute upon clicking this tab.
- arg0_e: (Event, Onclick)
- name: (String)
- <page_key>: (Object, ContextMenu) - Inherits
- special_function: (Function) - The function to execute upon clicking any tab.
- arg0_e: (Event, Onclick)
- Returns: (HTMLElement)
- id: (String)
¶ Folders/Sections
addSection() - Creates a foldable section/foldable element that can be minimised/expanded.
- arg0_options: (Object)
- expand_class: (String) - Optional. The class to add when the content is expanded. ‘uf-expanded’ by default.
- minimise_class: (String) - Optional. The class to add when the content is collapsed. ‘uf-minimised’ by default.
- selector: (String) - The selector for the various elements that can be minimised/expanded. Note that the first element covered by the selector will have the actual chevron controller.
- selector_class: (String) - Optional. The class to add to the chevron controller. ‘uf-chevron minimise’ by default.
- src: (String) - The source of the chevron image. ‘./UF/gfx/chevron_icon.png’ by default.
- is_collapsed: (Boolean) - Optional. Whether the section should start in a collapsed state. False by default.
¶ Nested Hierarchy Functions
Nested hierarchies are a special type of Component with dedicated functions and bindings. These are typically used for file inputs, as well as for any type of recursive nested list (i.e. for elements currently being rendered). They are generally split into three distinct types: File Explorers (which are in charge of folder and file management), Generic Hierarchies, and Naissance GIS Hierarchies (used for GIS purposes, i.e. geographical groups and entities).
You may also define custom Hierarchy types, please view BrowserUI - Hierarchies#Custom Hierarchies for specific examples (related to File Explorer defines).
¶ File Explorer
Main article(s): BrowserUI - Hierarchies#File Explorer
File Explorers are a custom type of Detached Component that exist for purposes of navigating the saves folder, or for providing file inputs in general. createFileExplorer() is the main function for creating new File Explorer Detached Components within your application.
¶ Hierarchies - Initialisation
Main article(s): BrowserUI - Hierarchies#Hierarchies
Hierarchies are generic Detached Components that can be used anywhere a sortable nested list is required. Note that you may wish to extend them with custom bindings for nested context menus; see initHierarchy() for more information.
¶ Hierarchies - Supporting Functions
Main article(s) - BrowserUI - Hierarchies#Supporting Functions
Supporting functions can be used by developers to help populate and update state within BrowserUI Hierarchies and other Detached Components. Updates are managed by renderHierarchy().
insertEntityAtBottom() and insertGroupAtTop() are typically used for default population purposes.
¶ Undo/Redo Trees
Main article(s): DALS - Delta Actions Logging System
Undo/Redo Trees are used as the standard within UF and UF/BrowserUI, as well as broader Confoederatio software. If you prefer managing a conventional Undo/Redo stack, this can be done via a DALS restriction to the default timeline only.
By default, the UI for Undo/Redo Trees is also provided and can be bound to any valid query selector or HTMLElement.
¶ 1. Documentation - UI Components
(Object, Component)
- type: (String) - The type of HTML input to grab. (See 1. Documentation - UI Components for a full list of available UI Components).
- icon: (String) - Optional. The path to the display icon image.
- name: (String) - Optional. The JS code to execute on button click.
- tooltip: (String) - Optional. The HTML tooltip a user can see by hovering over this input.
- height: (Number) - Optional. The row height of this element in a grid. 1 by default.
- width: (Number) - Optional. The column width of this element in a grid. 1 by default.
- x: (Number) - Optional. The X position of the element in a grid. 0 by default.
- y: (Number) - Optional. The Y position of the element in a grid. n + 1 by default, where n = last row.
- onload: (Function) - The function that is executed upon load. If it returns a type (Object), the (Object, Component) type is updated to that Object.
- arg0_element: (HTMLElement) - The immediate HTMLElement of the given component.
- placeholder: (Variable) - Optional. The placeholder for the Component to have.
(Object, Component): Determined by the .type field in createContextMenu() or createPageMenu().
Inherits all options in (Object, Component).
‘Returns:’ values refer to the state variables read out from getInputsAsObject().
- ‘biuf’
- name: (String)
- default: (String) - Serves as the default placeholder for a BIUF value.
- options: (Object, HTMLAttributes) - Serves as the attributes Object for BIUF.
- Returns: (String) - Returned from .innerHTML.
- name: (String)
- ‘rich_text’/'wysiwyg'
- id: (String) - The custom ID for this WYSIWYG component. Overrides <input_key>.
- name: (String)
- onchange: (Function) - Fires upon any change in text to the WYSIWYG component. Applies to both visual and code editors.
- arg0_event: (Object)
- target: (HTMLElement) - The input WYSIWYG Component's corresponding HTMLElement.
- value: (String) - Returns an HTML String of the text inside the WYSIWYG component.
- arg0_event: (Object)
- Returns: (String) - Returned from .innerHTML.
- ‘basic_colour’
- attributes: (Object, HTMLAttributes)
- onclick: (Function)
- arg0_e: (Event, Onclick)
- Returns: (String) - Seven-character hexadecimal code (i.e. #000000).
- ‘button’
- icon: (String) - The image file/URL for which an icon will be used. Always to the left of .name.
- name: (String)
- onclick: (Function)
- arg0_e: (Event, Onclick)
- ‘checkbox’
- icon: (String) - The image file/URL for which an icon will be used. Always to the left of .name.
- name: (String)
- attributes: (Object, HTMLAttributes)
- options: (Object)
- <option_key>: (String)
- Returns: (Array<String>) - .id array of checked sub-elements.
- ‘color’/'colour' - [WIP] Recommended to use ‘basic_colour’ for now. Technically complete, but colour wheels may be somewhat janky.
- name: (String)
- Returns: (Array<Number, Number, Number>) - 3-element RGB array.
- ‘context_menu’ - [WIP] Not yet implemented. Use an ‘html’ component with a
e.innerHTML = createContextMenu().onload field instead. - ‘datalist’
- options: (Object)
- <option_key>: (String)
- Returns: (String) - Selected <option> .value for the given datalist.
- options: (Object)
- ‘date’
- name: (String)
- multiple_rows: (Boolean) - Whether hours/minutes should be on a separate row from years/months/days.
- Returns: (Object, Date)
- year: (Number)
- month: (Number) - Ranges from 1-12.
- day: (Number) - Ranges from 1-28/30/31.
- hour: (Number) - Ranges from 0-23.
- minute: (Number) Ranges from 0-59.
- ‘date_length’
- name: (String)
- Returns: (Object, Date)
- year: (Number)
- month: (Number) - Ranges from 1-12.
- day: (Number) - Ranges from 1-28/30/31.
- hour: (Number) - Ranges from 0-23.
- minute: (Number) Ranges from 0-59.
- ‘email’
- name: (String)
- attributes: (Object, HTMLAttributes)
- Returns: (String)
- name: (String)
- ‘file’ - [WIP] Not entirely integrated as a component. Use dedicated File Explorer functions instead.
- ‘hierarchy’ - [WIP] Not entirely integrated as a component. Use dedicated Hierarchy functions instead.
- ‘hidden’
- ‘html’
- name: (String) - Optional. The heading to display for this HTML Component.
- custom_html_function: (Object) - The custom HTML function to define for parsing. Should return a variable if this is a readable input component.
- arg0_element: (HTMLElement)
- innerHTML: (HTMLString)
- name: (String) - Optional. The heading to display for this HTML Component.
- ‘image’ - [WIP] Not yet implemented.
- ‘number’
- name: (String)
- attributes: (Object, HTMLAttributes)
- onclick: (Function)
- arg0_e: (Event, Onclick)
- Returns: (Number)
- name: (String)
- ‘password’
- name: (String)
- attributes: (Object, HTMLAttributes)
- Returns: (String)
- name: (String)
- ‘radio’
- name: (String)
- attributes: (Object, HTMLAttributes)
- options: (Object)
- <option_key>: (String)
- Returns: (String) - The .id of the chosen radio option.
- name: (String)
- ‘range’
- name: (String)
- attributes: (Object, HTMLAttributes)
- max: (Number)
- min: (Number)
- onclick: (Function)
- arg0_e: (Event, Onclick)
- options: (Object)
- VALUE: (Number) - The default placeholder value for ‘range’.
- value_equation: (String, Localisation) - The localisation string for the value equation, i.e. how to parse input values. ‘n’ stands for the input VALUE.
- Returns: (Number)
- name: (String)
- ‘reset’
- name: (String)
- ‘search_select’
- name: (String)
- attributes: (Object, HTMLAttributes)
- onchange: (Function) - Fires upon clicking an item in the search_select Component.
- arg0_element: (HTMLElement)
- onclick: (Function) - Fires upon clicking an item in the search_select Component.
- arg0_element: (HTMLElement)
- options: (Object)
- <option_key>: (String)
- Returns: (String) - The [data-value] attribute of the selected item for search_select.
- name: (String)
- ‘select’
- name: (String)
- attributes: (Object, HTMLAttributes)
- onclick: (Function)
- arg0_e: (Event, Onclick)
- options: (Object)
- <option_key>: (String)
- Returns: (String) - The .id of the selected <option>.
- name: (String)
- ‘sortable_list’
- name: (String)
- attributes: (Object, HTMLAttributes)
- delete_button_name: (String) - Human-readable name for the delete button.
- disable_remove: (Boolean) - Whether removing items from the list should be allowed.
- has_controls: (Boolean) - Whether controls for the sortable_list Component should be shown.
- onchange: (Function) - Fires upon any user-driven UI change for the sortable_list Component.
- arg0_element: (HTMLElement)
- onremove: (Function) - Fires upon removing a user removing an item from the sortable_list Component.
- arg0_element: (HTMLElement)
- options: (Object)
- <option_key>: (String)
- Returns: (Array<HTMLElement>) - Returns an array of elements in sequential order from the query selector ul.sortable-list > li > span.
- name: (String)
- ‘submit’
- name: (String) - Optional. ‘Submit’ by default.
- attributes: (Object, HTMLAttributes)
- name: (String) - Optional. ‘Submit’ by default.
- ‘tel’/'telephone'
- name: (String) - Optional.
- attributes: (Object, HTMLAttributes)
- Returns: (String)
- name: (String) - Optional.
- ‘text’
- name: (String) - Optional.
- attributes: (Object, HTMLAttributes)
- onclick: (Function)
- arg0_e: (Event, Onclick)
- Returns: (String)
- name: (String) - Optional.
- ‘time’
- name: (String) - Optional.
- attributes: (Object, HTMLAttributes)
- Returns: (Object)
- hour: (Number)
- minute: (Number)
- name: (String) - Optional.
- ‘url’/'URL'
- name: (String) - Optional.
- attributes: (Object, HTMLAttributes)
- Returns: (String)
- name: (String) - Optional.
¶ 2. Documentation - Localisation
Localisation in UF/BrowserUI almost entirely depends on parseVariableString() as of 1.0, which is designed to function similarly to that of a template string, with which it may be coordinated.
parseVariableString() - Parses a variable string and returns its resolved value.
- arg0_string: (String) - The string which to resolve.
- arg1_options: (Object)
- <key>: (Variable)
- regex_replace: (Object)
- <key>: (Variable)
- Returns: (Variable) - Type coerced to a string for most localisation purposes.
¶ 3. Documentation - Variable Bindings
autoFillInput() - Auto-fills an input for a given element based on parseVariableString() and their context menu .placeholder object.
- arg0_options: (Object)
- element: (HTMLElement) - The direct element object for which to fill in an input for.
- placeholder: (Variable) - The variable to use as the placeholder.
- type: (String) - The type of input the element represents.
- value: (Object) - The local value for the given context menu object element.
- attributes: (Object)
- max: (Number) - The maximum number that can be returned from a .value_equation.
- min: (Number) - The minimum number that can be returned from a .value_equation.
- value_equation: (String) - The value equation to use for transforming an input number, i.e. for .type = ‘range’.
- attributes: (Object)
fillInput() - Manually fills in a ContextMenu input with the placeholder for its corresponding type.
- arg0_options: (Object)
- element: (HTMLElement) - The direct element object for which to fill in an input for.
- placeholder: (Variable) - The variable to use as the placeholder.
- type: (String) - The type of input the element represents.
getInput() - Returns the input of a specific HTMLElement within a context menu as a variable.
- arg0_input_el: (HTMLElement) - The individual .context-menu-cell being referenced.
- arg1_options: (Object)
- custom_html_function: (Function) - Function for parsing custom .type = ‘html’ components. Must return a value.
- arg0_input_el: (HTMLElement)
- custom_html_function: (Function) - Function for parsing custom .type = ‘html’ components. Must return a value.
- Returns: (Object)
getInputsAsObject() - Returns all inputs from a ContextMenu as an Object.
- arg0_context_menu_el: (HTMLElement) - The context menu element.
- arg1_options: (Object)
- do_not_include_submenus: (Boolean) - Optional. Whether to not include context submenus. False by default.
- entity_id: (String) - Optional. Whether the context menu is related to an entity. False by default.
- custom_file_function: (Function) - Optional. The function to run to fetch input values for 'file' types. Fetches all paths by default.
- custom_html_function: (Function) - Optional. The function to run to fetch input values for custom 'html' types. Fetches nothing by default.
¶ 4. Internal Helper Functions
Main article(s): BrowserUI - Internal Helper Functions
Internal Helper Functions exist within BrowserUI for QOL purposes. They may be used by end developers for extending BrowserUI for their own purposes, particularly for creating new types of component Objects without being forced to use .type = ‘html’ with a .onload function.
Due to their length, these functions have been moved to a separate documentation article.
¶ TODO.
Main article(s): BrowserUI TODO