{"id":19640630,"url":"https://github.com/daniel-km/omeka-s-module-shortcode","last_synced_at":"2026-05-15T06:10:02.012Z","repository":{"id":148008338,"uuid":"399432690","full_name":"Daniel-KM/Omeka-S-module-Shortcode","owner":"Daniel-KM","description":"Module for Omeka S that allows to insert shortcuts in site pages in order to render more content via a simple string like `[shortcode]`.","archived":false,"fork":false,"pushed_at":"2024-12-09T07:37:41.000Z","size":162,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-09T18:57:56.434Z","etag":null,"topics":["editorial","omeka-s","omeka-s-module"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Daniel-KM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-24T11:02:01.000Z","updated_at":"2024-12-09T07:37:28.000Z","dependencies_parsed_at":"2025-01-10T10:53:54.981Z","dependency_job_id":null,"html_url":"https://github.com/Daniel-KM/Omeka-S-module-Shortcode","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Daniel-KM%2FOmeka-S-module-Shortcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Daniel-KM%2FOmeka-S-module-Shortcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Daniel-KM%2FOmeka-S-module-Shortcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Daniel-KM%2FOmeka-S-module-Shortcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Daniel-KM","download_url":"https://codeload.github.com/Daniel-KM/Omeka-S-module-Shortcode/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240947648,"owners_count":19883030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["editorial","omeka-s","omeka-s-module"],"created_at":"2024-11-11T14:06:18.981Z","updated_at":"2026-05-15T06:10:02.004Z","avatar_url":"https://github.com/Daniel-KM.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Shortcode (module for Omeka S)\n==============================\n\n\u003e __New versions of this module and support for Omeka S version 3.0 and above\n\u003e are available on [GitLab], which seems to respect users and privacy better\n\u003e than the previous repository.__\n\n[Shortcode] is a module for [Omeka S] that allows to insert shortcuts in site\npages in order to display more content via a simple string.\n\nThe shortcodes are well known in Wikipedia (named [wikitext]), [WordPress], [Omeka Classic],\nand many other cms. The format that is used is the one of WordPress and Omeka Classic,\nlike `[shortcode key=value]`. For example, `[media id=51 player=mirador]`\nwill render the media #51 in the html code with [Mirador]. Or `[items num=3 is_featured=true sort=random]`\nwill display a list of three featured items. A simple link can be `[link 51]` or\n`[link 52 file=original]`. The last update of a site page can be `[page meta=modified]`.\n\nShortcodes can be used nearly anywhere in site pages, even in titles. So it is\npossible to set a title with a dynamic data: `[count resource=items query=\"fulltext_search=xxx\"]`\nwill display the total of items according to the query.\n\nFurthermore, all core shortcodes of Omeka Classic are integrated and other ones\nare gradually implemented in order to make migration easier.\n\nOf course, other modules can add new shortcodes: just add it as a config key\nunder `[shortcodes]`.\n\n\nInstallation\n------------\n\nSee general end user documentation for [installing a module].\n\nThis module requires the module [Common], that should be installed first.\nSome arguments of some shortcodes require the module [Advanced Search].\n\n* From the zip\n\nDownload the last release [Shortcode.zip] from the list of releases, and\nuncompress it in the `modules` directory.\n\n* From the source and for development\n\nIf the module was installed from the source, rename the name of the folder of\nthe module to `Shortcode`.\n\nThen install it like any other Omeka module and follow the config instructions.\n\n\nQuick start\n-----------\n\nA shortcode is a string to add in a textarea field a site page block. It looks\nlike `[shortcode key=value]`. There can be multiple features and values can\nbe protected with quotes or double quotes when they contain spaces: `[shortcode key1=\"my value\" key2='my \"value\"']`.\nWhen the shortcode is not identified, it is displayed as it.\n\nShortcodes work exactly like in Omeka Classic, with the same shortcuts, so you\ncan consult the [Omeka Classic] user manual. Nevertheless, some shortcuts are\nmarked deprecated and it is recommended to use the more semantic equivalent ones\nfor Omeka S.\n\nFor example, to render the media #51 with the default renderer, you can use:\n`[media id=51 player=default]`. This is the equivalent of `[file id=51]` that\nwas used in Omeka Classic, and that is now a simple alias.\n\n\nShortcodes\n----------\n\n### Available shortcodes\n\n#### No operation\n\nThe shortcode `[noop]` is skipped automatically, whatever its arguments.\n\n#### Count\n\nThe shortcode `[count]` allows to get the total of resources. It requires a\nresource type : `[count resource=items]`.\n\nThe count can be limited by argument `query` or any other generic params: `id`,\n`is_featured`, `has_image`, `has_media`, `owner`, `item_set`, `collection`,\n`class`, `class_label`, `template`, `template_label`, `tag`.\n\nWhen the generic params are present, they override the matching api argument set\nin the query: `[count resource=items query=\"resource_class_id=32\" class=dctype:PhysicalObject]`.\nNote: the shortcodes arguments are a simplified variant of the keys used in the\napi.\n\nAs most of shortcodes, the argument `span=xxx` allows to wrap the result with a\n`span` with the specified value as class.\n\n#### Single resource\n\nThe following shortcodes can be use to display a single resource:\n\n- `resource`\n- `item`\n- `media`\n- `item_set`\n- `collection` (alias of `item_set`)\n- `asset`\n- `page`\n- `site`\n- `annotation` (with module [Annotate])\n\nIt displays a single resource. The internal id is required to get it. Example: `[item id=51]`.\nThe name of the argument `id` can be omitted: `[item 51]`. The numeric id should\nbe the first argument without key. Other arguments are sent to the partial. For\npage and site, the `id` is the internal id or the slug. For pages, the argument\n`site` should be used to specify the site, else the current site is used.\n\nThe template is the name of the resource by default.\n\n##### As block\n\nBy default, a single resource is displayed as a block, similar to the site page\nshowcase.\n\n##### As link\n\nUse the view template `link` to display the resource as a link: `[item 51 view=link]`.\nYou can use the shortcode for it `[link 51]` in that case too (see below).\n\nNote that for media, this is the link to the resource page, not to the file. Use\nargument `file=original` or `file=large`, etc. to get it (see below).\n\n##### As url\n\nIf you just need the url, use the view template `url` to display the resource as\na simple url: `[item id=51 view=url]`, or simply `[item 51 url]`.\n\n##### As a metadata\n\nTo display the metadata of a resource, use the key `meta`: `[item 51 meta=o:modified]`.\nThe field names are the ones used in the json-ld representation, included any\nproperty term, for example `[item 51 meta=dcterms:relation]`.\n\nWhen multiple values are available, only the first one is displayed.\n\nThe standard Omeka metadata starting with `o:` can be shortened, so to get the\ncreation date of the current page, the shortcode can be `[page meta=created date=long]`.\n\nFor dates (created or modified), the args `date` and `time` can be added, with\npossible values `none` (default for time), `short`, `medium` (default for date),\n`long`, and `full`.\n\n##### Through a player\n\nThe param `player` allows to render the resource through a player, for example\n`[item id=51 player=Mirador]`. The player should be installed via a module, for\nexample [LightGallery], [Mirador], [UniversalViewer], [Diva], [ViewerJs], [Verovio],\nor anything else as long as the matching view helper exists and can be called\nwith `__invoke(AbstractResourceEntityRepresentation $resource, array $options = [])`.\nWarning: the case of the value should be checked when needed (the first letter\nis automatically lower-cased).\n\nWhen the player doesn't exist, the resource is rendered as a block, except for\nmedia, that is rendered with its own default renderer. The value can be `default`\nin that case too: `[media id=52 player=default]`.\n\nThe player `image` allows to display the thumbnail of the resource. The\nshortcode `[image]` is a shortcode to it: `[image 51]` is like `[item 51 player=image]`.\n\nSpecific options are sent to the partial and to the renderer and to the player.\n\nFor media, there are specific options for the default renderer:\n  - `thumbnail`, the thumbnail type, that can be `large`, `medium` (default) or\n    `square`,\n  - `align`, to align the thumbnail on `left` (default), `right` or `center`,\n  - `show_title`, to specify the type of the title: `item_title` or `file_mane`.\n\n- Deprecated shortcode name for compatibility with Omeka classic:\n  - `file`\n    Shortcut to `[media player=default]`.\n\n#### Resource link or url\n\nThe shortcode `link` can be used to display a link to the resource page: `[link 51]`.\n\nTo set the title, use argument `title`, else it will use the default title of\nthe resource: `[link 51 title=\"Title of the resource\"]`. To use the url as title,\nskip the title: use `[link 51 title=]`.\n\nTo get only the url, use the view `url`: `[link 51 view=url]`, or simply `[link 51 url]`.\nNote that it is no more a link: use `[link 51 title=]` to get the link.\n\nThe argument `span` allow to wrap the link or url with a specific class.\n\n_Warning_: This is the link to the resource page, even for media. To get the\nlink or url to the media file, use `[link 51 file=original]`, where file can be\nany of the thumbnail types.\n\n#### List of resources\n\nThe following shortcodes can be use to list resources:\n\n- `items`\n- `medias` (with a `s` for multiple medias)\n- `item_sets`\n- `collections` (alias of `item_sets`)\n- `pages`\n- `sites`\n- `annotations` (with module [Annotate])\n\n  To limit resources, use the same arguments than the shortcode `count`.\n  The resources are listed according to `num`, `sort`, and `order` if any.\n\n  Assets cannot be listed for now.\n\n- Deprecated shortcode names for compatibility with Omeka classic:\n  - `recent_items`\n    Shortcut to `[items num=5 sort=created order=desc]`.\n  - `featured_items`\n    Shortcut to `[items num=1 is_featured=true sort=random]`.\n  - `recent_collections`\n    Shortcut to `[items num=5 sort=created order=desc]`.\n  - `featured_collections`\n    Shortcut to `[items num=1 is_featured=true sort=random]`.\n\n### Generic arguments\n\nSome generic arguments are used in many shortcodes, so they are gathered here.\n\n(If the table is not readable, go to the original page of the module [Shortcode]).\n\n| Argument name     | Purpose                                                               | Argument value                    | Example                                                           |\n| ----------------- | --------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------- |\n| `id`              | Get a list of resources by id.                                        | List or range of integers         | `[items id=15,30,51]`, `[items id=15-51]`                         |\n| `ids`             | Deprecated alias of `id`                                              | List or range of integers         | See `id`                                                          |\n| `site`            | Get only resources from the specified site                            | Integer                           | `[items site=2]`                                                  |\n| `owner`           | Get only resources owned by a specific user                           | Integer                           | `[items owner=2]`                                                 |\n| `user`            | Deprecated alias of `owner`                                           | Integer                           | See `owner`                                                       |\n| `item_set`        | Get only resources from an item set                                   | List or range of integers         | `[items item_set=7]`                                              |\n| `collection`      | Alias of `item_set`                                                   | List or range of integers         | `[items collection=7]`                                            |\n| `class`         * | Get only resources from one or multiple classes                       | List of terms or ids              | `[items class=dctype:StillImage,26]`                              |\n| `class_label`     | Get only resources from a class via its label                         | String                            | `[items class_label=\"Physical Object\"]`                           |\n| `item_type`       | Deprecated alias of `class_label`)                                    | String                            | See `class_label`                                                 |\n| `template`        | Get only resources from one or multiple templates                     | List or range of integers         | `[items template=1,2`]                                            |\n| `template_label`  | Get only resources from a template via its label                      | String                            | `[items template_label=\"Base Resource\"]`                          |\n| `tag`           * | Get only resources with the specified tag (`curation:tag`)            | List of strings                   | `[items tag=\"alpha, beta, gamma\"]`                                |\n| `tags`          * | Deprecated alias of `tag`                                             | List of strings                   | See `tag`                                                         |\n| `is_featured`     | Get only resources with a value `curation:featured`.                  | Boolean                           | `[collections is_featured=1]`                                     |\n| `has_image`     * | Resource with an image (a thumbnail), or not.                         | Boolean                           | `[featured_items has_image=false]`                                |\n| `has_media`     * | Resource with a media, or not.                                        | Boolean                           | `[items has_media=true]`                                          |\n| `query`           | Specify a query to limit resources                                    | String (advanced search url)      | `[items query=\"search=xxx\"]`                                      |\n| `num`             | Number of resources returned. \"0\" means unlimited. Default: 10.       | Integer                           | `[featured_items num=4]`                                          |\n| `sort`            | Property term or specific api value to sort the resource by.          | Property term or json-ld keys     | `[items sort=dcterms:date]`, `[items sort=created]`               |\n| `order`           | Order of the sorting                                                  | `a`, `d`, `asc`, or `desc`        | `[items sort=dcterms:title order=asc]`                            |\n| `meta`            | Get the specified metadata                                            | Property term or json-ld keys     | `[item 51 meta=dcterms:creator]`, `[item 51 meta=title]`          |\n| `span`            | Wrap the output with a span and optionally a class                    | String|Null                       | `[item 51 span=author]`                                           |\n| `view`            | Specify a special theme template for specific rendering               | String                            | `[items view=items]`                                              |\n\nThe arguments marked with a `*` require the module [Advanced Search].\n\nFor boolean values, a `0` or a `false` are false, anything else is true.\n\nA list of integers is a comma-separated list of number or a range separated by\nan hyphen: `15,30,51`, `15-51`\n\nFor a list of terms, it is recommended to use terms instead of ids, because they\nare more portable. The case must be respected for now: `dcterms:ispartof` or `dctype:stillimage`\ndon't exist, you should use `dcterms:isPartOf` and `dcterms:StillImage`.\n\nThe sort specific strings are the one used by the api, like `created`, `modified`,\n`random`, and the property terms.\n\nThe current site is automatically added. To get results for all sites, use an\nempty string: `[items site=]`\n\nThe partial template set with `view` should be available under `common/shortcode/`.\nFor security, the name must not contain a dot. If the template is missing, the\ndefault one is used. Some shortcodes doesn't use a template by default (`count`,\n`link`) and you can use argument `span` to wrap it with a class if you don't\nneed a full template. The templates `link` and `url` are fake templates.\n\nTake care of copy-pasting: often, span and attributes are inserted automatically.\nYou may need to check the source code of an html text area when an issue occurs.\n\n\nDevelopment\n-----------\n\nAny module can add new shortcode: just add it as a config key under `[shortcodes]`.\n\nThe shortcode can be any class that can be invoked; just add the interface\n`Shortcode\\Shortcode\\ShortcodeInterface` to it, or extends the class from the\nabstract class `Shortcode\\Shortcode\\AbstractShortcode`. If a partial is needed,\nit is recommended to put it in directory common/shortcode.\n\n\nTODO\n----\n\n- [ ] WordPress shortcodes (alias to Omeka ones, for example `[gallery]`)?\n- [ ] Shortcoder any.\n\n\nWarning\n-------\n\nUse it at your own risk.\n\nIt’s always recommended to backup your files and your databases and to check\nyour archives regularly so you can roll back if needed.\n\n\nTroubleshooting\n---------------\n\nSee online issues on the [module issues] page on GitLab.\n\n\nLicense\n-------\n\nThis module is published under the [CeCILL v2.1] license, compatible with\n[GNU/GPL] and approved by [FSF] and [OSI].\n\nThis software is governed by the CeCILL license under French law and abiding by\nthe rules of distribution of free software. You can use, modify and/ or\nredistribute the software under the terms of the CeCILL license as circulated by\nCEA, CNRS and INRIA at the following URL \"http://www.cecill.info\".\n\nAs a counterpart to the access to the source code and rights to copy, modify and\nredistribute granted by the license, users are provided only with a limited\nwarranty and the software’s author, the holder of the economic rights, and the\nsuccessive licensors have only limited liability.\n\nIn this respect, the user’s attention is drawn to the risks associated with\nloading, using, modifying and/or developing or reproducing the software by the\nuser in light of its specific status of free software, that may mean that it is\ncomplicated to manipulate, and that also therefore means that it is reserved for\ndevelopers and experienced professionals having in-depth computer knowledge.\nUsers are therefore encouraged to load and test the software’s suitability as\nregards their requirements in conditions enabling the security of their systems\nand/or data to be ensured and, more generally, to use and operate it in the same\nconditions as regards security.\n\nThe fact that you are presently reading this means that you have had knowledge\nof the CeCILL license and that you accept its terms.\n\n\nCopyright\n---------\n\n* Copyright Roy Rosenzweig Center for History and New Media, 2014\n* Copyright Daniel Berthereau, 2021-2025 (see [Daniel-KM])\n\nThe shortcode parser is an improved version of the one that is used [in WordPress]\nsince 2008 (version 2.5). The same is used [in Omeka Classic] since 2014\n(version 2.2) too, and it can be found in older various places.\n\n\n[Shortcode]: https://gitlab.com/Daniel-KM/Omeka-S-module-Shortcode\n[Omeka S]: https://omeka.org/s\n[wikitext]: https://en.wikipedia.org/wiki/Help:Wikitext#Links_and_URLs\n[WordPress]: https://wordpress.com/support/shortcodes/\n[Omeka Classic]: https://omeka.org/classic/docs/Content/Shortcodes/\n[installing a module]: https://omeka.org/s/docs/user-manual/modules/#installing-modules\n[Advanced Search]: https://gitlab.com/Daniel-KM/Omeka-S-module-AdvancedSearch\n[Common]: https://gitlab.com/Daniel-KM/Omeka-S-module-Common\n[Annotate]: https://gitlab.com/Daniel-KM/Omeka-S-module-Annotate\n[LightGallery]: https://gitlab.com/Daniel-KM/Omeka-S-module-LightGallery\n[Mirador]: https://gitlab.com/Daniel-KM/Omeka-S-module-Mirador\n[UniversalViewer]: https://gitlab.com/Daniel-KM/Omeka-S-module-UniversalViewer\n[Diva]: https://gitlab.com/Daniel-KM/Omeka-S-module-Diva\n[ViewerJs]: https://gitlab.com/Daniel-KM/Omeka-S-module-ViewerJs\n[Verovio]: https://gitlab.com/Daniel-KM/Omeka-S-module-Verovio\n[module issues]: https://gitlab.com/Daniel-KM/Omeka-S-module-Shortcode/issues\n[CeCILL v2.1]: https://www.cecill.info/licences/Licence_CeCILL_V2.1-en.html\n[GNU/GPL]: https://www.gnu.org/licenses/gpl-3.0.html\n[FSF]: https://www.fsf.org\n[OSI]: http://opensource.org\n[in WordPress]: https://developer.wordpress.org/reference/functions/get_shortcode_atts_regex/\n[in Omeka Classic]: https://github.com/omeka/Omeka/blob/master/application/views/helpers/Shortcodes.php#L96-L117\n[GitLab]: https://gitlab.com/Daniel-KM\n[Daniel-KM]: https://gitlab.com/Daniel-KM \"Daniel Berthereau\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-km%2Fomeka-s-module-shortcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaniel-km%2Fomeka-s-module-shortcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaniel-km%2Fomeka-s-module-shortcode/lists"}