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.
Block Plus is a module for Omeka S that adds page models and new blocks for the editorial pages and improves some of the existing ones: image gallery, D3 graph, mirror page, search form, item set showcase, exhibits, footnotes, etc. Some resource page blocks are implemented too: breadcrumbs, previous/next resource, section, etc.
Another feature is the possibility to pre-configure page models and list of blocks, so it is easier to build a new page. The page models and blocks groups can be defined via a simple click from an existing page.
Warning: Since Omeka S v4.1, many of the features implemented some years ago were re-implemented in core. The migration from old blocks of the module before version 3.4.22 to new blocks may require some manual updates of the themes when they were customized. See below for migration. There is no issue for a new install.
See general end user documentation for installing a module.
This module requires the module Common, that should be installed first.
The module uses external js libraries for some blocks, so use the release zip to install it, or use and init the source.
Download the last release BlockPlus.zip from the list of releases (the master
does not contain the dependency), and uncompress it in the modules
directory.
If the module was installed from the source, rename the name of the folder of
the module to BlockPlus
, and go to the root module, and run:
composer install --no-dev
Then install it like any other Omeka module and follow the config instructions.
When creating a new page, a option allows to select a page model or a blocks group. When editing an existing page, the button "Add block group plus" allows to load the same list of pre-configured blocks groups, avoiding to recreate it on multiple pages.
This pre-configured list of page models and group of blocks can be configured in many places. Four page models, one for each of the page templates of the module, and one group of blocks are available by default. The page models are similar to the ones of Omeka Classic (Omeka 2) to simplify migration.
The block "blockGroup" is not required and the group can be a simple list of blocks, so you can configure the blocks of all a page type. If you use the block Group, you may specify the data span for the number of the following blocks nested inside it. If not set, all blocks until the next block Group will be nested.
A page model or a group of blocks is just a pre-configured list of blocks of settings, similar to the api representation of a site page, that are available in https://example.org/api/site_pages. You can change settings once appended to the page.
A page model or a blocks group can be defined via a simple click in the page "Edit page". So the current page or the current list of blocks with all of their settings will be stored as main setting, site settings or theme settings (if the theme supports it).
Such page models and groups of blocks can be configured in any module, in the file config/local.config.php of the installation, in the main settings, in the site settings, in the file config/theme.ini of the current theme or in the theme settings.
A configured element is a page model when the key "o:layout_data" or "layout_data" is set with an array, even empty. If the key is not present, the element is a blocks groups. Page models are not displayed in the list of blocks groups in the "Edit page".
To set the list of page models or groups of blocks in a file (module.config.php, local.config.php), follow the example in the file module.config.php of this module.
To set the list of page models or groups of blocks in a field in a settings page (main settings, site settings, theme settings), use the format "ini".
[asset_text]
o:label = "Asset with text"
o:caption = "Blocks group with a heading, an asset, a field for html and a line break with some styles"
o:block.1.o:layout = "blockGroup"
o:block.1.o:layout_data.class = "block-asset-text"
o:block.2.o:layout = "heading"
o:block.2.o:data.text = "Image"
o:block.2.o:data.level = 3
o:block.3.o:layout = "asset"
o:block.4.o:layout = "html"
o:block.4.o:data.html = "<p>This <strong>image</strong> represents…</p>"
o:block.5.o:layout= "lineBreak"
o:block.5.o:data.break_type = "opaque"
o:block.5.o:layout_data.background_color = "#404e61"
o:block.5.o:layout_data.min_height = "18px"
Set the name as section, a label as o:label
, a description as o:caption
, a
list of blocks with o:block
and keys o:layout
, o:data
and o:layout_data
.
If you want to create a page model, add a key o:layout_data
with an array as
value. Key o:data
does not exist for page model. All values are optional,
except the layout name for each block (key o:layout
).
For simplicity, you can skip the prefix o:
for keys o:label
, o:caption
,
o:block
, o:layout
, o:data
, and o:layout_data
, so you can use label
,
caption
, block
, layout
, data
, and layout_data
, for example the
following config is the same than above:
[asset_text]
label = "Asset with text"
caption = "Blocks group with a heading, an asset, a field for html and a line break with some styles"
block.1.layout = "blockGroup"
block.1.layout_data.class = "block-asset-text"
block.2.layout = "heading"
block.2.data.text = "Image"
block.2.data.level = 3
block.3.layout = "asset"
block.4.layout = "html"
block.4.data.html = "<p>This <strong>image</strong> represents…</p>"
block.5.layout= "lineBreak"
block.5.data.break_type = "opaque"
block.5.layout_data.background_color = "#404e61"
block.5.layout_data.min_height = "18px"
If you want to add a group in the theme via the file config/theme.ini, you
cannot use the section marker for [layout_name]
and you should prepend the
main key page_models
, then the name of the page model or blocks group, for
example:
page_models.asset_html.label = "Asset with html"
page_models.asset_html.block.1.layout = "asset"
page_models.asset_html.block.2.layout = "html"
Of course, if there is a setting "block_page_models" in the theme config, it will be managed like main and site settings in the user interface.
When two elements have the same name (root key), the more specific replaces the more generic, so config < settings < site settings < theme config < theme settings.
Available templates:
These templates support the "class and url from caption" feature: if you need a specific class or url for the theme and not only a page, you can prepend them to each asset caption:
url = https://example.org/
class = xxx yyy
Next lines are the true caption.
Furthermore, the caption may be an html one.
A simple block to display a template from the theme. It should be adapted by in the theme. It may be used for a static html content, like a list of partners, or a complex layout, since any Omeka feature is available in a view.
Two block templates are provided:
An example layout is provided to display a dynamic tree view from a tsv/csv file. The file should be one value by a row, with the offset matching the depth:
Asia
Japan
Tokyo
Europe
France
Paris
Italy
Roma
Florence
For more complex hierarchy, it is recommended to use modules Reference or Thesaurus.
A second example is a template to create a standard glossary (definition list):
alpha = First letter of Greek alphabet
beta = Second letter of Greek alphabet
The glossary can be created with html too with the block html
and template html-glossary
.
In that case, set a list of term and definition separated by an empty line:
alpha
definition of alpha
beta
definition of beta
definition of beta continued…
To insert a line, it is recommended to set the cursor at the start of the line. It will avoid possible issues.
This block displays the breadcrumbs of the current page according to site settings.
Some specific templates are available in Browse Preview:
thumbnail_size=medium
. You can see an example on the site Ontologie du christianisme médiéval en images,
from French Institut national de l’histoire de l’art.To use them, simply select the wanted template:
This block displays buttons to share the current page in a privacy-compliant way. Available buttons are Download, Email, Facebook, Pinterest and Twitter.
The D3 graph adds the D3 library to display relations between items in a graph: links between subjects and objects, links between items and item sets, etc. An example of use can be seen on the digital library of the Fondation de la Maison de Salins.
Similar to media or asset, but to display an external asset that is not a resource neither an asset file, so currently not manageable inside Omeka. With a block of html in a group of blocks, it may be used to display a html text with a video on the home page.
Display a html heading <h1></h1>
to <h6></h6>
in order to organize your
blocks.
Two templates allow to wrap next blocks inside a html structure details/summary.
Two new options are added in main settings:
Furthermore, it is possible to add footnotes inside each html field.
For the templates:
This is similar to the block Media, but for item sets. This block will be merged in block Showcase in a future version.
Allow to display a list of links. In the text area, write each link as:
url = Title = Optional short description
/s/main/page/beta = Beta = Short description
This block improves the core one in order to skip current site and translated sites.
This feature may be integrated in the core.
Display the messages (notice, warning and errors), like in admin. This block may be useful for modules like Contact Us, Contribute, Guest, Bulk export, etc. that add some interactions with the visitor.
Allow to use a page as a block, so the same page can be use in multiple sites, for example the page "About" or "Privacy". Of course, the page is a standard page and can be more complex with multiple blocks. May be fun. This is an equivalent for the shortcode as a page in Omeka Classic too.
Allow to specify some metadata to the page for theme creators.
Allow to redirect the page to another page, inside or outside Omeka. It is useful for hard coded links in the footer, to keep track of some clicks, to use the page item/browse as a the home page, or some other use cases.
Include a specific search form in a specific page. The default query may be adapted to the page via the theme.
Create a full search page with a simple or complex form and the results on the
same page. All options should be managed via the theme. To replace item/browse,
item-set/browse and even media/browse, you may need to set the page as default
action for the search in default template common/search-form
.
Generic complete block to display any selected resources, site, page, asset or url.
The table can be displayed from the root if wanted.
This feature may be integrated in the core.
Display a tree structure from selected resources. The structure is generally built from the property Dublin Core : Has Part.
Display the last messages from an account on Twitter. To use it, you may use your own developer bearer token, else the module will try to use an anonymous one.
Technical note: Since December 2020, it is required to get a dev account to fetch messages of a user, because Twitter disabled any standard html endpoint (see this issue on StackOverflow). If you use a dev account, it is not necessarily the one of the thread to follow.
Nevertheless, it is still possible to fetch them with an anonymous bearer token.
To get it, check the urls in the dev tools of your browser in the "network" tab.
The token is set in the header of the requests to https://api.twitter.com with
the key Authorization
, for example AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA
.
This token will be available for the next two years, or less. Anyway, the
module fetches it automagically. Nevertheless, it uses some hard coded urls that
may change.
Check how to generate a bear token. You need to create an app in your account too. If you can't, try to check the option to use the Api version 1.1.
In all cases, there is a rate limit, but generally largely enough for a common digital library.
A block that does nothing, but that may be useful for theme developer.
This block displays the breadcrumbs of the current page according to site settings.
This block displays buttons to share the current page in a privacy-compliant way. Available buttons are Download, Email, Facebook, Pinterest and Twitter. The config should be set in site settings.
Display the description of the resource.
Allow to wrap a list of block with a html element <div>
. It is useful to use a
theme natively. They are the same, but with a different class. You can use the
block Html Section too.
Add a link to the item from the media.
Display the messages (notice, warning and errors), like in admin. This block may be useful for modules like Contact Us, Contribute, Guest, Bulk export, etc. that add some interactions with the visitor.
Allow to display buttons previous resource and next resource in the list.
Warning: to define what is the previous or next resources is not so simple, because it may be the order in a item set, or order in the last results of a research.
For order in item set when an item is in multiple item set, an option in main settings allows to define which property define it. Another option allows to define the default order.
When a search is done, the list is built from the user last browse query, else from natural order or the item set one.
The default order without previous browse or search can be set in site settings for items and item sets. For media, the order is defined in item.
This block requires the module Easy Admin.
It can be used as a theme helper too (see below).
Allow to wrap a list of block with a html element <section>
. It is useful to use
a theme natively.
This block provides the same information than the view helper pageMetadata()
(see below), but from a block. It is usefull with the simple block to extract
params, or to get some informations about the page from anywhere in the theme.
// A simple check is done to make the theme more generic.
$blockMetadata = $plugins->has('blockMetadata') ? $plugins->get('blockMetadata') : null;
if ($blockMetadata) {
$data = $blockMetadata('params_key_value');
}
The view helper CaptionClassAndUrl()
allows to extract a class, a url and a
label from the start of a string. The optional class, url and label may be set
at start of a caption like:
url = https://example.org/
class = xxx yyy
label = Any zzz
Next lines are the true caption.
The initial caption may be an html one.
The output is a simple array containing caption, class, url, and label and flags for local url (relative url), local media file, and html. Get result like:
[$caption, $class, $url, $label, $isLocalUrl, $isMediaFile, $isHtml] = $this->captionClassAndUrl($string);
Allow to add a type to the page, so it’s simpler to have different templates for different pages. It allows in particular to create exhibits inside a site, without creating a new site.
You can add new types in the settings of the site. Then, in your theme, you can
get the page type $pageType = $this->pageMetadata('type');
and many other data
about the page. If the page is an exhibit, it is possible to build a specific
navigation menu of this exhibit too, like in the site Fondation de la Maison de Salins.
To manage multiple types, it’s generally required to edit the template "view/omeka/site/page/show.phtml" of your theme and to add a check:
// A simple check is done to make the theme more generic.
$pageMetadata = $plugins->has('pageMetadata') ? $plugins->get('pageMetadata') : null;
if ($pageMetadata):
$type = $pageMetadata('type') ?: null;
switch ($type):
case 'home':
$class = 'home';
// Specific html code…
break;
case 'exhibit':
$class = 'exhibit';
// Specific html code…
break;
case 'exhibit_page':
$class = 'exhibit-page';
// Specific html code…
break;
case 'simple':
$class = 'simple-page';
// Specific html code…
break;
default:
// Generic html code…
$class = 'page';
break;
endswitch;
$this->htmlElement('body')->appendAttribute('class', $class);
// …
endif;
This view helper allows to get the data of all pages of the same type in the current site. For example, you can get all "exhibit_page". Multiple types can be retrieved at once.
// A simple check is done to make the theme more generic.
$pagesMetadata = $plugins->has('pagesMetadata') ? $plugins->get('pagesMetadata') : null;
if ($pagesMetadata) {
$data = $pagesMetadata('exhibit_page');
}
A breadcrumb may be added on resources pages via the command echo $this->breadcrumbs();
.
The default template is common/breadcrumbs.phtml
, so the breadcrumb can be
themed. Some options are available too.
By default, the breadcrumbs for an item use the first item set as the parent
crumb. The first item set is the item set with the smallest id. If you want to
use another item set, set it as resource in the property that is set in the main
settings, or in the options of the view helper.
These helpers require the module Easy Admin.
To use it, add the following code in the item, item set, or media show page:
<?php
$plugins = $this->getHelperPluginManager();
$previousNext = $plugins->has('previousNext') ? $plugins->get('previousNext') : null;
?>
<?= $previousNext ? $previousNext($resource) : '' ?>
Two other helpers can be used to manually build the html code:
<?php
$plugins = $this->getHelperPluginManager();
$hasPreviousNext = $plugins->has('previousNext');
?>
<?php if ($hasPreviousNext): ?>
<div class="previous-next-items">
<?php if ($previous = $this->previousResource($resource)): ?>
<?= $previous->link($translate('Previous item'), null, ['class' => 'previous-item']) ?>
<?php endif; ?>
<?php if ($next = $this->nextResource($resource)): ?>
<?= $next->link($translate('Next item'), null, ['class' => 'next-item']) ?>
<?php endif; ?>
</div>
<?php endif; ?>
Allow to go back to the last list of results in order to browse inside item sets, items or media after a search without losing the search results. It can be appended automatically with helper "previousNext()" and option "back" set to true.
A module can add page and block templates to theme: just add them in the file
config/module.config.ini of the module under keys page_templates
and block_templates
,
for example:
'block_templates' => [
'asset' => [
'asset-bootstrap-hero' => 'Block Plus: Bootstrap Hero', // @translate
],
],
See more info on page templates and block templates in user doc and dev doc.
Select them in the view "Page edit". You may theme them too: copy the block
templates that are in view/common/block-layout/
in the same place of your
theme.
The core blocks (Browse preview, Html, Item metadata, Item showcase, List of pages, List of sites, Page title, Table of contents) are improved with two new options:
Most of the blocks have an option to set a title.
Most of block have an option to set a specific template, so it’s possible to display these blocks differently in the same page or on different pages.
Warning
When a block allows to select a template, the filename must start with the same string than the original template, for example "table-of-contents-pages.phtml" for the block "TableOfContents".
Furthermore, it should exists in a module or in the current theme. When the template is missing, for example when switching into another theme, the default of the template is used. Thereby, when the module or the theme that has this template is replaced, you have to check the pages that use it.
Since the integration of "asset" in Omeka 3.1, this block is an improved version of the core block "asset". It can list assets with optional link to pages, labels and caption. The assets are not required to be filled, so it allow to display any list of contents.
Unlike the upstream version, it has a specific class
option at asset level and
supports templates. Some templates are available: "asset-block", "asset-hero-bootstrap",
"asset-left-right" and "asset-partners".
See above.
The block Browse preview has new fields to display sort headings and pagination, so it's now possible to have a specific list of items, like the main browse view.
For the specific templates, see above.
See above.
Allow to wrap a block or multiple block with a div
. in particular to create
columns. Divisions can be nested. The css should be prepared in the theme to
managed them. By default, only a simple aside
column of 30% is available with
class column align-right
(or left).
Allow to display an external resource. The block contains an html textarea too. See above.
See above.
See above.
See above.
Display the date of the creation and/or modification of the current page. See Omeka issue #1706.
See above.
Simplify the display of a media on the left or the right (see user guide). It is the same block that existed in Omeka Classic. It was migrated to a block Group with blocks Media and Html.
See above.
See above.
Allow to set a div with a specific class between two blocks. May be useful to fix some css issues, or to increase space between some blocks. The content of the block is:
<div class="break separator"></div>
Replaced by block "Line Break".
See above.
See above.
See above.
See above.
Warning: when a page is saved, all remaining settings that are not managed by the form are removed. So the best way to see issues is to load all pages before migration and to load all pages after migration AND resaving each page.
See more info on page templates and block templates in user doc and dev doc.
The following blocks are no more overridden:
The following blocks are no more overridden, but contains a fix/feature and will be removed soon when integrated upstream:
The new templating mechanism of Omeka S v4.1 uses a new directory in theme to
allow to use block template. You should move all templates from view/common/block-layout
to view/common/block-template
that were a template managed by this module, but
not the default templates named like the original ones.
For example, if you used the block "Block" with the default template customized in your theme, let it as "view/common/block-layout/block.phtml". But if you used the same block with a module template, move it to "view/common/block-template/block-glossary.phtml".
Then, you should add the specific templates in the file config/theme.ini of the theme.
Some templates are deprecated and were renamed with a "-plus" and moved in
directory view/common/block-template
. The migration moved the option to use
the new template name.
This template was renamed, but not deprecated:
You should add the specific templates in the file config/theme.ini of the theme if you really need them. Else, it is recommended to use the default template.
You should check the styles of all of them.
The option heading
of all blocks were removed. A new block "Heading" was
added and the migration prepended it automatically. But the <div>
is no more
inside the <div>
of the previous block and the heading level is always
converted to 2, whatever the level was.
Warning: the block "Browse preview" still uses the setting "heading".
It is the same for the option html
that was added in some blocks and moved to
a prepended standard block "html".
The core migration used the option alignment
too in some blocks, that may have
created some style issues too.
These classes were added to a main div of the block. They are now managed by the core, that separated styling. These values are now managed in a upper div and the migration moved them to the new layout data.
You should remove them from the phtml files of the themes and check if styles is right in all pages.
For block Asset, the keys "class" and "url" of assets were moved to the top of the caption and automatically extracted in templates.
url = https://example.org/
class = xxx yyy
Next lines are the true caption.
You should check the theme manually if you use this feature and get class and url like other asset templates:
[$caption, $class, $url, $label, $isLocalUrl, $isMediaFile, $isHtmlCaption] = $this->captionClassAndUrl($attachment['caption']);
The block Browse Preview is no more managed by this module. Support of options "html", "sort_headings" and "pagination" were removed. Check your themes if you used it, or use block Search Results.
Normally, the migration converted this block into a block Search Results when the specific features were used, else converted it in a block template for block Browse Preview.
Furthermore, the variable $site
is no more available in block templates for
Browse Preview, so you should add $site = $block->page()->site();
or $site = $this->currentSite()
if you need it.
You should fix the theme manually.
The block Division was removed. When the divisions were flat, they were converted into a group of blocks, a new feature of Omeka S v4.1.
When the divisions were nested, the migration was not done, so you should do it manually with page template "grid" and/or blocks groups.
Furthermore, the option "tag", that can be "div" or "aside", is no more managed.
The block does not manage html any more, so it display an external resource. The migration converts it to a group of blocks External Content and Html. Furthermore, the option Caption Position is now a class of the block. So you may check styles.
The variable $html
is no more available in templates for block Html, so you
should get it via $block->dataValue('html', '')
. A list of matched files was
added during migration and is available in logs.
You should fix the theme manually.
The block Item Showcase was renamed Media in Omeka S v4.1. The option "linkType" was renamed "link".
You should fix the theme manually.
The block is now a group of blocks Media and Html, so structure and classes were updated, so you may check styles.
The block class is now in the block template, so you may check styles.
For modules that used the form select element "template", you should do the same migration and use the same mechanism of block template. The select element will be removed in a future version.
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 module is published under the CeCILL v2.1 license, compatible with GNU/GPL and approved by FSF and OSI.
In consideration of access to the source code and the 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 only have limited liability.
In this respect, the risks associated with loading, using, modifying and/or developing or reproducing the software by the user are brought to the user’s attention, given its Free Software status, which may make it complicated to use, with the result that its use is reserved for developers and experienced professionals having in-depth computer knowledge. Users are therefore encouraged to load and test the suitability of the software 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 of security. This Agreement may be freely reproduced and published, provided it is not altered, and that no provisions are either added or removed herefrom.
MIT license.
One of the CKEditor ones [GPL].
One of the CKEditor ones [GPL]. See [CKEditor-Footnotes].
ISC License (equivalent to MIT)
See MIT license here: http://tympanus.net/codrops/licensing/ The original template was fixed by KevinMwangi and updated for newer version of components (modernizr, smartresize, imagesloaded).