Docs:Filter Metadata

The filters element

The filters element can be added to the metadata for any theme, module, or step that needs to be included or excluded depending on the filtering option passed to the processor by the user. If a theme, module, or step has no filters element, or an empty filters element, then it will always be included in the course regardless of the filters specified by the user on the command line.

Attributes

None. This element is a container only.

Example

<filters>
    <include>socs</include>
</filters>

The include element

The include element is a filter selector that can only appear within a filters element. The include element acts as a marker that says "Only include this resource in the course if one or more of the specified include filter keywords matches one or more of the keywords in the list passed to the processor, otherwise do not include this resource in the course". When a resource has a filters element that contains one or more include elements, the resource will only be included in the course when at least one of the filter keywords in the includes appears in the list of keywords provided via the processor's --filter argument. This is the only situation in which a resource with one or more include elements in its filters element will be generated: if the processor is run without a --filter argument, or with a --filter argument whose list of filter keywords does not include one of the keywords set in the resource's includes, the resource will not be included. For example, a resource that has the following filters element will only be generated when the filter list provided to the processor includes 'socs', otherwise it will not be included:

Attributes

None. This element is a container only.

Example

In this example, the resource will only be added to the generated course if the list of filter keywords passed to the processor includes the keyword "socs".

<filters>
    <include>socs</include>
</filters>

The exclude element

The exclude element is a filter selector that can appear inside a filters element. The exclude element acts as a marker that says "If a resource can be included (subject to any restrictions imposed by any include elements) always include it, unless the filter keyword matches any of the keywords in the list passed to the processor". When a resource has a filters element that contains one or more exclude elements, the resource will always be included in the course unless:

1. The filters element for the resource contains one or more include elements, and none of the filter keywords specified in the resource's include elements appear in the list of keywords the processor was given on the command line.
2. One or more of the filter keywords specified in the exclude elements are present in the list of filter keywords the processor was given on the command line.

Attributes

None. This element is a container only.

Example

In this example, a resource with the following filters element will always be included in the generated course, unless the filter list provided to the processor includes 'socs', in which case it will not be included:

<filters>
    <exclude>socs</exclude>
</filters>

This is a more complicated example, where the resource will only be included in the generated course if the filter list provided to the processor includes 'socs', and it does not also include 'demo':

<filters>
    <include>socs</include>
    <exclude>demo</exclude>
</filters>