| 1 |
efrain |
1 |
## Moodle Component Library
|
|
|
2 |
|
|
|
3 |
The Moodle UI component Library is built with the aim to provide a single repository
|
|
|
4 |
of Moodle UI components to be used for new and existing Moodle pages.
|
|
|
5 |
|
|
|
6 |
A Moodle UI component is a self-contained UI element originating from one source file
|
|
|
7 |
that can be used in different locations in core code, for example a button.
|
|
|
8 |
|
|
|
9 |
This plugin generates the documentation of the Moodle User Interface components. It
|
|
|
10 |
is build using the [Bootstrap](http://getbootstrap.com) docs and the [Hugo](https:://gohugo.io)
|
|
|
11 |
static site builder.
|
|
|
12 |
|
|
|
13 |
## Build the Component Library pages
|
|
|
14 |
|
|
|
15 |
After installing Node.js you can build the Component Library pages by running:
|
|
|
16 |
|
|
|
17 |
Grunt componentlibrary
|
|
|
18 |
|
|
|
19 |
When completed the Component Library will be available from Site Administration > Development > UI Component Library
|
|
|
20 |
|
|
|
21 |
Please note it is not possible to compile the component library html pages if the configuration option $CFG->admin is configured to have another value than 'admin'.
|
|
|
22 |
|
|
|
23 |
## How the Component Library was built
|
|
|
24 |
|
|
|
25 |
The Moodle grunt tasks were setup to include the node modules required for building a static site using
|
|
|
26 |
the hugo static site builder, the hugo-lunr-indexer for searching the component library and to prepare all the tasks
|
|
|
27 |
for building component library pages from Markdown files and the library styling using scss files. this way
|
|
|
28 |
all the build tasks for the library are included in Moodle's core grunt tasks
|
|
|
29 |
|
|
|
30 |
A new component library plugin was created inspired by the bootstrap docs system. The plugin serves HTML pages from
|
|
|
31 |
the docs folder in admin/tool/componentlibrary. The content of the docs folder is generated by running `grunt componentlibrary`.
|
|
|
32 |
|
|
|
33 |
### JS Files
|
|
|
34 |
When serving the HTML pages some additional JavaScript is loaded:
|
|
|
35 |
* clipboardwrapper.js and clipboard.js: This allows you to click a button to copy the contents of a code example to your clipboard so you can easily paste it in your code editor when you want to use the code example in your project
|
|
|
36 |
|
|
|
37 |
* search.js and lunr.js: When the component library docs folder is generated, the contents of the docs folder is indexed by the hugo-lunr-indexer npm module. This generates a json file in `/admin/tool/componentlibrary/hugo/site/data/my-index.json` containing page references to search words. The lunr.js amd module parses this search index and the search.js amd module interfaces the search input field with the lunr.js to show a dropdown with search results on user input
|
|
|
38 |
|
|
|
39 |
* mustache.js and jsrunner.js: The component library allows you to specify a core mustache template that should be loaded and displayed within the component library docs pages. The mustache.js module fetches the mustache template using a webservice call injecting it with custom variables for the templates if provided. the jsrunner.js fetches the JavaScript section of example code encapsulated in these tags {{#js}} custom js code {{/js}} and executes it. This way the component library can also fetch core js modules and render the result
|
|
|
40 |
|
|
|
41 |
### Example form
|
|
|
42 |
The component library includes an example moodle form in `/admin/tool/componentlibrary/classes/exampleform.php` that renders most form fields inside a component library page. Since the rendering of form fields require php the form fields cannot be included as mustache templates only. The example form does not contain all possible fields but enough to serve as a testing page when any of the form CSS changes
|
|
|
43 |
|
|
|
44 |
### A moodle icons page
|
|
|
45 |
The command line script `/admin/tool/componentlibrary/cli/fetchicons.php` was added to create a json file showing the list of available icons that can be called using the mustache {{#pix}} helper. The page showing the icons will show the FontAwesome icons and the old pix item that can still be used in custom themes.
|
|
|
46 |
|
|
|
47 |
### The hugo configuration
|
|
|
48 |
Hugo's configuration is stored in `/admin/tool/componentlibrary/config.yml`. It tells Hugo where to find the templates to create pages, how to handle syntax highlighting and more. For more information about the configuration options please visit the [Hugo](https:://gohugo.io) website
|
|
|
49 |
|
|
|
50 |
### The hugo templates
|
|
|
51 |
Hugo translates Markdown files into HTML files and wraps them in preconfigured templates. The templates define how the navigation for Hugo is rendered and can include Hugo specific syntax using partials and shortcodes. These translate syntax like {{< example >}} into a documentation block for code. See for `/admin/tool/componentlibrary/hugo/site/layouts/partials`
|
|
|
52 |
|
|
|
53 |
### The Bootstrap section of the component library
|
|
|
54 |
The component library include a selection of the documentation pages of the bootstrap project. The pages removed were the pages related to documentation of the Bootstrap project itself and all of the example pages where components are displayed. Any links to theme pages are changed to links to the original project using the docsref shortcode in `/admin/tool/componentlibrary/hugo/site/layouts/shortcodes/docsref.html`.
|
|
|
55 |
|
|
|
56 |
Removed docs pages were in these files and folders
|
|
|
57 |
|
|
|
58 |
* admin/tool/componentlibrary/content/bootstrap/getting-started/*
|
|
|
59 |
* admin/tool/componentlibrary/content/bootstrap/about/*
|
|
|
60 |
* admin/tool/componentlibrary/content/bootstrap/migration.md
|
|
|
61 |
* admin/tool/componentlibrary/content/bootstrap/extend/icons.md
|
|
|
62 |
* admin/tool/componentlibrary/content/bootstrap/browser-bugs.md
|
|
|
63 |
|
|
|
64 |
### Updating the bootstrap docs pages
|
|
|
65 |
|
|
|
66 |
For newer versions of Bootstrap download the most recent version of bootstrap from https://github.com/twbs/bootstrap
|
|
|
67 |
|
|
|
68 |
copy the contents of bootstrap/site/content/docs/{newversion} to
|
|
|
69 |
admin/tool/componentlibrary/content/bootstrap/
|
|
|
70 |
|
|
|
71 |
Remove any pages about the bootstrap project itself (see paragraph above).
|
|
|
72 |
|
|
|
73 |
Add a _index.md file in each subfolder of admin/tool/componentlibrary/content/bootstrap/, the contents of the _index.md file should look something like this:
|
|
|
74 |
---
|
|
|
75 |
title: "Components"
|
|
|
76 |
date: 2021-05-05T15:15:15Z
|
|
|
77 |
draft: true
|
|
|
78 |
weight: 20
|
|
|
79 |
---
|
|
|
80 |
Adding _index.md files ensures they show up as collapsable sections in the Component Library navigation
|
|
|
81 |
|
|
|
82 |
Copy changed files from bootstrap/site/data/ to admin/tool/componentlibrary/hugo/site/data/
|
|
|
83 |
|
|
|
84 |
Copy new files from bootstrap/site/layouts/shortcodes/ to admin/tool/componentlibrary/hugo/site/layouts/partials/. Leave changed files as is.
|
|
|
85 |
|
|
|
86 |
Try compiling the new component library pages using `grunt componentlibrary`. If anything is still missing from bootstrap you should see a message for more information.
|