.. include:: /shortcuts.rstext .. index:: pair: Administration; Extensions single: Site administrator; Extensions .. _extensions: Extensions ---------------- *Administration → Extensions* .. note:: *Extensions* is only accessible by site administrators. Extensions in Mahara serve to provide certain functionality in the system. Extensions can be installed at any point and can also be hidden. .. index:: pair: Extensions; Plugins single: Site administrator; Plugins .. _plugins: Plugin administration ~~~~~~~~~~~~~~~~~~~~~~~~~ *Administration → Extensions → Plugin administration* The *Plugin administration* lists all the plugins that are currently installed on your Mahara instance and provides a link to the plugin configuration settings where available. Plugins in Mahara are always installed and can be accessed if users know the URLs and would otherwise have access. Rather than enabling and disabling the functionality, plugins are hidden or made visible by clicking on the *Hide* or *Show* buttons beside the plugins. When hiding an artefact type plugin, Mahara stops the display of the blocks related to it as well. .. figure:: /images/administration/plugin_install_extensions.* :alt: Warning when a plugin is not yet installed Warning when a plugin is not yet installed If you added a plugin to your site's codebase or if a new plugin was added to Mahara since the last upgrade that you performed, you will need to install it. A plugin that is not yet fully installed is marked with a warning and :index:`listed first ` in its section. Click the *Install* link to start the installation process. In order to delete a plugin completely, you must delete the code and all database tables that pertain to the plugin. Additionally, you need to delete it from a number of system tables, e.g. "artefact", "artefact_config", "artefact_cron", etc. As an example, view the `information on how to uninstall the My Learning plugin `_. .. note:: Core Mahara functionality can be made unavailable to users by hiding it. This may be useful if you connect Mahara to another system that already provides this functionality or if you do not wish your users to use that functionality. However, the decision about hiding a functionality should be considered thoroughly as it may also mean that users may not be able to have as many artefacts available to them as they could have. In the following, only the plugins that have additional settings are discussed. .. index:: pair: Plugins - configurable; Folder single: Default sort order of files in a folder block single: Allow viewers to download files in a folder block .. _plugin_folderblock: Blocktype: File / folder ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can decide the default sort order for files displayed in a *Folder* block and whether viewers of portfolio pages that contain a *Folder* block should be able to download the contents of the folder as zip file in one go. .. figure:: /images/administration/plugin_file_folder.* :alt: Configure the Folder block Configure the *Folder* block #. **Default sort order of files**: Decide whether the default sort order for displaying files in a *Folder* block should be alphabetically ascending or descending. .. note:: Page authors can change the sort order for each block. #. **Download folders as zip files**: Switching this option to "Yes", you can download the contents of a folder displayed in a *Folder* block as zip file. Thus, it is very easy for a viewer to grab all files at once and download them to their computer. .. seealso:: Site administrators decide in the :ref:`Artefact type: File settings ` for how long the zip file is kept on the server. .. index:: pair: Plugins - configurable; Image gallery single: Configuration of external image galleries .. _plugin_imagegallery: Blocktype: File / gallery ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can provide additional image gallery settings and also allow your users to make Flickr and Photobucket image galleries available. The settings you make on this page will be the default settings for all users. .. figure:: /images/administration/plugin_file_gallery.* :alt: Configure the Image gallery block Configure the *Image gallery* block #. **Use Slimbox2**: Switch this option to "Yes" if you want to enlarge images from your image gallery on the page in an overlay instead of opening them in a new window. #. **Use photo frame**: Turn this option on if you want to put a frame around the thumbnail of each photo in photo galleries. #. **Maximum photo width**: Set the maximum width (in pixel) to which the photos will be resized when viewed with Slimbox2. #. **Flickr API key**: If you want to allow users to display photos from Flickr, you need a valid Flickr API key. You can `apply for the key at Flickr `_. #. **Photobucket API key**: If you want to allow users to display photos from Photobucket, you need a valid API and private API key. You can get them from the developer page of `Photobucket `_. #. **Photobucket API private key**: Provide the private API key from Photobucket that you will have received. #. Click the *Save* button to keep your changes. .. index:: pair: Plugins - configurable; Embedded media single: Configurable default video size of "Embedded media" .. _plugin_internalmedia: Blocktype: File / internalmedia ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Configure which file types users can embed into the :ref:`Embedded media block `. If you disable a file type that has already been used in a block, it will not be rendered any more. Mahara comes with `Video.js `_, a :index:`media player ` that can play a number of media files and does not require Flash (though it does have a Flash fallback option). Other video file types can be enabled, but users must have the appropriate software installed on their computers and the respective plugins enabled in their browsers to play them. .. figure:: /images/administration/plugin_file_internalmedia.* :alt: Configure the Embedded media block Configure the *Embedded media* block #. Turn on the file types that you wish your users to be able to show on their portfolio pages. #. Click the *Save* button to keep your changes. .. note:: If you allow the embedding of file types that cannot be played by Video.js, some users may not have the necessary software installed for displaying these file types. :index:`Here's ` an overview of the video and audio file formats that can be played by Video.js and which browsers can view them. Only because Video.js supports them does not mean that all browsers can play them. They still need to support a specific file format themselves. Listed are only the browsers that Mahara supports. iOS devices may not always display MP4 files as the devices may only recognize the MPEG4 "Baseline" profile rather than the "High" profile. You can read the `Apple specifications `_ and convert a video if needed using `Handbrake `_. Newer iOS devices (from the iPhone 5S on) should play "High" profile videos. .. list-table:: :header-rows: 1 * - File format - Chrome - Chrome for Android - Firefox - Internet Explorer / Edge - Opera - Safari (incl. iOS) * - 3GPP media file - - - - - - * - FLV Flash movie (requires Flash) - |check| - - |check| - - |check| - * - MP3 audio - |check| - |check| - |check| - |check| - |check| - |check| * - MP4 video (H.264) - |check| - |check| - |check| - |check| - |check| - |check| * - MPEG movie - - - - - - * - OGA audio - |check| - |check| - |check| - - |check| - * - OGG Vorbis audio file - |check| - |check| - |check| - - |check| - * - OGV video - |check| - - |check| - - |check| - * - SWF flash movie (requires Flash) - - - - - - * - WEBM video file - |check| - |check| - |check| - - |check| - .. note:: While you can upload any file fromat from any computer or Android device, you are not able to upload audio files from an iOS device. You can only upload .mov video files. These require a browser plugin to be played and are not served via Video.js. AVI and WMV files can only be played on computers running Windows unless you have a browser plugin installed on another operating system. .. index:: pair: Plugins - configurable; Text .. _plugin_text: Blocktype: Text ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can convert :ref:`Note ` blocktypes to :ref:`Text ` blocktypes across the entire instance. .. figure:: /images/administration/plugin_text.* :alt: Configure text settings Configure text settings #. Mahara calculates how many notes can be converted. Notes with the following characteristics are included in the conversion process. Notes that: * have not been re-used in another block; * do not have a license attached; * do not use tags; * do not have any attachments; * have not received any comments. #. Turn on the option **Convert "Note" blocks** to convert all notes. #. Click the *Save* button to start the conversion process. This may take some time depending on how many notes are to be converted. .. seealso:: If you have a large site, the conversion of notes to text may take a very long time. :index:`It ` can be beneficial to use the `command-line script `_. .. index:: pair: Plugins - configurable; Wall .. _plugin_wall: Blocktype: Wall ^^^^^^^^^^^^^^^^^^^ You can limit the number of characters that are allowed for :ref:`wall ` posts in this configuration setting. Existing posts will not be changed. .. figure:: /images/administration/plugin_wall.* :alt: Configure wall settings Configure wall settings #. Choose the maximum number of characters for your wall posts. #. Click the *Save* button to keep your changes. .. index:: pair: Plugins - configurable; Comments .. _plugin_comments: Artefact type: Comments ^^^^^^^^^^^^^^^^^^^^^^^^^ Turn comment ratings on to enable ratings in the comment section on artefacts and pages. :index:`You ` can change the look of the comment ratings as well as the scale. .. note:: Ratings cannot be on their own. They require either a comment or a file attachment. .. figure:: /images/administration/plugin_comment.* :alt: Enable comment ratings Enable comment ratings #. **Enable comment ratings**: Switch to "Yes" to enable comment ratings. #. **Icon to use to display ratings**: Use the drop-down menu to select the icon that you want to use for your ratings. You can choose between: * Star |star| * Heart |heart| * Thumbs up |thumbs up| * Tick |tick| #. **Number of rating choices**: Choose the scale that users will see when rating comments. .. note:: If you change the number of rating choices, the ratings themselves will not be recalculated to fit that new scale. #. **Colour**: Use the colour picker to select the colour for your icon or enter the `hexadecimal color code `_. #. **Generated example**: See a preview of what your comment ratings will look like. #. Click the *Save* button to keep your changes. .. index:: pair: Plugins - configurable; File .. _plugin_file: Artefact type: File ^^^^^^^^^^^^^^^^^^^^^^^^ You can configure a variety of options for uploading files: * Default user quota * Default group quota * Upload agreement * Resize images on upload * Profile picture size * Comments * Folder downloads .. index:: pair: File settings; Default user quota Default user quota """""""""""""""""""""""""" .. figure:: /images/administration/plugin_file_defaultuserquota.* :alt: Configure the default user quota Configure the default user quota #. **Default quota**: You can set the amount of disk space that **new users** will have as their quota. Existing user quotas will not be changed. #. **Update user quotas**: Switch this option to "Yes" if you want to update the file quota for **existing users** with the value under **Default quota**. Only then will they be updated. #. **Enforce a site-wide maximum quota**: Switch to "Yes" if you do not wish an administrator to go beyond the allowed maximum quota. #. **Maximum quota**: You can set the maximum quota that an administrator can give to a user. Existing user quotas will not be affected. #. **Quota notification threshold**: :index:`You ` can set a percentage for when a user receives a notification about reaching the upload limit for files. They can then decide to delete files to free up space or contact the site or institution administrator to check if they can receive more space. #. **Site administrator notification**: Switch to "Yes" if the site administrator shall receive the quota notification emails for individual users to take action. #. **Institutional override**: Switch this option to "Yes" if you want to allow institution administrators to set user file quotas and have default quotas for each institution. #. Click the *Save* button at the bottom of the page when you are finished making your changes or continue to the next section on this page. .. index:: pair: File settings; Default group quota Default group quota """""""""""""""""""""""" .. figure:: /images/administration/plugin_file_defaultgroupquota.* :alt: Configure the default group quota Configure the default group quota #. **Default group quota**: You can set the amount of disk space that **each group** will have as its quota. Existing groups will not be affected. #. **Update group quotas**: Switch to "Yes" if you want to update the file quota for **existing groups** with the value under **Default quota**. Only then will they be updated. #. Click the *Save* button at the bottom of the page when you are finished making your changes or continue to the next section on this page. .. index:: pair: File settings; Upload agreement .. _upload_agreement: Upload agreement """""""""""""""""""""" .. figure:: /images/administration/plugin_file_uploadagreement.* :alt: Configure the upload agreement Configure the upload agreement #. **Require agreement**: Switch to "Yes" if you want to force users to agree to certain terms before they can upload a file to the site. They must accept this agreement before they are able to choose a file from their computer to upload to Mahara. #. **Default agreement**: This is the default agreement that will be displayed if you selected the option **Require agreement** and if you don't want to use your own custom agreement. #. **Use custom agreement**: If you want to write your own upload agreement, switch this option to "Yes" in addition to **Require agreement**. #. **Custom agreement**: If you want to use a custom upload agreement, write it here. #. Click the *Save* button at the bottom of the page when you are finished making your changes or continue to the next section on this page. .. index:: pair: File settings; Resize images on upload .. _image_resizing: Resize images on upload """"""""""""""""""""""""""""" .. figure:: /images/administration/plugin_file_resizeimages.* :alt: Configure the image resizing options Configure the image resizing options #. **Resize large images automatically**: Switch this option to "Yes" to resize any image that is uploaded to the maximum width and height settings. #. **User option**: Switch to "Yes" if you wan to display users the option to resize images automatically in their :ref:`account settings `. #. **Maximum width**: Choose the maximum width (in pixels) to which images will be resized upon uploading. #. **Maximum height**: Choose the maximum height (in pixels) to which images will be resized upon uploading. #. Click the *Save* button at the bottom of the page when you are finished making your changes or continue to the next section on this page. .. index:: pair: File settings; Profile picture size Profile picture size """"""""""""""""""""""""""""""" .. figure:: /images/administration/plugin_file_profilepicturesize.* :alt: Configure the size of the profile pictures Configure the size of the profile pictures #. **Width**: Choose the maximum width (in pixels) of the profile pictures for users. #. **Height**: Choose the maximum height (in pixels) of the profile pictures for users. #. Click the *Save* button at the bottom of the page when you are finished making your changes or continue to the next section on this page. .. note:: All images uploaded to the profile pictures area will be resized to these dimensions if they are larger. .. index:: pair: File settings; Comments .. _comments_ratings: Comments """"""""""""""" .. figure:: /images/administration/plugin_file_comments.* :alt: Configure the default comment settings for different file types Configure the default comment settings for different file types #. Click the *Select All* button to mark all file types. #. Click the *Select none* button to clear your selections of the checkboxes. #. **Default comment permission**: Choose the artefact types which shall have comments enabled per default. Users can override these settings for individual artefacts in the :ref:`files area `. You can enable comments for: * archive, i.e. compressed file * audio file * file * folder * image * profile picture * video file #. Click the *Save* button at the bottom of the page when you are finished making your changes or continue to the next section on this page. .. index:: pair: File settings; Folder downloads Folder downloads """""""""""""""""""""""""" .. figure:: /images/administration/plugin_file_folderdownloads.* :alt: Configure the folder download settings Configure the folder download settings #. **Length of time to keep zip files**: Choose the amount of time for how long you want to keep the zip files on the server that are created during the folder download process. The default time frame is 3,600 seconds (1 hour). #. Click the *Save* button when you are finished making your changes. .. index:: pair: Plugins - configurable; Profile .. _plugin_profile: Artefact type: Profile ^^^^^^^^^^^^^^^^^^^^^^^^^^^ For profile information you can decide which fields a user must provide when a user account is created manually or via CSV file. These fields are marked **mandatory fields**. The profile fields marked **searchable fields** are available for all logged-in users to search on. |new in Mahara 17.04| :index:`Decide ` which profile fields you want to display in *Administration → Users → User search*. .. seealso:: |new in Mahara 17.04| :index:`You ` can add custom profile fields more easily via an `addition to a local file `_ in the Mahara code base. .. figure:: /images/administration/plugin_profile.* :alt: Choose mandatory and searchable profile fields Choose mandatory and searchable profile fields #. **Mandatory fields**: Select the fields that you wish all users to fill in. Certain fields cannot be deselected. #. **Searchable fields**: Select the fields that can be searched on by others. Certain fields cannot be deselected. #. |new in Mahara 17.04| **Administration user search**: Select the fields that you want to display in the *User search* table. The fields you select here are not exported to the CSV file though. .. note:: Use the *Select all* and *Select none* buttons to select all profile fields at once or to clear your selection respectively. #. Click the *Save* button to accept your changes. .. index:: pair: Plugins - configurable; Persona pair: Plugins - configurable; BrowserID single: Migrate Persona accounts .. _plugin_persona: Authentication: BrowserID / Persona ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Persona authentication is `discontinued `_ as at 30 November 2016. Nobody is able to use that authentication anymore. When you upgrade to Mahara 17.04 from a version prior to Mahara 16.10, Persona authentication will be deactivated, and you cannot re-activate it anymore. You can automatically migrate all accounts that use Persona to internal authentication. .. figure:: /images/administration/plugin_persona.* :alt: Migrate Persona accounts to internal authentication Migrate Persona accounts to internal authentication #. **Institution**: The institutions that use Persona authentication are listed. #. **Number of active Persona users**: A list of all users that have Persona. The link takes you to the :ref:`user search page ` and displays only the users with Persona. #. **Auto-migrate Persona users**: Switch to "Yes" if you want to migrate all users to internal authentication that have been using Persona authentication. If you don't do that, they will not be able to log in. .. note:: If an institution does not have an internal authentication set, one will be created so that the users can be moved. You will need to inform the users that used Persona as their login to reset their password as no email is sent with the account details. They should go to the :ref:`"Lost username / password" screen ` and enter the email address of their Persona account in order to retrieve their username and password. #. Click the *Save* button to migrate the users. .. index:: pair: Plugins - configurable; SAML .. _plugin_saml: Authentication: SAML ^^^^^^^^^^^^^^^^^^^^^^^^ If you wish to use :ref:`SAML authentication ` anywhere on your site, you can find all necessary information on your site's metadata and certificate here. .. note:: SimpleSAMLphp is a managed dependency that is included in Mahara, which makes the installation of SAML-based authentication methods easier. You may need to install a few more dependencies manually. Please follow the on-screen instructions if that were the case. .. figure:: /images/administration/plugin_saml.* :alt: Prepare your site for SAML authentication Prepare your site for SAML authentication #. **Service Provider entityId**: This is the unique ID that identifies your Mahara instance to the Identity Provider, e.g. example.org/mahara. It is filled in automatically with the wwwroot of your instance. If it is incorrect, you can change it here. #. **Metadata**: The metadata link takes you to the page with your SAML metadata that you would need to give to the Identity Provider. #. **Public key**: The public key is generated and rotated automatically. #. Click the *Save* button to keep your changes. .. index:: pair: Plugins - configurable; Fulltext search single: Fulltext search .. _plugin_fulltext_search: Search: Elasticsearch ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The regular Mahara search is limited to finding users and in certain places titles, descriptions and tags of pages or collections. However, Mahara can be extended to use allow for fulltext search capabilities. The Mahara core project team chose to use `Elasticsearch `_. This is a powerful and extensible fulltext search engine. It does require a Java server, e.g. Tomcat, to run and thus may not be available for small instances of Mahara. .. note:: Currently, the plugin can only be used for Mahara instances running on a PostgreSQL database. Work is in progress to extend the support for MySQL for Mahara 1.9. .. figure:: /images/administration/plugin_elasticsearch.* :alt: Configure the Elasticsearch plugin Configure the Elasticsearch plugin #. Most of the Elasticsearch configuration needs to be done on the server level. Here you only see the settings, but cannot change them directly. #. **Cron record limit**: Decide on the maximum number of records to be passed from the queue to the Elasticsearch server on each cron run. An empty field or ``0`` means that there is no limit. #. **Artefact types**: Check the artefact types that you want to include in the search index. Only artefact types that have a hierarchy defined below are valid. You will need to reset artefacts in the queue below for your changes to take effect. #. **Artefact types hierarchy**: Enter the hierarchy for each artefact type separated by ``|`` (a pipe). Place each artefact type on a row by itself. #. **Index reset**: View the number of records of each type currently in the queue to be sent to the Elasticsearch server. Items are sent to the Elasticsearch server each time the search plugin's cron task runs (every 5 minutes). #. Click the *Reset* button to clear the search index and thus deleting all records and requeuing them. #. Click the *Save* button to accept your changes. .. seealso:: You can find more information about `Elasticsearch in Mahara on the wiki `_. There are also some `developer notes `_ to get you started. .. index:: pair: Plugins - configurable; Internal search single: Exact user search .. _plugin_search: Search: Internal search ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If your site has a lot of users and uses a PostgreSQL database, user searches will be faster with exact user searching enabled. The setting will still work with MySQL databases, but it is unlikely that it increases search performance significantly. The advantage of the exact user search is that if you have 20 users with the first name "Percy" but different last names, you may find the user you are looking for more quickly because you can search for "Percy Pearle" and the result list will not show "Percy Pearl", "Percy Sutter", "Percy Townsend" etc. However, partial matches on profile fields will not return results, so if for example you have a user called "Percy", then typing "Perc" into the search box will not find that user anymore. .. figure:: /images/administration/plugin_search.* :alt: Configure the internal search plugin Configure the internal search plugin #. **Exact user searches**: Switch this option to "Yes" if you want to enable exact user searches. #. Click the *Save* button to keep your changes. .. index:: pair: Plugins - configurable; Forum .. _plugin_forum: Interaction: Forum ^^^^^^^^^^^^^^^^^^^^^^^^ The post delay setting determines the time (in minutes) that users have for editing their forum posts before they are mailed out. Once a forum post has been mailed and further edits are made, the date, time and editor are mentioned in the post. .. figure:: /images/administration/plugin_forum.* :alt: Set the edit time before the forum post is finalised Set the edit time before the forum post is finalised #. **Post delay**: Set the time in minutes before a post is finalised and further edits are marked as such. #. Click the *Save* button to keep your changes. .. index:: pair: Plugins - configurable; LTI single: New in Mahara 17.04; LTI plugin .. _lti_activation: |new in Mahara 17.04| Module: LTI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can activate the LTI API in order to use the :ref:`LTI integration `. .. figure:: /images/administration/plugin_lti.* :alt: Configure the LTI plugin Configure the LTI plugin #. The message lets you know whether the LTI functionality is enabled or not. #. **Configuration item**: List of the configuration items for LTI. #. **Status**: Displays which configuration items are ready to be used and which ones are not. #. **Auto-configure LTI**: Switch to *Yes* if you want all settings to be made automatically. .. note:: Once the auto-configuration was successful, you do not see this option anymore. You can bring it back by making a change in the *Web services* section manually. #. Click the *Save* button to save your changes. .. index:: pair: Plugins - configurable; Mobile API .. _mobile_api: Module: Mobile API ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can activate the mobile API in order to use :ref:`"Mahara Mobile" `, the new Mahara app. .. figure:: /images/administration/plugin_mobile_api.* :alt: Configure the mobile API Configure the mobile API #. The message lets you know whether the mobile apps API is enabled or not. #. **Configuration item**: List of the configuration items for the mobile apps API. #. **Status**: Displays which configuration items are ready to be used and which ones are not. #. **Auto-configure mobile apps API?** Switch to *Yes* if you want all settings to be made automatically. .. note:: Once the auto-configuration was successful, you do not see this option anymore. You can bring it back by making a change in the *Web services* section manually. #. **Manual token generation**: Switch to *Yes* if you want to allow your users to create the initial app token manually. This is only needed if the authentication method does not support the token generation. This is the case with MNet for example. #. Click the *Save* button to save your changes. .. index:: pair: Extensions; HTML filters single: Site administrator; HTML filters .. _html_filters: HTML filters ~~~~~~~~~~~~~~~~~~~ *Administration → Extensions → HTML filters* Mahara uses `HTML Purifier `_ to filter out malicious code that could threaten the security of the system. If you have code, e.g. iFrames or JavaScript that you wish to use and that otherwise gets filtered out, you will have to write a filter to circumvent that. Filters should always be specific to their purpose and not give 'carte blanche' to ensure security as much as possible. Mahara already comes with a number of installed filters. Others can be uploaded and then installed. If you have created a new set of HTML filters, you can install them by unzipping the files into the folder ``/htdocs/lib/htmlpurifiercustom`` and then click the *Install* button. Custom filters for iFrames that allow the embedding of media content such as YouTube and WikiEducator allow users to grab the URL of the page on which the media is displayed instead of having to find the actual embed code. .. note:: You do not necessarily require bespoke filters for media that you wish to embed via