first commit

admin/tool/componentlibrary/content/library/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Component library"
+date: 2017-10-17T15:26:15Z
+draft: false
+weight: 20
+---

admin/tool/componentlibrary/content/library/adding-images.md

@@ -0,0 +1,53 @@
+---
+layout: docs
+title: "Adding images"
+date: 2020-02-04T09:40:32+01:00
+draft: false
+weight: 2
+---
+
+## Images
+
+Images that need to be show in the component library should be placed in a separate folder for each new page.
+
+The Markdown file for this page is located here:
+
+```
+└── content
+     └── moodle
+         └── getting-started
+            └── adding-images.md
+```
+
+To access images for this page create a new folder here.
+
+```
+└── static
+     └── moodle
+         └── getting-started
+            └── adding-images
+```
+
+Place your images in this new folder:
+
+```
+└── static
+     └── moodle
+         └── getting-started
+            └── adding-images
+                ├── wildebeest-1200.jpg
+                ├── kitten1.png
+                └── kitten2.png
+```
+
+To use images use this syntax:
+
+Syntax for markdown (.md) files:
+
+```
+{{</* image "wildebeest-1200.jpg" "Image of a Wildebeest" "img-fluid" */>}}
+```
+
+Rendered result on this page:
+
+{{< image "wildebeest-1200.jpg" "Image of a Wildebeest" "img-fluid">}}

admin/tool/componentlibrary/content/library/adding-pages.md

@@ -0,0 +1,68 @@
+---
+layout: docs
+title: "Adding pages"
+date: 2020-03-02T10:13:29+01:00
+draft: false
+weight: 2
+---
+
+## Adding or editing a page in the component library
+
+In this step-by-step guide you will create a new page called Breadcrumb navigation and compile it from a markdown text file to a HTML page in the component library.
+
+To add a page to the component library on your local machine navigate open your editor or file manager and create a new markdown text file in folder /content/moodle/components/breadcrumbs.md
+
+
+```
+└── content
+    └── moodle
+       └── components
+          └── breadcrumbs.md
+```
+
+Open the file in your favourite editor and start it with some metadata, we call this syntax [frontmatter](https://gohugo.io/content-management/front-matter/).
+
+```
+---
+layout: docs
+title: "Breadcrumb navigation"
+date: 2020-03-02T10:13:29+01:00
+draft: false
+---
+```
+
+Make sure you add these characters `---` before and after your metadata. You can change the title and date to match your document.
+
+## Run the component library Grunt task.
+
+In your terminal run the command `npm install` and then `grunt componentlibrary` in your Moodle root folder. This will install all required resources and compile the componentlibrary pages. If you do not have npm installed on your system please visit [npmjs.com](https://www.npmjs.com/get-npm) to learn how to get a working setup.
+
+
+The output should be similar to this:
+
+```
+Running "componentlibrary:docsBuild" task
+Building sites …
+                   | EN
++------------------+-----+
+  Pages            | 113
+  Paginator pages  |   0
+  Non-page files   |  18
+  Static files     |  18
+  Processed images |   0
+  Aliases          |   7
+  Sitemaps         |   1
+  Cleaned          |   0
+
+Total in 913 ms
+Running "componentlibrary:cssBuild" task
+Rendering Complete, saving .css file...
+Wrote CSS to /var/www/repositories/cl_master/moodle/admin/tool/componentlibrary/hugo/dist/css/docs.css
+Wrote Source Map to /var/www/repositories/cl_master/moodle/admin/tool/componentlibrary/hugo/dist/css/docs.css.map
+Running "componentlibrary:indexBuild" task
+
+Done.
+
+```
+
+The grunt watch task will pick up changes in the componentlibrary Markdown files and Scss files. So run `grunt watch` if you want to edit the pages.

admin/tool/componentlibrary/content/library/component-library-backend.md

@@ -0,0 +1,65 @@
+---
+layout: docs
+title: "Component Library Backend"
+date: 2021-05-27T15:43:07+01:00
+group: moodle-components
+draft: false
+---
+
+## Creating new Pages
+
+Pages for the component library are written in [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) and a number of [Hugo](https://gohugo.io) powered tools.
+
+To add a page simply create a Markdown file in content/moodle/[foldername]/
+
+## Generating the HTML versions of the Markdown files
+
+The HTML pages for this library are created in the docs/ folder of the componentlibrary
+
+Please run `npm install` in the $moodleroot folder to fetch all requirements for contributing to this library.
+
+Once all requirements are installed you all you need to do is run `grunt componentlibrary` to create the component library pages.
+
+## Location of Markdown files
+
+```
+└── content
+    ├─ bootstrap
+    └─ moodle
+```
+
+## HTML output folder
+
+```
+├── docs
+```
+
+## Page setup using the Hugo static site builder
+
+The hugo config file can be found in /admin/tool/componentlibrary/config.yml
+
+The HTML and CSS for the component library pages are found here:
+
+```
+└─── hugo
+    ├── archetypes
+    ├── dist
+    ├── scss
+    └─- site
+```
+
+`archetypes` are template markdown files used when creating a new hugo page.
+
+`dist` CSS and JavaScript for use in Hugo pages
+
+`scss` The SCSS used to generate the docs css for the Component Library.
+
+`site` The page templates for hugo that include the left hand menu, navbar etc. And the templates to render example code shown in this component library.
+
+
+## Creating a new docs page
+
+Find the example page in `/admin/tool/componentlibrary/content/moodle/components/example.md` and use it as a template for your new
+page. In the top part of the example.md file you will find the `frontmatter` configuration between the `---` characters. This part is used when hugo generates the page name and description. Change it to describe the new page you are creating.
+
+The document setup is not fixed at all, the example page is just there for inspiration when starting to describe a Moodle component.

admin/tool/componentlibrary/content/library/example-files.md

@@ -0,0 +1,75 @@
+---
+layout: docs
+title: "Example files"
+date: 2020-01-21T13:00:00+08:00
+draft: false
+---
+
+There may be times that we need to provide example implementations of the component being documented in order to further demonstrate how to use a component.
+
+We need to put these files in `examples` folders. It helps organise things and makes the maintenance of the component library code easier by allowing us to distinguish examples from the actual component library code.
+
+
+## Example pages
+
+Example pages can be placed under the `componentlibrary/examples` folder.
+
+See the `formfields.php` example page as an example:
+
+```
+componentlibrary
+└── examples
+     └── formfields.php
+```
+
+This can be embedded in the component's documentation page via iframe. For example in `componentlibrary/content/moodle/form-elements.md`:
+
+```
+<iframe src="../../../../examples/formfields.php" style="overflow:hidden;height:4000px;width:100%;border:0" title="Moodle form fields"></iframe>
+```
+
+## Example classes
+
+Example classes can be placed under the `componentlibrary/classes/local/examples/[componentname]` folder.
+
+In our form fields example, we have the `\tool_componentlibrary\local\examples\formelements\example` class under `componentlibrary/classes/local/examples/formelements`.
+
+## Example templates
+
+Example templates can be placed under the `componentlibrary/templates/examples/[componentname]` folder.
+
+In our form fields example, we have the `tool_componentlibrary/examples/formelements/toggles` template under `componentlibrary/templates/examples/formelements`.
+
+## Summary
+
+Please put example files in their designated `examples` folders.
+```
+componentlibrary
+└── classes
+    └── local
+        └── examples
+            └── [component folder]
+                └── [example classes]
+└── examples
+    └── [example page]
+└── templates
+    └── examples
+        └── [component folder]
+            └── [example templates]
+```
+
+For the form elements documentation, its example files are in the following `examples` folders.
+```
+componentlibrary
+└── classes
+    └── local
+        └── examples
+            └── formelements
+                └── example.php
+└── examples
+    └── formfields.php
+└── templates
+    └── examples
+        └── formelements
+            └── toggles.mustache
+```

admin/tool/componentlibrary/content/library/getting-started.md

@@ -0,0 +1,35 @@
+---
+layout: docs
+title: "Getting started"
+date: 2020-01-28T10:13:29+01:00
+group: library
+draft: false
+weight: 1
+---
+<style>
+  .bd-title {
+    display: none;
+  }
+</style>
+<div class="d-flex">
+  <div class="w-50 ml-auto mr-auto">
+{{< image "logo.png" "The Moodle logo" "img-fluid">}}
+</div>
+</div>
+
+## The Moodle UI Component library
+
+The Moodle UI component library is the central location for documenting frequently used User Interface components used in Moodle. Moodle UI components are used to represent distinct UI elements, such as tables, buttons, dialogs, and others.
+The main purpose of this library is to provide documentation for designers and developers when doing frontend development of new features.
+
+This library allows you to create user interfaces more efficiently, it is a tool for visual designers, front-end developers, ux developers and anybody creating core Moodle code or Moodle extensions.
+
+Whenever a new Moodle feature is created or updated the building blocks for the UI of the feature should be documented in this library.
+
+## Bootstrap docs
+
+A large part of this library contains information about [Bootstrap](http://getbootstrap.com) components which are shipped with every Moodle installation. Bootstrap contains a lot of useful components and utilities which can safely be used for frontend development. For example, instead of adding custom CSS to add some padding in a box you should really look at the [spacing](/moodle-3.9/utilities/spacing) utilities from Bootstrap instead.
+
+## Build with Hugo
+
+This page and all other pages in the Component library are build using [Hugo](http://gohugo.io), a static site generator that can turn documentation written in Markdown into nice pages like the one you are looking at right now.

admin/tool/componentlibrary/content/library/moodle-javascript.md

@@ -0,0 +1,44 @@
+---
+layout: docs
+title: "Moodle JavaScript"
+date: 2020-01-14T13:38:37+01:00
+group: moodle-components
+draft: false
+menu: "main"
+---
+
+## Running AMD modules
+
+When using this (shortcode) syntax you can showcase your HTML and add some RequireJS style Javascript that will call core AMD modules.
+
+In order for this to work you need to use the JavaScript syntax used in core Mustache templates. See the ```{{js}}``` tags in this example below:
+
+{{< example >}}
+<div id="toasttest" role="alert" aria-live="assertive" aria-atomic="true" class="toast" data-autohide="false">
+  <div class="toast-header">
+    <img src="http://placekitten.com/50/50" class="rounded mr-2" alt="PlaceKitten">
+    <strong class="mr-auto">Bootstrap</strong>
+    <small>11 mins ago</small>
+    <button type="button" class="ml-2 mb-1 close" data-dismiss="toast" aria-label="Close">
+      <span aria-hidden="true">&times;</span>
+    </button>
+  </div>
+  <div class="toast-body">
+    Hello, world! This is a toast message.
+  </div>
+</div>
+{{#js}}
+require(
+[
+    'jquery',
+    'theme_boost/toast',
+],
+function(
+    $,
+    Toast
+) {
+    var root = $('#toasttest');
+    root.toast('show');
+});
+{{/js}}
+{{< /example >}}

admin/tool/componentlibrary/content/library/moodle-templates.md

@@ -0,0 +1,53 @@
+---
+layout: docs
+title: "Moodle templates"
+date: 2020-01-14T13:38:37+01:00
+group: moodle-components
+draft: false
+menu: "main"
+---
+
+## Moodle templates
+
+[Moodle templates](https://moodledev.io/docs/guides/templates) are use to write HTML and Javascript using mustache files.
+
+If you are creating your own pages in the UI Component library you can load core templates using this (shortcode) syntax:
+
+```
+{{</* mustache template="core/notification_error" */>}}
+{{</* /mustache */>}}
+```
+
+This is the result of adding the core/notification template on this page:
+
+{{< mustache template="core/notification_error" >}}
+{{< /mustache >}}
+
+This allows you to document any mustache template in the component library.
+
+## Moodle templates with custom data
+
+Not all templates found in Moodle core are will documented with example JSON formatted data (see the variables tab for the notification_error). To use custom Json data please use this (shortcode) syntax:
+
+```
+{{</* mustache template="core/notification_error" */>}}
+{
+    "message": "Your pants are awesome!",
+    "closebutton": 1,
+    "announce": 1,
+    "extraclasses": "foo bar"
+}
+{{</* /mustache */>}}
+```
+
+
+This is the result of adding the core/notification template on this page:
+
+{{< mustache template="core/notification_error" >}}
+{
+    "message": "Your pants are awesome!",
+    "closebutton": 1,
+    "announce": 1,
+    "extraclasses": "foo bar"
+}
+{{< /mustache >}}

admin/tool/componentlibrary/content/library/syntax-highlighting.md

@@ -0,0 +1,105 @@
+---
+layout: docs
+title: "Syntax highlighting"
+description: Use Hugo shortcodes for Syntax highlighting.
+date: 2020-02-04T09:40:32+01:00
+draft: false
+weight: 3
+---
+
+## Using Shortcodes for syntax
+
+Using this (shortcode) syntax you can higlight programming syntax in the component library
+
+## HTML highlighting
+
+Syntax for markdown (.md) files:
+
+```
+{{</* highlight html */>}}
+<div class="myclass">
+  This is an example.
+</div>
+{{</* /highlight  */>}}
+```
+Rendered result on this page:
+
+{{< highlight html >}}
+<div class="myclass">
+  This is an example.
+</div>
+{{< /highlight >}}
+
+## PHP shortcode
+
+Syntax for markdown (.md) files:
+
+```
+{{</* php */>}}
+  $mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
+{{</* /php  */>}}
+```
+Rendered result on this page:
+
+{{< php >}}
+  $mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
+{{< /php >}}
+
+## Highlight shortcode
+
+Syntax for markdown (.md) files:
+
+```
+{{</* highlight js */>}}
+var config = {
+    test: null,
+    selector: '[data-drag-type=move]'
+};
+{{</* /highlight  */>}}
+```
+Rendered result on this page:
+
+{{< highlight js >}}
+var config = {
+    test: null,
+    selector: '[data-drag-type=move]'
+};
+{{< /highlight >}}
+
+
+## Example shortcode
+
+The example shortcode shows the HTML source with syntax highlighting and renders it on the page. This shortcode takes the following arguments:
+
+show_markup="true/false"
+show_preview="true/false"
+
+
+
+
+```
+{{</* example */>}}
+<div class="input-group">
+  <input type="text" class="form-control" placeholder="Search">
+  <div class="input-group-append">
+    <button class="btn btn-primary" type="button">
+        <i class="fa fa-search"></i>
+    </button>
+  </div>
+</div>
+{{#js}}
+    window.console.log('hello');
+{{/js}}
+{{</* /example  */>}}
+```
+
+{{< example >}}
+<div class="input-group">
+  <input type="text" class="form-control" placeholder="Search">
+  <div class="input-group-append">
+    <button class="btn btn-primary" type="button">
+        <i class="fa fa-search"></i>
+    </button>
+  </div>
+</div>
+{{< /example >}}