Quick-start guide: Creating your first component
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.
- 1 Objective
- 2 Step 1: npm run tui-build-watch
- 3 Step 2: Creating a new Tui component
- 4 Step 3: Creating a page component
- 5 Step 4: Creating a page in Totara Core that uses the component so that we can test it
- 6 Step 5: Create a component to implement the ping status UI
- 7 Step 6: Include the ping status component
- 8 Step 7: Include a button component
- 9 Step 8: Add SCSS styles to our status component
- 10 Step 9: Request data using Apollo and GraphQL
- 11 Step 10: Adding a filter to the Apollo helper
- 12 Step 11: Add a unit test with Jest
- 13 Wrap up
- 14 Legacy rendering from PHP
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.
npm run tui-build-watch
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.
npm run tui-init local_quickstart vendorname
mkdir client/component/local_quickstart/src/components/ping
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
{
"component": "local_quickstart",
"vendor": "vendorname"
}
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