If you haven't already read the pages on setting up your development environment and the build process then we suggest you read those first.

Make sure that you have put Tui into development mode, and have NPM installed and ready to run.

Objective

The objective is to create a server ping component that pings Totara Core using GraphQL, and displays the last time the ping was successful. 

Rather than create this as a component within an existing bundle, we are instead going to create a new bundle at the same time.

Step 1: npm run tui-build-watch

Rather than manually trigger the build when we need to we're going to run the following command, and leave it running until we're complete.

Each time we save a change to our component it will generated updated build files.

Step 2: Creating a new Tui component

Vue components, pages, and modules are organised into Tui components.

Core functionality is presented through the tui Tui component, located at client/component/tui.

How you organise your components is up to you, but we recommend grouping them together based upon functionality. To keep it easy, in core we have used the frankenstyle name from Totara Core as the name for Tui components. For instance if you had a custom local plugin installed at server/local/myplugin, then we would recommend grouping your Vue components into a local_myplugin Tui component located at client/component/local_myplugin.

The use of a frankenstyle name is optional.

For the purpose of this example we are going to call our Tui component 'local_quickstart', and we'll have a server-side plugin under server/local/quickstart. This guide will not go over creating the server-side plugin, only touching the necessary files to create and view our Tui component.

You could create the file structure manually, but to save time will use the tui-init generator.

Run the following commands, replacing 'vendorname' with a unique string identifying you or your employer. The vendor string has no inherent meaning, it's just used to categorise components within the build system - you can set it to anything you want. For example, if Totara were developing a new component we'd use totara as the vendor.

Each Tui component needs a tui.json file that defines its name and the vendor who created it.

This will be automatically generated by the above command with the following content:

client/component/local_quickstart/tui.json

After running the tui-init command you will need to restart tui-build-watch to pick up the new Tui component.

Step 3: Creating a page component

With the build watcher running with the command described earlier, you're ready to create a component. We have different types of components. Firstly we have small re-usable ones that are encapsulated with the intention of performing a limited set of functionalities or visual styles - these are sometimes called presentational components. We assemble these small components and then write additional logic to wire them up together into whole User Interfaces.

We have larger components too, ones that tie together presentational components and implement the logic for the application, often including their own styles as well.

We are going to create a component that will handle the logic for pinging the server and a component that will display the ping result, which we will use from our first component.

We'll start out by creating a page component called Ping.vue in the directory client/component/local_quickstart/src/pages. It's worth noting that all component files use the PascalCase naming convention.

client/component/local_quickstart/src/pages/Ping.vue

Notice the individual technology chunks as described above, <template> for HTML and <script> for JavaScript, both contained within a single component.

Step 4: Creating a page in Totara Core that uses the component so that we can test it

Now we have a simple Tui component, we want to render it via PHP. We'll do this using the MVC (Model, view, controller) pattern. For more information, see the MVC pattern documentation.

This guide doesn’t cover creating the plugin. Here we only touch the files we need to in order to render the component.

Step 4a: Creating a page controller

First, we'll start out with the page controller. In your plugin's server directory (in this example it's /server/local/quickstart) ensure you have the classes directory, and within it make the controllers directory.

In the controllers directory, let's create our PHP controller class for our page ping. We'll name the controller the same as the page we want to control to make it easy to understand and follow.

Now, we'll define the controller class. The controller class will define a method called action which returns the Tui component we want to render (via tui_view).

server/local/quickstart/classes/controllers/ping.php

Step 4b: Creating the PHP page