Shortcode (module for Omeka S)
New versions of this module and support for Omeka S version 3.0 and above are available on GitLab, which seems to respect users and privacy better than the previous repository.
The shortcodes are well known in Wikipedia (named wikitext), WordPress, Omeka Classic,
and many other cms. The format that is used is the one of WordPress and Omeka Classic,
[shortcode key=value]. For example,
[media id=51 player=mirador]
will render the media #51 in the html code with Mirador. Or
[items num=3 is_featured=true sort=random]
will display a list of three featured items.
Shortcodes can be used nearly anywhere in site pages, even in titles. So it is
possible to set a title with a dynamic data:
[count resource=items query="q=xxx"]
will display the total of items according to the query.
Furthermore, all core shortcodes of Omeka Classic are integrated and other ones are gradually implemented in order to make migration easier.
Of course, other modules can add new shortcodes: just add it as a config key
Uncompress files and rename module folder
Shortcodes. Then install it like any
other Omeka module and follow the config instructions.
See general end user documentation for Installing a module.
Some arguments sof some shortcodes require the module Advanced Search.
A shortcode is a string to add in a textarea field a site page block. It looks
[shortcode key=value]. There can be multiple features and values can
be protected with quotes or double quotes when they contain spaces:
[shortcode key1="my value" key2='my "value"'].
When the shortcode is not identified, it is displayed as it.
Shortcodes work exactly like in Omeka Classic, with the same shortcuts, so you can consult the Omeka Classic user manual. Nevertheless, some shortcuts are marked deprecated and it is recommended to use the more semantic equivalent ones for Omeka S.
For example, to render the media #51 with the default renderer, you can use:
[media id=51 player=default]. This is the equivalent of
[file id=51] that
was used in Omeka Classic, and that is now a simple alias.
[noop] is skipped automatically, whatever its arguments.
[count] allows to get the total of resources. It requires a
resource type :
The count can be limited by argument
query or any other generic params:
When the generic params are present, they override the matching api argument set
in the query:
[count resource=items query="search=xxx" class=dctype:PhysicalObject].
Note: the shortcodes arguments are a simplified variant of the keys used in the
span=xxx allows to wrap the result with a
span with the
specified value as class.
List of resources
sfor multiple medias)
annotations(with module Annotate)
To limit resources, use the same arguments than the shortcode
The resources are listed according to
order if any.
- Deprecated shortcode names for compatibility with Omeka classic:
[items num=5 sort=created order=desc].
[items num=1 is_featured=true sort=random].
[items num=5 sort=created order=desc].
[items num=1 is_featured=true sort=random].
annotation(with module Annotate)
Display a single resource. The argument
id is required to get it. Other
arguments are sent to the partial.
Through a player
player allows to render the resource through a player, for example
[item id=51 player=Mirador]. The player should be installed via a module, for
example LightGallery, Mirador, UniversalViewer, Diva, ViewerJs, Verovio,
or anything else as long as the matching view helper exists and can be called
__invoke(AbstractResourceEntityRepresentation $resource, array $options = ).
Warning: the case of the value should be checked when needed (the first letter
is automatically lower-cased).
When the player doesn't exist, the resource is rendered as a block, except for
media, that is rendered with its own default renderer. The value can be
in that case too:
[media id=52 player=default].
Specific options are sent to the partial and to the renderer and to the player.
For media, there are specific options for the default renderer:
thumbnail, the thumbnail type, that can be
align, to align the thumbnail on
show_title, to specify the type of the title:
- Deprecated shortcode name for compatibility with Omeka classic:
Some generic arguments are used in many shortcodes, so they are gathered here.
| Argument name | Purpose | Argument value | Example |
| ----------------- | ----------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------- |
id | Get a list of resources by id. | List or range of integers |
[items id=15-51] |
ids | Deprecated alias of
id | List or range of integers | See
site | Get only resources from the specified site | Integer |
[items site=2] |
owner | Get only resources owned by a specific user | Integer |
[items owner=2] |
user | Deprecated alias of
owner | Integer | See
item_set | Get only resources from an item set | List or range of integers |
[items item_set=7] |
collection | Alias of
item_set | List or range of integers |
[items collection=7] |
class * | Get only resources from one or multiple classes | List of terms or ids |
[items class=dctype:StillImage,26] |
class_label | Get only resources from a class via its label | String |
[items class_label="Physical Object"] |
item_type | Deprecated alias of
class_label) | String | See
template | Get only resources from one or multiple templates | List or range of integers |
[items template=1,2] |
template_label | Get only resources from a template via its label | String |
[items template_label="Base Resource"] |
tag * | Get only resources with the specified tag (
curation:tag) | List of strings |
[items tag="alpha, beta, gamma"] |
tags * | Deprecated alias of
tag | List of strings | See
is_featured | Get only resources with a value
curation:featured. | Boolean |
[collections is_featured=1] |
has_image * | Resource with an image (a thumbnail), or not. | Boolean |
[featured_items has_image=false] |
has_media * | Resource with a media, or not. | Boolean |
[items has_media=true] |
query | Specify a query to limit resources | String (advanced search url) |
[items query="search=xxx"] |
num | Number of resources returned. "0" means unlimited. Default: 10. | Integer |
[featured_items num=4] |
sort | Property term or specific api value to sort the resource by. | Property term or some strings |
[items sort=created] |
order | Order of the sorting |
[items sort=dcterms:title order=asc] |
templet | Specify a special theme template for some shortcodes | String |
[items templet=items] |
The arguments marked with a
* require the module Advanced Search.
For boolean values, a
0 or a
false are false, anything else is true.
A list of integers is a comma-separated list of number or a range separated by
For a list of terms, it is recommended to use terms instead of ids, because they
are more portable. The case must be respected for now:
don't exist, you should use
The sort specific strings are the one used by the api, like
random, and the property terms.
The current site is automatically added. To get results for all sites, use an
The partial template set with
templet should be available under
For security, the name must not contain a dot. If the template is missing, the
default one is used.
Take care of copy-pasting: often, span and attributes are inserted automatically. You may need to check the source code of an html text area when an issue occurs.
Any module can add new shortcode: just add it as a config key under
The shortcode can be any class that can be invoked; just add the interface
Shortcode\Shortcode\ShortcodeInterface to it, or extends the class from the
Shortcode\Shortcode\AbstractShortcode. If a partial is needed,
it is recommended to put it in directory common/shortcode.
- [ ] WordPress shortcodes (alias to Omeka ones, for example
- [ ] Shortcoder any.
Use it at your own risk.
It’s always recommended to backup your files and your databases and to check your archives regularly so you can roll back if needed.
See online issues on the module issues page on GitLab.
This software is governed by the CeCILL license under French law and abiding by the rules of distribution of free software. You can use, modify and/ or redistribute the software under the terms of the CeCILL license as circulated by CEA, CNRS and INRIA at the following URL "http://www.cecill.info".
As a counterpart to the access to the source code and rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software’s author, the holder of the economic rights, and the successive licensors have only limited liability.
In this respect, the user’s attention is drawn to the risks associated with loading, using, modifying and/or developing or reproducing the software by the user in light of its specific status of free software, that may mean that it is complicated to manipulate, and that also therefore means that it is reserved for developers and experienced professionals having in-depth computer knowledge. Users are therefore encouraged to load and test the software’s suitability as regards their requirements in conditions enabling the security of their systems and/or data to be ensured and, more generally, to use and operate it in the same conditions as regards security.
The fact that you are presently reading this means that you have had knowledge of the CeCILL license and that you accept its terms.
- Copyright Roy Rosenzweig Center for History and New Media, 2014
- Copyright Daniel Berthereau, 2021 (see Daniel-KM)
The shortcode parser is an improved version of the one that is used in WordPress since 2008 (version 2.5). The same is used in Omeka Classic since 2014 (version 2.2) too, and it can be found in older various places.