Skip to content

Commit

Permalink
Updated documentaiton in README.md.
Browse files Browse the repository at this point in the history
  • Loading branch information
@michael-milette
michael-milette committed Jul 22, 2024
1 parent 128937e commit 7056aeb
Show file tree
Hide file tree
Showing 2 changed files with 179 additions and 21 deletions.
4 changes: 3 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Change Log
All notable changes to this project will be documented in this file.

## [2.5.2] 2024-07-19 (dev)
## [2.5.2] 2024-07-22 (dev)
### Added
- New {ifprofile shortname is "value"}...{/ifprofile} tag.
- New {ifprofile shortname is ""}...{/ifprofile} tag.
Expand All @@ -10,6 +10,8 @@ All notable changes to this project will be documented in this file.
- New {ifprofile shortname contains "value"}...{/ifprofile} tag.
- New {ifprofile shortname in "value"}...{/ifprofile} tag.
### Updated
- Added more documentation to README.md.
- Fixed links and updated table of contents in README.md.
- {categories0} tag now shows hidden categories if role has moodle/category:viewhiddencategories.
- {categories0menu} tag now shows hidden categories if role has moodle/category:viewhiddencategories.
- Fixed a couple of PHP 5.6 compatibility issues. Note that unit tests are still only compatible with PHP 7.1 and later.
Expand Down
196 changes: 176 additions & 20 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,28 +10,100 @@ FilterCodes filter plugin for Moodle

# Table of Contents

- [FilterCodes filter plugin for Moodle](#filtercodes-filter-plugin-for-moodle)
- [Table of Contents](#table-of-contents)
- [Basic Overview](#basic-overview)
- [Requirements](#requirements)
- [Download FilterCodes for Moodle](#download-filtercodes-for-moodle)
- [Installation](#installation)
- [Usage](#usage)
- [List of FilterCode tags](#list-of-filtercode-tags)
- [Define your own custom global tags](#define-your-own-custom-global-tags)
- [FilterCodes in a custom menu](#filtercodes-in-a-custom-menu)
- [Scrap'ing content](#scrapeing-content)
- [Back to section / Back to course](#back-to-section--back-to-course)
- [Optional FilterCodes for Moodle settings](#optional-filtercodes-for-moodle-settings)
- [List of FilterCode tags](#list-of-filtercode-tags)
- [Creating FilterCodes Documentation](#creating-filtercodes-documentation)
- [Profile](#profile)
- [System Information](#system-information)
- [UI Elements](#ui-elements)
- [For use in courses](#for-use-in-courses)
- [Categories](#categories)
- [Custom menu](#custom-menu)
- [URL](#url)
- [Content](#content)
- [Contact Form templates](#contact-form-templates)
- [Useful for creating Custom Contact Forms and Links](#useful-for-creating-custom-contact-forms-and-links)
- [Conditionally display content filters (All versions of Moodle)](#conditionally-display-content-filters-all-versions-of-moodle)
- [Logged in/out](#logged-inout)
- [Courses](#courses)
- [Roles](#roles)
- [Miscellanious](#miscellanious)
- [Conditionally display content filters (For Moodle Mobile app and Web services)](#conditionally-display-content-filters-for-moodle-mobile-app-and-web-services)
- [Conditionally display content filters (For Moodle Workplace)](#conditionally-display-content-filters-for-moodle-workplace)
- [HTML and "lang" tagging](#html-and-lang-tagging)
- [Define your own custom global tags](#define-your-own-custom-global-tags)
- [FilterCodes in a custom menu](#filtercodes-in-a-custom-menu)
- [General menu](#general-menu)
- [Admin menu](#admin-menu)
- [Developer Tools menu](#developer-tools-menu)
- [Theme Switcher menu](#theme-switcher-menu)
- [Enabling FilterCodes in the Custom Menu / Primary Navigation](#enabling-filtercodes-in-the-custom-menu--primary-navigation)
- [Technique A: Patching Moodle core](#technique-a-patching-moodle-core)
- [Technique B: Patching your Moodle theme](#technique-b-patching-your-moodle-theme)
- [For themes based on **boost** (Moodle 4.0 and later)](#for-themes-based-on-boost-moodle-40-and-later)
- [For themes based on **boost** (Moodle 3.2 to 3.11 and some 4.0+)](#for-themes-based-on-boost-moodle-32-to-311-and-some-40)
- [For themes based on the older **bootstrapbase** (Moodle 2.7 to 3.6)](#for-themes-based-on-the-older-bootstrapbase-moodle-27-to-36)
- [FilterCodes in HEAD](#filtercodes-in-head)
- [Scrape'ing content](#scrapeing-content)
- [Back to section / Back to course button](#back-to-section--back-to-course-button)
- [Optional FilterCodes for Moodle settings](#optional-filtercodes-for-moodle-settings)
- [Custom navigation support](#custom-navigation-support)
- [Escape tags](#escape-tags)
- [Hide completed courses](#hide-completed-courses)
- [Scrape tag support](#scrape-tag-support)
- [Show contact picture](#show-contact-picture)
- [Show contact's profile description](#show-contacts-profile-description)
- [Show hidden profile fields](#show-hidden-profile-fields)
- [Contact link type](#contact-link-type)
- [Show {categorycards} background](#show-categorycards-background)
- [Global custom tags](#global-custom-tags)
- [Customizing or translating the forms generated by the {form...} tags](#customizing-or-translating-the-forms-generated-by-the-form-tags)
- [Updating](#updating)
- [Uninstallation](#uninstallation)
- [Limitations](#limitations)
- [Language Support](#language-support)
- [Troubleshooting](#troubleshooting)
- [Frequently Asked Questions (FAQ)](#faq)
- [FAQ](#faq)
- [Answers to Frequently Asked Questions](#answers-to-frequently-asked-questions)
- [Can I combine/nest conditional tags?](#can-i-combinenest-conditional-tags)
- [How can {ifactivitycompleted} work for the completion of a combination of multiple activities?](#how-can-ifactivitycompleted-work-for-the-completion-of-a-combination-of-multiple-activities)
- [I am using FilterCodes on a multi-language site. Some of my non-FilterCode tags are not being processed. How can I fix this?](#i-am-using-filtercodes-on-a-multi-language-site-some-of-my-non-filtercode-tags-are-not-being-processed-how-can-i-fix-this)
- [How can I use this to pre-populate one or more fields in a Contact Form for Moodle?](#how-can-i-use-this-to-pre-populate-one-or-more-fields-in-a-contact-form-for-moodle)
- [Why do administrators see the text of all other roles when using {ifminxxxx}Content{/ifminxxxx} tags?](#why-do-administrators-see-the-text-of-all-other-roles-when-using-ifminxxxxcontentifminxxxx-tags)
- [Is there a tag to display...?](#is-there-a-tag-to-display)
- [Why does the {button} tag not work?](#why-does-the-button-tag-not-work)
- [How can I style the {coursecontacts} tag?](#how-can-i-style-the-coursecontacts-tag)
- [Do you have examples/samples of how tags work in my version of FilterCodes?](#do-you-have-examplessamples-of-how-tags-work-in-my-version-of-filtercodes)
- [When a user is logged out, the First name, Surname, Full Name, Email address and Username are empty. How can I set default values for these tags?](#when-a-user-is-logged-out-the-first-name-surname-full-name-email-address-and-username-are-empty-how-can-i-set-default-values-for-these-tags)
- [I added the "{mycoursesmenu}" to my custom menu. How can I hide it if the user is not logged in?](#i-added-the-mycoursesmenu-to-my-custom-menu-how-can-i-hide-it-if-the-user-is-not-logged-in)
- [How can I add a "Logout" link in my custom menu?](#how-can-i-add-a-logout-link-in-my-custom-menu)
- [How can I create a menu that is just for administrators or some other roles?](#how-can-i-create-a-menu-that-is-just-for-administrators-or-some-other-roles)
- [Why is the IP Address listed as 0:0:0:0:0:0:0:1?](#why-is-the-ip-address-listed-as-00000001)
- [Why does it show me as enrolled on the frontpage?](#why-does-it-show-me-as-enrolled-on-the-frontpage)
- [I added the {recaptcha} tag in my webform. Why doesn't the reCAPTCHA show up?](#i-added-the-recaptcha-tag-in-my-webform-why-doesnt-the-recaptcha-show-up)
- [How can I get the {scrape} tag to work?](#how-can-i-get-the-scrape-tag-to-work)
- [How can I scrape content from more than one web page or more than one website?](#how-can-i-scrape-content-from-more-than-one-web-page-or-more-than-one-website)
- [How can I scrape content based on a pattern of HTML tags instead of just one HTML tag with a class or id? Example, an h1 tag inside the div class="content" tag.](#how-can-i-scrape-content-based-on-a-pattern-of-html-tags-instead-of-just-one-html-tag-with-a-class-or-id-example-an-h1-tag-inside-the-div-classcontent-tag)
- [How can I get the {getstring} tag to work? It doesn't seem to be replaced with the correct text.](#how-can-i-get-the-getstring-tag-to-work-it-doesnt-seem-to-be-replaced-with-the-correct-text)
- [How can I customize or translate the forms generated by the {form...} tags?](#how-can-i-customize-or-translate-the-forms-generated-by-the-form-tags)
- [Is there more information about the {ifprofile shortname ...} tag?](#is-there-more-information-about-the-ifprofile-shortname--tag)
- [What are the supported dateTimeFormat formats?](#what-are-the-supported-datetimeformat-formats)
- [Are there any security considerations?](#are-there-any-security-considerations)
- [How can I get answers to other questions?](#how-can-i-get-answers-to-other-questions)
- [Contributing](#contributing)
- [Contributors](#contributors)
- [Pending Features](#pending-features)
- [Motivation for this plugin](#motivation-for-this-plugin)
- [Further information](#further-information)
- [Further Information](#further-information)
- [License](#license)


# Basic Overview

FilterCodes filter for Moodle enables content creators to easily customize and personalize Moodle sites and course content using over 135 plain text tags that can be used **almost** anywhere in Moodle. Support may also vary depending on the theme used.
Expand Down Expand Up @@ -524,7 +596,17 @@ Notes:

Even better, try out the dynamic **{menudev}** tag. It includes all of the above and more. Best of all, it only includes menu items for the developer tools that you have installed. Just replace everything below the words "Dev tools" and above the "{/ifdev}" line with **{menudev}**. The content that is generated by this tag is not user-configurable however we are open to suggestions.

## FilterCodes in custom menus
### Theme Switcher menu

It's true, FilterCodes includes a built-in theme switcher which can be very especially useful for Moodle developers. It allows you to switch theme from a list of installed themes while staying on the current page. At the bottom of the list, you will also find handy links to Moodle's **Advanced Theme Settings** (formerly known as Theme Settings) as well as the settings for the current active theme.

Add the following tag to your custom menu:

{menuthemes}

Note that this is a top level menu that will only be visible to Site Administrators, not regular users. Also, in order for this to work, you must enable theme switching in ** Site Administration > Appearance > Advanced Theme Settings** (formerly known as Theme Settings).

## Enabling FilterCodes in the Custom Menu / Primary Navigation

Note: The source code in this section was last updated in April 2022 for Moodle 4.0 and last tested in January 2024 for Moodle 4.3 and 4.4 (ALPHA) compatibility.

Expand All @@ -534,7 +616,9 @@ FilterCodes can work in custom menus but, unfortunately, only if the theme suppo

If you are using Moodle 3.5 or later, there are two ways to make FilterCodes work in Moodle's custom menu (also called primary menu in Moodle 4.0+):

**Technique A**: The preferred method is to patch your instance of Moodle using Git. If you did not install Moodle using Git, you can still apply the changes but you will need to do so manually. FYI: The patches for Moodle 3.7 to 3.11 are identical.
### Technique A: Patching Moodle core

The preferred method is to patch your instance of Moodle using Git. If you did not install Moodle using Git, you can still apply the changes but you will need to do so manually. FYI: The patches for Moodle 3.7 to 3.11 are identical.

Even better, encourage Moodle HQ to enable this functionality in future releases of Moodle. For more information and to vote for this functionality, see:

Expand All @@ -561,11 +645,13 @@ Example: To apply the patch for Moodle using git (change the "M403" for other ve
git cherry-pick FETCH_HEAD
```

This is usually enough to make the filters work in the custom menu. However, we have noticed it may not work with some Moodle themes, most notably premium themes. Those themes will need to be patched using the technique B.
This is usually enough to make the filters work in the custom menu. However, we have noticed it may not work with some Moodle themes, most notably premium themes. Those themes will need to be patched using the Technique B.

**Technique B**: If technique A does not work for you, you will need to integrate a few lines of code into your Moodle theme, or ask your theme's developer/maintainer to apply this change for you. Be sure to follow the correct instructions for your version of Moodle.
### Technique B: Patching your Moodle theme

### For themes based on **boost** (Moodle 4.0 and later)
If technique A does not work for you, you will need to integrate a few lines of code into your Moodle theme, or ask your theme's developer/maintainer to apply this change for you. Be sure to follow the correct instructions for your version of Moodle.

#### For themes based on **boost** (Moodle 4.0 and later)

There is no tested patch available for all 3rd party Moodle 4.0 themes. It is recommended to use Moodle core patch above which is known to work.

Expand Down Expand Up @@ -613,9 +699,9 @@ Add this code to the core_renderer section (probably located in /theme/yourtheme
}
```

### For themes based on **boost** (Moodle 3.2 and later)
#### For themes based on **boost** (Moodle 3.2 to 3.11 and some 4.0+)

Note: Supported in Moodle 3.2 and later. If you are using Moodle 4.0 or later, you **must also** integrate the patch **For themes based on boost (Moodle 4.0 and later)** above.
Note: Supported in Moodle 3.2 to 3.11. Most Moodle 4.0 themes do not require this patch but some that were ported for 4.0+ still do.

Add the following code to core_renderer section (often found in /theme/yourtheme/classes/output/core_renderer.php) of your theme. Note: Your theme may even already have such a class (they often do):

Expand Down Expand Up @@ -689,11 +775,11 @@ Add the following code to core_renderer section (often found in /theme/yourtheme
}
```

### For themes based on the older **bootstrapbase** (Moodle 2.7 to 3.6)
#### For themes based on the older **bootstrapbase** (Moodle 2.7 to 3.6)

Note: Supported in Moodle 2.7 to 3.6.

Add the following code to core_renderer section of your theme for Moodle 2.7 to 3.6. Be sure to replace "themename" with the name of the theme's directory. Note: Your theme may even already have such a class (they often do):
Add the following code to core_renderer section (often found in /theme/yourtheme/classes/output/core_renderer.php) of your theme. Note: Your theme may even already have such a class (they often do). The important lines are chunk of code that starts with "// Filter custom menu items..." including the 5 lines that follow it:

```php
class theme_themename_core_renderer extends theme_bootstrapbase_core_renderer {
Expand Down Expand Up @@ -733,6 +819,36 @@ Add the following code to core_renderer section of your theme for Moodle 2.7 to
}
```

## FilterCodes in HEAD

Like the Custom menu/Primary Naviation, most themes do not support applying FilterCodes to the Within HEAD field found in Site Administration > Appearance > Additional HTML. This is unfortunate because it can very useful to conditionally include Styles or JavaScript depending on who the user is, their role, a field in their user profile, or a custom field in a course.

To enable this functionality requires a developer to integrate the following code to the core_renderer class' standard_head_html() method of your theme:

```php
public function standard_head_html() {
: : : : : : : :
// Backup the current value of CFG->additionalhtmlhead.
$additionalhtmlhead = trim($CFG->additionalhtmlhead ?? '');

if (!empty($additionalhtmlhead)) {
// Apply Moodle filters to additional head content.
$context = context_system::instance();
$options = ['context' => $context, 'noclean' => true, 'trusted' => true, 'para' => false];
$CFG->additionalhtmlhead = format_text($additionalhtmlhead, FORMAT_HTML, $options);
}

// Output using the regular standard_head_html().
$output = parent::standard_head_html();

// Restore the original value of $CFG->additionalhtmlhead.
$CFG->additionalhtmlhead = $additionalhtmlhead;
: : : : : : : :
}
```

A slightly different version could be applied to Moodle core code if you prefer.

## Scrape'ing content

Note: This feature must be enabled in FilterCodes settings.
Expand Down Expand Up @@ -763,7 +879,7 @@ If the URL fails to produce any content (broken link for example), a message wil

If the matching tag, class and/or id cannot be found, will return all of the page content without being filtered.

## Back to section / Back to course
## Back to section / Back to course button

Help students navigate your Moodle site by implementing this handy-dandy BACK button. Works at both the section and activity level.

Expand All @@ -789,7 +905,7 @@ Experimental: Only available in Moodle 3.2, 3.3 and 3.4. Enable support for Filt

NOTE: Does not filter tags on the Moodle Theme Settings page. This is not a bug, just a limitation.

For information on enabling FilterCodes in custom menus of other versions of Moodle, see [FilterCodes in a custom menu](#filtercodes-in-a-custom-menu)
For information on enabling FilterCodes in custom menus of other versions of Moodle, see [Enabling FilterCodes in the Custom Menu / Primary Navigation](#enabling-filtercodes-in-the-custom-menu--primary-navigation)

### Escape tags

Expand Down Expand Up @@ -1311,7 +1427,47 @@ Verify that the component (plugin) name and/or the string key are correct. If a

See **Customizing or translating the forms generated by the {form...} tags** in the [Usage](#usage) section.

### What are the Supported dateTimeFormat formats?
### Is there more information about the {ifprofile shortname ...} tag?

{ifprofile shortname ...} is a conditional tag that enables you to display information depending on the value of fields in a user's profile.

Here is a list of the various options you can use with it:

{ifprofile shortname is "value"}...{/ifprofile}
{ifprofile shortname not "value"}...{/ifprofile}
{ifprofile shortname is ""}...{/ifprofile}
{ifprofile shortname not ""}...{/ifprofile}
{ifprofile shortname contains "value"}...{/ifprofile}
{ifprofile shortname in "value"}...{/ifprofile}

**Notes:**

The only comparison operators currently supported are 'is', 'not', 'contains' and 'in'.

The "value" must always be enclosed in quotes. Use an empty set of quotes to compare the value to an empty field.

The shortname can be any visible custom profile fields, unless the FilterCodes ifprofilefiedonlyvisible setting is unchecked, as well as the core profile fields including:

* id
* username
* auth
* idnumber
* email
* institution
* department
* city
* country
* timezone
* lang

Important: The specified value must be the value that is stored in the database, which may be different than what is displayed when you view a user profile. Here are some examples:

* You must specify CA for the country of Canada, not Canada, when comparing to the country field.
* If your profile field contains a multi-language string, you need to specify the string as it is before it is processed by Moodle language filters.
* For dropdown fields, you may need to view the HTML code to see what the actual values are for a field.
* For checkboxes, the checked value is 1, unchecked is 0.

### What are the supported dateTimeFormat formats?

The date and time formats, defined in Moodle (langconfig.php)[https://github.com/moodle/moodle/blob/master/lang/en/langconfig.php], control how dates and times will be displayed.

Expand Down

0 comments on commit 7056aeb

Please sign in to comment.