portfolio/pages: Add "Create via tags" option

New feature in Mahara 18.10: You can populate a page
with tagged content automatically (Bug #1775106).

source/portfolio/pages.rst

@@ -230,17 +230,44 @@ You add a new page in your portfolio when you want to display artefacts together
    Create a portfolio page
 
 #. On the *Pages and collections* page, click the *Add* button. In the modal that comes up, click the *Page* button. You are taken to the *Settings*.
-#. **Page title**: Provide a title for your page. This field cannot be left empty. If you do not enter a title, the default "Untitled" will appear.
+#. **Basics**: This section includes basic page settings:
+
+   * Page title
+   * Page description
+   * Tags
+   * Create via tags
+
 
    .. note::
-      The page title, description, and tags appear in the *Basics* panel. If you cannot see them, click the |retracted| icon to make them visible.
+      If you cannot see these settings options, click the |retracted| icon to make them visible.
 
+#. **Page title**: Provide a title for your page. This field cannot be left empty. If you do not enter a title, the default "Untitled" will appear.
 #. **Page description**: Write a brief description summarising your objective of this page. It will appear on the page itself.
-#. **Tags**: Enter tags to find your page more easily at a later stage. You can choose from your existing tags by starting to type a letter and then selecting the tag you want to use. You can also type a new tag, and it is added to your list of tags.
+#. **Tags**: Enter tags to find your page more easily at a later stage. You can choose from your existing tags by starting to type a letter and then selecting the tag you want to use. You can also type a new tag, select it, and it is added to your list of tags.
 
    .. seealso::
       You can find more information on how to use the tag selector in the :ref:`"Tags" section <tag_add>`.
 
+#. |new in Mahara 18.10| **Create via tags**: :index:`You <single: New in Mahara 18.10; Populate a page with tagged content>` can select one or more tags to populate the page with all artefacts and blocks that have been tagged with them. If you select more than one tag, you only see content that matches all selected tags, i.e. it must match tag one and tag two.
+
+   .. note::
+      The page is only populated with already existing tagged content. If you tag new artefacts, they will not be added automatically. You will have to add them manually or populate the page again. Only new artefacts will be added.
+
+      Once you have added artefacts automatically, you can re-arrange and also remove them as needed. Since there are several possibilities of adding artefacts and blocks to a page, the following content mappings are made when multiple artefacts of the same type are added:
+
+      * 1 image: Image block
+      * 2+ images: Image gallery
+      * 1 PDF: PDF block
+      * 2+ PDFs: Files to download block
+      * 1 audio / video: Internal media block (as long as the format is supported)
+      * 2+ audio / video: Files to download block
+      * Generic file(s): Files to download block
+      * Folder(s): 1 Folder block per folder
+      * Journal(s): 1 Journal block per journal
+      * Journal entry / entries: Tagged journal entries block
+      * Note(s): 1 Note block per note
+      * Plan / tasks: The entire plan that contains the tagged content
+      
 #. **Name display format**: Choose how you want your name to appear on the page to others.
 #. **Anonymise**: If the site administrator allowed :ref:`anonymous pages <anonymous_pages>`, you can choose this option here. Instead of your (display) name, "Author's name hidden" will be displayed to everyone. Administrators and staff can still see your real name.
 #. **Layout**: Click the |retracted| icon to display all layout options. You can :ref:`change the layout <edit_layout>` to decide the overall distributon of your blocks on the page.