Function Editor

The FunctionEditor.vue view loads when we create a new ZObject of type Function/Z8 or edit an existing one. The App entry point renders Function Editor when we:

• Create a new Function: Opening the special page Special:CreateObject with the URL parameter zid=Z8. E.g. https://www.wikifunctions.org/wiki/Special:CreateObject?zid=Z8
• Edit an existing Function: Opening the wiki page for a Zid that belongs to a function with the URL parameter action=edit. E.g. https://www.wikifunctions.org/wiki/Z802?action=edit

The Function Editor content consists of a simple form page having no additional widgets.

Function Viewer

The FunctionViewer.vue view loads when we view an existing Function/Z8 object. The App entrypoint renders Function Viewer when we:

• View a Function: Opening the wiki page for a Zid that belongs to a function. E.g. https://www.wikifunctions.org/wiki/Z802

The Function Viewer page accommodates the widgets: About, Function Evaluator, Implementations Table and Tests Table.

Default View

The DefaultView.vue view is loaded when creating, editing, or viewing all objects that are not a Function/Z8. The App entry point renders Default View when we:

• Create a new object: Opening the special page Special:CreateObject without the zid URL parameter. E.g. https://www.wikifunctions.org/wiki/Special:CreateObject
• Create a new object of a given type: Opening the special page Special:CreateObject with the zid parameter set to other than Z8. E.g. https://www.wikifunctions.org/wiki/Special:CreateObject?zid=Z14
• View an object: Opening the wiki page for a Zid that belongs to an object that's not a function. E.g. https://www.wikifunctions.org/wiki/Z11
• Edit an object: Opening the wiki page for a Zid that belongs to an object that's not a function with the URL parameter action=edit. E.g. https://www.wikifunctions.org/wiki/Z8020?action=edit&uselang=en

The page is formed by a central Content section and the About widget. And specifically, when viewing or editing objects of type Implementation/Z14 or Test/Z20, it also adds the Function Explorer, Function Evaluator, and Function Report widgets.

Function Evaluator

The FunctionEvaluator.vue view is loaded when opening the Special:RunFunction page. E.g. https://www.wikifunctions.org/wiki/Special:RunFunction

ZObject Initialization

Every Create, Edit or View page represents an object of type Persistent Object/Z2. When we create a new ZObject, the initialization process creates a blank Persistent Object/Z2, and when we edit or view an existing one, the initialization flow requests it via the MediaWiki API and sets it as the page root ZObject.

As persisted, ZObjects are valid JSON objects and they are stored in their canonical (or short) form. However, while initializing the Frontend app, objects undergo two transformations:

1. Transform from canonical to hybrid form: Terminal nodes (Strings/Z6 and References/Z9) are transformed into their normal (or long) form. Lists are left as arrays, in their canonical form (aka. Benjamin Arrays).
2. Missing keys are initialized to their blank values, so that editors can see them and edit them to valid values. Some commonly missing keys are Description/Z2K5, Aliases/Z2K4, the Key/Z3 property Is identity/Z3K4, and the Type/Z4 properties for its Equality function/Z4K4, Display function/Z4K5 or Reading function/Z4K6.

Label Data Initialization

Once the main ZObject is requested, transformed and stored as as described in the section above, we have a locally accessible, easily editable representation of all its nodes. However, the object is still represented in its non-readable form (with language-independent Zids and ZKey ids instead of human-readable labels).

The final step of initialization is to make sure that all the ZObject and ZKey ids are shown in the user language, if available, or in their closest available fallback language:

Before label data	For English	For Spanish

To accomplish this, the global store keeps a glossary of labels and their translations to the user language, stored in the module library.js, and all of the components request the translations to this module.

Details on how to use the library module are below in the Library module section.

Page Submission

Before the final submission, the main ZObject undergoes a series of validations and, if those are successful, a series of transformations. All of these are placed in the submissions module.

The component that handles, triggers and orchestrates all the submission-related actions is the Publish widget detailed below.

Notes on Getters

Pinia getters work as computed properties. After requesting the getter in the component using mapGetters like this:

computed: $.extend( {}, mapGetters( [
    'getCurrentZObjectId',
    'getZObjectByKeyPath'
] ), {
    ...
} ),

The getter getCurrentZObjectId is already computed and can be used anywhere in the component without having to invoke it as a function.

zobjectId: function() {
  return this.getCurrentZObjectId;
}

However, some getters need an input. In these cases, getters will return a function which needs to be invoked from the component. This is the case of getters like getZObjectByKeyPath, which needs the full array of keys passed as an input:

exampleMainZObjectType: function() {
  return this.getZObjectByKeyPath( [ 'main', 'Z2K2', 'Z1K1' ] );
}

This needs to be taken into consideration when mocking the store getters in the jest unit tests, and every getter needs to be mocked to return either a value or a function.

Library module

The library module requests, transforms and stores all the auxiliary information that the UI needs from other ZObjects that are not the main one. The library module stores two main collections:

• labels: Glossary of all ZObject and ZKey ids in their abstract form and their most relevant available label. Each value contains the human-readable label, the language of the label, and the Zid, and the objects are indexed by Zid.

{
  "Z1": { "label": "Object", "lang": "Z1002", "zid": "Z1" },
  "Z1K1": { "label": "type", "lang": "Z1002", "zid": "Z1K1" },
  "Z1002": { "label": "Inglés", "lang": "Z1003", "zid": "Z1002" },
  "Z1003": { "label": "Spanish", "lang": "Z1002", "zid": "Z1003" },
}

• objects: Cached ZObjects that were requested by the library module and might be needed in the future.

// Given the function Id, get a list of the argument types
const newArgs = this.getInputsOfFunctionZid( functionZid );

const argTypes = newArgs.map( ( arg ) => arg[ Constants.Z_ARGUMENT_TYPE ] );

// Fetch all argument type Zids first, before the creation of the blank objects
this.fetchZids( { zids: argTypes } ).then( () => {
  // Now we know that all arg types will be available on this.getStoredObject( argType )

  // We can safely initialize the function call arguments:
  newArgs.forEach( ( arg ) => {
    const key = arg[ Constants.Z_ARGUMENT_KEY ];
    const type = arg[ Constants.Z_ARGUMENT_TYPE ];
    
    // We create the blank value of the given type:
    const value = this.createObjectByType( { type } );

    // Then set the argument blank value on its key:
    this.setValueByKeyPath( {
      keyPath: [ ...keyPath, key ],
      value
    } );
  } );
} );

ZObject module

The ZObject module stores the page ZObjects under their specific namespace (main , call or response), and provides a collection of getters and actions to navigate and mutate them.

Some getters and actions are specific to certain namespaces and object types, for example, getCurrentZObjectType will always return the type of the ZObject stored in the main namespace, under the Persistent Object Value/Z2K2 key, so it doesn't require a path as an input (in other words, the path is always main.Z2K2). Other getters or actions are more generic and can be used to inspect or mutate different nodes. In these cases, the getters and actions require keyPath as an input, which should be an array of strings describing the path to walk, starting from the namespace name. For example, the keyPath to the main inner object type would be [ 'main', 'Z2K2', 'Z1K1' ]

main: {
    Z2K2: {
        Z1K1: {
            Z1K1: "Z9",
            Z9K1: "Z11"
        },
        Z11K1: {
            Z1K1: "Z9",
            Z9K1: "Z1002"
        },
        Z11K2: {
            Z1K1: "Z6",
            Z6K1: "old string"
        }
    }
}

setValueByKeyPath( [ "main", "Z2K2", "Z11K2", "Z6K1" ], "new string" );

changeTypeByKeyPath( {
  keyPath: [ 'main', 'Z2K2', 'Z11K1' ],
  type: 'Z60'
} );

main: {
    Z2K2: {
        Z1K1: {
            Z1K1: "Z9",
            Z9K1: "Z11"
        },
        Z11K1: {
            Z1K1: {
                Z1K1: "Z9",
                Z9K1: "Z60"
            },
            Z60K1: {
                Z1K1: "Z6",
                Z6K1: ""  // blank value
            }
        },
        Z11K2: {
            Z1K1: "Z6",
            Z6K1: "old string"
        }
    }
}

ZObjectKeyValue

The component ZObjectKeyValue.vue is the most important piece of the Default View as it represents every key-value pair and provides the following functionality:

• It renders the key in the preferred user language, or in the closest fallback language. E.g. Instead of "Z1K1", it shows "type" or "(en) type"
• It figures out the ZObject type of its value
• It figures out the layout configuration for each type, which determines whether the type has a built-in component and whether it has both expanded and collapsed states.
• It allows switching between collapsed and expanded mode if the component allows so (wee ExpandedToggle section below)
• Depending on the layout configuration and on the current state of the expansion toggle, it decides what component to render.
• Depending on the type specification for the given key, it restricts the changes that a contributor can make to the value.
• It allows changing the mode of the value, between literal ZObject, a referenced ZObject, or a ZObject produced by a function call. (See ModeSelector section below)
• It handles changes in the value by catching and handling set-value and set-type events from the value. (See Data modification events section below)

The ZObjectKeyValue component acts as the main functional node for the whole tree, while the typed components just handle the rendering of the HTML elements.

Every ZObjectKeyValue component will render:

• ExpandedToggle component
• ModeSelector component
• LocalizedLabel component
• A dynamically rendered component for the value. This component may be terminal, or a continuation of the component tree.

ExpandedToggle

This component precedes every key-value, and it is a button with three states:

• Bullet point: The value for this key doesn't have a double state (collapsed and expanded views). This can be either because the type doesn't have a built-in component and will always be rendered with the fallback ZObjectKeyValueSet, or because it has a built-in component but the layout configuration specifies that this component should nevery be expanded and shown using ZObjectKeyValueSet.
• Collapsed, or right chevron: The value for this key is rendered with its collapsed view, which is a builtin component specific for its type. By clicking it, it will switch to expanded.
• Expanded, or down chevron: The value for this key has a collapsed view (or a builtin component for its type), but it's currently shown in its expanded view (with the fallback ZObjectKeyValueSet component). By clicking it, it will switch to collapsed.

ModeSelector

Even when a given key must contain a value of a bound type (E.g. the key Z11K1 must only contain values of type Language/Z60), this value could be passed in different ways (or modes):

• The value can be a literal object of the required type.
• The value can be a link (or a reference) to an object of the required type.
• The value can be a function call that returns an object of the required type.
• Inside an implementation composition, the value can be a reference to one of the inputs passed when calling this function.

The ModeSelector component follows every key, and is a button with the icon of an ellipsis ..., with a dropdown menu with all the possible representations of the value. Clicking on any of these options, will fully change the shape of the value under this key to the selected one.

The available values are specific to the key, its required type and its context. This component is not rendered when:

• It is a Read page.
• The key is hidden in the parent ZObjectKeyValue component by setting skipKey=true.

Additionally to the mode editing options, when the key belongs to a list item, it adds additional menu options to:

• delete this item from the list,
• move this item up in the list, and
• move this item down in the list.

ZObjectKeyValueSet

The ZObjectKeyValueSet component renders the collection of key-value pairs of a ZObject. Whenever showing a given ZObject using this component, it will iterate through all its keys, and render a ZObjectKeyValue component for each one of them.

This component is the fallback option when:

• There is no builtin component associated with its type. E.g. An object of type Key/Z3 has no builtin component, so it will be rendered using ZObjectKeyValueSet, which will render a ZObjectKeyValue for each of its keys (Z1K1, Z3K1, Z3K2 and Z3K3).
• There is a builtin component for this type, but the ZObjectKeyValue component is on expanded mode.

Typed components

Some common types have their own builtin components that understand the existing keys, can initialize values, and can render HTML elements that allow for easy viewing and editing of their values.

The components ZString and ZReference are terminal, and hence will not allow further expansion into ZObjectKeyValueSet. All the other typed components can be switched to expanded mode.

Every typed component should have as input properties:

1. keyPath: which contains a string representation of the path of keys up to this value. This will be mostly used for mutation operations, which are handled by the zobject.js store actions, and need a full path to reach the target object.
2. objectValue: a reference to the ZObject node in the store. This will be used for reading and extracting the relevant values of each ZObject in order to build the appropriate template.

Every typed component should at least:

1. Implement a template that adapts to both Read and Edit pages.
2. Use the utility functions provided in the zobjectMixin.js to extract the necessary values from the objectValue object.
3. React to change events in the relevant template elements, and emit setValue events with the correct payload, so that the ZObjectKeyValue parent component updates the state.
4. Additionally, any typed component should be able to handle an empty state.

For a good example, we can take a look at the ZMonolingualString component. The following figures show a list of Monolingual string/Z11 objects. The one for the Edit page also showcases the component blank state:

Read page	Edit source page

This is how the ZMonolingualString component solves the points listed above:

1. The template adds a chip for the language ISO code (corresponds to the key Z11K1), and a text for the string value (corresponds to the key Z11K2) for Read mode. In Edit mode, the string value is instead shown in an Input component, for it to be editable.
2. The utility function getZMonolingualTextValue( objectValue ) returns the terminal value of the Language/Z11K1 key, which is used to build the language chip element. The utility function getZMonolingualTextValue( objectValue ) returns the value of the Text/Z11K2 key, which is set as the text or input field in the template.
3. The component observes changes in the input field, and when it changes, it emits the event setValue with the whole keyPath and the new value to set. The whole keyPath is built by concatenating the component keyPath (e.g. 'main.Z2K3.Z12K1.1') and the partial keyPath that describes the particular inner change (e.g. 'Z11K2.Z6K1'):

   {
     keyPath: 'main.Z2K3.Z12K1.1.Z11K2.Z6K1',
     value: "new value"
   }
   

4. The blank state of the monolingual string has a special style as seen in the image.

The Component Tree

Let's look at an example of the component tree putting all of these together. Assuming a Persistent Object/Z2 containing a Monolingual text/Z11 as shown below (only the content key, for simplicity):

{
  "Z2K2": {
    "Z1K1": "Z11",
    "Z11K1": "Z1002",
    "Z11K2": "new string"
  }
}

This is the tree of components that would be rendered:

• ZObjectKeyValue component for the key Z2K2:
  • properties:
    • key: Z2K2
    • expected type for key: Object/Z1 (anything)
    • value type: Monolingual text/Z11
  • component rendered for the value:
    • ZMonolingualString component, if expanded is false, or
    • ZObjectKeyValueSet component, if expanded is true.
      • ZObjectKeyValue component for the key Z1K1
        • properties:
          • key: Z1K1
          • expected type for key: Type/Z4
          • value type: Reference/Z9
        • component rendered for the value:
          • ZReference component
      • ZObjectKeyValue component for the key Z11K1
        • properties:
          • key: Z11K1
          • expected type for key: Language/Z60
          • value type: Reference/Z9
        • component rendered for the value:
          • ZReference component
      • ZObjectKeyValue component for the key Z11K2
        • properties:
          • key: Z11K2
          • expected type for key: String/Z6
          • value type: String/Z6
        • component rendered for the value:
          • ZString component

Data modification events

When a template component in edit mode detects an update in one of its input fields, it emits a mutation event that is then handled by its parent ZObjectKeyValue component who, as explained above, contains all the state modification logic and calls the state mutation actions. There are two mutation events that are handled by this component:

• set-value event: Thrown by every component whenever a value is being changed. While handling this event, the ZObjectKeyValue component will make the required mutation using the setValueByKeyPath action and, additionally, make different alterations depending on the type or key updated. For example, when the value of a Function Call Function/Z7K1 key changes, it will also remove the old function call arguments (if any) and set the new ones for the newly updated Function Call Function Id.

• set-type event: Mainly thrown by the Mode Selector component, which handles type modifications of each key between its literal type or any of the other resolver types (function call, reference, or argument reference). Any type mutations requires a special behavior, as it should initialize the object with a blank version of the given type.

About widget

The About widget is present in all view and edit pages, except for the Function Editor. It provides a way to view, navigate and edit multilingual information to the page ZObject.

When in the Function Viewer page, the About widget also displays information about the function inputs, their types and labels, and the function output type. Similarly, the About widget from the Function page also allows editing or adding input labels.

On load, the About widget will display as many languages as necessary to cover the ZObject information in the user's language or closest fallback languages. For example, if the whole information (name, description, aliases, input labels) is available in the user's language, the widget will present one language block with the user language. However, if the user's language information is incomplete, the About widget will be initialized with both the user's language block and the next fallback language which contains name, description, aliases and input labels for the object. Additionally, the user can select any other languages to add to the display.

Even when the page is in Read mode, the About widget allows edition of multilingual data. However, the edit and submission flows are slightly different:

• When in Edit mode:
  • Language blocks are shown in an editable form—with editable input fields.
  • Name, description, aliases and input labels can be edited cumulatively.
  • More languages can be added to the display, by clicking on the "n languages" button and selecting a new language (with or without data.)
  • Only when clicking the page "Publish" button, all the changes will be submitted.
• When in Read mode:
  • Language blocks are shown in a readable form—with text instead of fields.
  • Each language block has an "edit" (pencil) icon that sets the block state to its editable mode—with editable input fields. A "Cancel" and a "Publish" button will appear in the widget header.
  • Users can make changes to the multilingual data without leaving the Read page.
  • Once the edits are done, users can press the widget "Publish" button, which will trigger a publishing dialog asking for the change summary.

Publish widget

The Publish widget is rendered in all edit pages and initiates validation, transformation and submission of edited or newly created ZObject. It is formed by the components:

• Publish.vue: The base widget which renders the Cancel and Publish buttons. The "Publish" button is initially disabled, and is enabled only when changes are observed. It also triggers the validateZObject action when this button is clicked.
• PublishDialog.vue: Dialog component that's shown if the validation is passed successfully. Displays any warning messages that might be relevant to the user's edit, the text field to add a publish summary, and the final submission or cancellation buttons. This triggers the final ZObject transformations and submission as detailed in the transformations section. If the submission is unsuccessful, this dialog will show any errors returned by the edit API.

Function Evaluator widget

The Function Evaluator widget is shown in the Function Viewer page, and in the edit and view pages for Test/Z20 and Implementation/Z14 objects. It allows the user to try the function relevant to the page, as long as the Function is runnable (it has attached implementations) and the user has the right execute permissions.

The Function Evaluator widget runs the preferred implementation of the given function, except when in the Implementation view or edit page. In these cases, the Function Evaluator widget runs the particular Implementation represented in the page.

The widget uses the ZObjectKeyValue.vue default component which to create a component representation of both the function call and the returned result, stored under the namespaces of call and response, respectively.

The store module functionCall.js contains the actions necessary to initialize the widget and perform the function call.

Function Explorer widget

The Function Explorer widget allows users to see details of a Function definition, explore existing persisted Functions and see relevant details while writing an Implementation.

The widget is shown in the Read and Edit pages for Implementation/Z14 and Test/Z20 objects, and it has two different modes:

• In Read mode: the widget shows information of the current Implementation's target Function. E.g. If we are viewing an Implementation for the function "If", the Function explorer shows the signature details of the function "If".
• In Edit mode: the widget renders a search box where the user can search and select already existing functions, and see their signature details.

Function Report widget

The Function Report widget displays the current Test/Implementation status for the current Function. This widget is rendered in the Read and Edit pages for Implementation/Z14 and Test/Z20 objects:

• In an Implementation/Z14 page: The Function Report widget shows the state of all the available Tests of the current function, running against the given Implementation.
• In a Test/Z20 page: The Function Report widget shows the state of all the available Implementations for the current function, running the given Test.