Opening Hours is a highly customizable WordPress plugin to set up your venue's opening hours and display them with Shortcodes and Widgets.
- Features
- Installation
- Getting Started
- Widgets
- Shortcodes
- Troubleshooting / FAQ
- Contributing
- Changelog
- Donate
- License
- Supports multiple Sets of Opening Hours (e.g. one for your restaurant and one for your bar) that you can use independently.
- Supports Hollidays
- Supports Irregular Openings (e.g. different opening hours during Christmas)
- Supports child sets that overwrite your regular opening hours in a specific time period (e.g. seasonal opening hours or an extra day in every second week)
- Four highly customizable Widgets and Shortcodes also displaying contextual information (e.g. "We're currently closed but will be open again on Monday at 8am")
- Go to your WordPress dashboard
- Navigate to "Plugins"
- Click "Install"
- Search for "Opening Hours"
- Click "Install" on the Plugin "Opening Hours" by Jannik Portz
- Activate the Plugin
- Download the .zip-archive from https://wordpress.org/plugins/wp-opening-hours/
- Unzip the archive
- Upload the directory /opening-hours to your wp-content/plugins
- In your Admin Panel go to Plugins and active the Opening Hours Plugin
- Now you can edit your Opening Hours in the Settings-Section
- Place the Widgets in your Sidebars or use the Shortcode in your posts and Pages
If you are managing your WordPress Plugins via composer (e.g. when using Bedrock) the Opening Hours Plugin is also available on wpackagist.
Make sure you have wpackagist registered as repository in your composer.json file
"repositories": [
{
"type": "composer",
"url": "https://wpackagist.org"
}
],Add the Opening Hours plugin as dependency
"require": {
"wpackagist-plugin/wp-opening-hours": "1.2"
}Especially when installing a beta version for testing it makes sense to clone the GitHub Repository and checkout the branch from which you want to install the plugin. Before you can actually use the plugin you will have to perform the following steps (Node.js required)
- Open your command line and navigate to the project directory
- Make sure you have already loaded the submodules. If not run
git submodule update - If you do not already have gulp installed globally run
npm install -g gulp npm installgulp build
Alternatively you can also clone the repository somewhere on your computer and run gulp export instead of gulp build.
A .zip archive containing a built version of the plugin will be placed inside the project directory that you can unzip and place in
the wp-content/plugins directory of the WordPress installation of your choice.
The first step to set up your Opening Hours is to create a Set. A Set consists of Periods for all weekdays, Holidays and Irregular Openings. If you only want to display the Opening Hours for one venue you're fine with a single Set but you can as well add multiple Sets, each representing individual Opening Hours. You can for example add one Set for your restaurant and one Set for your Bar if you use one website for them and specify the desired Set per Widget or Shortcode.
Please Note: You will need to have administrator priviledges to manage Sets
Step 1: Go to your admin Dashboard and navigate to "Opening Hours". You will see a list of all your Sets. To add a new Set click "Add New" next to the heading.
Step 2: Give your Set a name in the "Enter title here" input. The name is only used internally and you can specify individual titles per Widget or Shortcode.
Step 3: Set up Opening Hours. In the Opening Hours Section you can edit the time inputs for each weekday. When clicking the +-Button you can add more periods per day. When clicking the x-Button next to a period you can delete periods.
Step 4: Set up Holidays. In the Holidays Section you can edit the name and the start and end dates. When clicking the "Add New Holiday" you can add more Holidays. You can also delete holidays when clicking the x-Button next to a Holiday.
Step 5: Set up Irregular Openings. Irregular Openings specify irregular opening hours for a specific day. You would for example add an Irregular Opening for NYE when you are only open in the morning. You can edit the name, the date and start and end time.
When clicking the "Add New Irregular Opening" you can add more Irregular Openings. You can also delete Irregular Openings when clicking the x-Button next to a row.
Step 6 (optional): In the Set Details Section you can give your Set a description. This is optional but the description can be displayed in the Overview Widget/Shortcode.
Step 7 (optional): In the Set Details section you can also set your custom Set Alias which you can use instead of the Set Id in Shortcodes. If you specify a specific Set Alias for more than one Set all Shortcodes will use the Set with the least value for menu_order.
Your Theme or a 3rd party Plugin may also specify Set Alias presets to make it easier for yor to enter the right one. Please note that Set Alias presets only work in browsers supporting HTML5 datalist.
Step 8: Save the data by clicking the "Save"/"Publish"-Button. Any changes will not be saved without saving the whole Set!
You may also set up child Sets with different Opening Hours for a longer Period of time. You can define a date range or a week scheme (even/odd weeks) when the Opening Hours of the Child Set should be used. You can for example use Child Sets if you have different Opening Hours in winter.
In Child Sets you can only set up Opening Hours but no Holidays or Irregular Openings.
Step 1: Make sure you have another Set which you can use as parent Set with the "regular" Opening Hours.
Step 2: Add a new Set by clicking the "Add New"-Button in the list of Sets.
Step 3: In the Attributes Section select the parent Set under "Parent".
Step 4: Click the "Save"/"Publish"-Button
Step 5: Set up the custom Opening Hours for the Child Set.
Step 6: Set the usage criteria in the Set Details Section. You can set a start and end date and/or a week scheme. Note that if you don't set start or end date and leave week scheme at "Every Week" the Child Set will never be used.
Step 7: Save the Child Set.
The Plugin will now automatically use the Opening Hours of the Child Set when the usage criteria matches the current time.
The Overview widget displays a table with all the opening hours in the speficied set.
There are the following options:
| Name | Description |
|---|---|
| Title | The title of the Widget. Will be displayed above the opening hours |
| Set to show | Select the set whose opening hours you want to show |
| Highlight |
Select which type of information shall be highlighted. Possible options are:
|
| Show closed days | Whether to display a row for closed days with a "Closed"-caption |
| Show description | Whether to display the set description above the opening hours |
| Compress opening hours | Whether to compress the opening hours. This means that the plugin will search for days with mutual opening hours and then group those together to one row in the table with a title like "Monday - Wednesday". |
| Use short day captions | Whether to use abbreviations for weekdays. E.g. "Monday" becomes "Mon.". This feature is also available in all other supported languages. |
| Include Irregular Openings | If there is an irregular opening on any day in the table it will replace the regular opening hours with the irregular opening hours for that day. |
| Include Holidays | If there is a holiday during one or more days in the table it will replace the regular opening hours of those days with the name of the holiday. |
| Template | You can choose among two templates: Table and List. The list template will display all data in a vertical list. This is useful for narrow sidebars. |
| Extended Settings | |
| Caption closed | Speficy a custom caption for closed days. |
| Highlighted period class | Custom CSS class for highlighted periods. default highlighted |
| Highlighted day class | Custom CSS class for highlighted days. default: highlighted |
| PHP Time Format | Custom format for times. The default is your standard WordPress setting. More on PHP date and time formats |
| Hide date of irregular openings | Whether to hide the date of irregular openings if they are in the table. |
| Week offset | Number of weeks the shortcode data shall be offset. Might be a positive or negative integer. |
The Is Open Widget displays a message whether a venue (a Set) is currently open/active.
There are the folliwing options:
| Name | Description |
|---|---|
| Title | The Widget Title |
| Set | Select a set whose opening status you want to show |
| Show next open period | When checked, a message telling the next open period will be displayed if the venue (set) is currently closed. |
| Show today's opening hours | Specify in which cases today's opening hours shall be displayed in the widget |
| Extended Settings | |
| Caption if open | Custom caption to show when the venue is open |
| Caption if closed | Custom caption to show when the venue is closed |
| Class if open | Custom CSS class when the venue is open |
| Class if closed | Custom CSS class when the venue is closed |
| Next Period string format | A custom string format for the next open period message. You can populate the string with the following placeholders:
We're open again on %2$s (%1$s) from %3$s to %4$s
|
| Today' opening hours string format | A custom string format for the today's opening hours message. You can populate the string with the following placeholders:
We're open today from %2$s to %3$s.
|
| PHP Date Format | Custom PHP date format for the date of the next open period. The default is your standard WordPress setting. More on PHP date and time formats |
| PHP Time Format | Custom PHP date format for the start and end time of the next open period. The default is your standard WordPress setting. More on PHP date and time formats |
The holiday widget displays all holidays in the specified set in a table or list. Holidays are always sorted ascedingly by their start dates.
There are the following options:
| Name | Description |
|---|---|
| Title | The Widget title |
| Set | Select a set whose holidays you want to display. |
| Highlight active holidays | Whether to highlight active holidays in the table |
| Template | You can choose among two templates: Table and List. The list template will display all data in a vertical list. This is useful for narrow sidebars. |
| Include past holidays | Whether to show past holidays in the widget |
| Extended Settings | |
| Class for highlighted Holiday | Custom CSS class for highlighted Holidays. default: highlighted |
| PHP Date Format | Custom PHP date format for the start and end date of the holidays. The default is your standard WordPress setting. More on PHP date and time formats |
The Irregular Openings Widget displays all Irregular Openings in the specified Set in a table or list. Irregular Openings are always sorted ascendingly by their start dates and times.
An Irregular Opening is reagarded as being in the past, when the full day, when the Irregular Opening takes place, has ended.
There are the following options:
| Name | Description |
|---|---|
| Title | The Widget title |
| Set | Select a Set whose Irregular Openings you want to show. |
| Highlight active Irregular Opening | Whether to highlight active irregular openings in the table or list |
| Template | You can choose among two templates: Table and List. The list template will display all data in a vertical list. This is useful for narrow sidebars. |
| Include past irregular openings | Whether to show past irregular openings in the widget |
| Extended Settings | |
| Class for Highlighted Irregular Opening | Custom CSS class for highlighted Irregular Openings in the table or list. default: highlighted |
| PHP Date Format | Custom PHP date format for the date of the irregular openings. The default is your standard WordPress setting. More on PHP date and time formats |
| PHP Time Format | Custom PHP date format for the start and end time of the irregular openings. The default is your standard WordPress setting. More on PHP date and time formats |
The Schema.org Widgetadds a JSON-LD record to the WordPress site representing the opening hours of a given Set. Refer to the docs on Schema.org integration for more information.
There are the following options:
| Name | Description |
|---|---|
| Set | The Set whose JSON-LD representation to insert |
| Exclude Holidays | When enabled, holidays are not considered for the SpecialOpeningHoursSpecification |
| Exclude Irregular Openings | When enabled, irregular openings are not considered for the SpecialOpeningHoursSpecification |
| Extended Settings | |
@Type property of the schema object |
Custom override for the @type of the schema record. By default Place is taken. |
name property of the schema object |
Custom override for the name of the schema record. By default the name of the selected Set is taken. |
description property of the schema object |
Custom override for the description of the schema record. By default the description of the selected Set is taken. |
Shortcodes are a WordPress core component, which give you the ability to add rich components to your posts' and pages' content. You can insert a Shortcode in the default WordPress editor.
The basic format of a shortcode is:
[shortcode-tag an_attribute="attr_value" another_attribute="another_attr_value"]
Heads up
Shortcode attributes of typeboolcan either betrue(meaning "yes") orfalse(meaning "no").
You can read more about Shortcodes in the WordPress documentation.
Shortcodes have exactly the same options as Widgets because every Widget is basically a representation of the corresponding Shortcode with a GUI for the Widget edit section.
The only required attribute for all Shortcodes is set_id. All other attributes are optional!
The Opening Hours Shortcode Builder assembles shortcodes for you that you can copy and insert into your content. This is particularly useful for people who are unfamiliar with shortcodes.
The builder can be found at https://janizde.github.io/opening-hours-shortcode-builder/
Development takes place in the GitHub Repo
In the edit page of parent sets the button Create a Shortcode opens the shortcode builder in a popup and prefills the set_id accordingly.
| Name | Type | Default | Description |
|---|---|---|---|
set_id |
int|string |
– | (required) The id of the set whose data you want to show. For regular Sets you may also use your custom Set Alias here |
title |
string |
– | The widget title |
before_title |
string |
<h3 class="op-{name}-title"> |
HTML before the title. When using Widgets this will be overridden by the sidebar's before_title attribute. |
after_title |
string |
</h3> |
HTML after the title. When using Widgets this will be overridden by the sidebar's after_title attribute. |
before_widget |
string |
<div class="op-{name}-shortcode"> |
HTML before shortcode contents. When using Widgets this will be overridden by the sidebar's before_widget attribute. |
after_widget |
string |
</div> |
HTML after shortcode contents. When using Widgets this will be overridden by the sidebar's after_widget attribute. |
Corresponds to the Overview Widget.
The [op-overview] shortcode displays the opening hours of the specified set.
The following attributes are available (Also mind the Common Attributes):
| Name | Type | Default | Description |
|---|---|---|---|
show_closed_days |
bool |
false |
Whether to display a row for closed days with a "Closed"-caption |
caption_closed |
string |
Closed |
Change the text of the closed caption |
show_description |
bool |
false |
Whether to display the set description above the opening hours |
highlight |
string |
noting |
What type of information to highlight. Possible values are: noting, period (currently active period), day (current weekday) |
compress |
bool |
false |
Whether to compress the opening hours. This means that the plugin will search for days with mutual opening hours and then group those together to one row in the table with a title like "Monday - Wednesday". |
short |
bool |
false |
Whether to use abbreviations for weekdays. E.g. "Monday" becomes "Mon.". This feature is also available in all other supported languages. |
include_io |
bool |
false |
If there is an irregular opening on any day in the table it will replace the regular opening hours with the irregular opening hours for that day. |
include_holidays |
bool |
false |
If there is a holiday during one or more days in the table it will replace the regular opening hours of those days with the name of the holiday. |
highlighted_period_class |
string |
highlighted |
CSS class for highlighted periods |
highlighted_day_class |
string |
highlighted |
CSS class for current weekday |
time_format |
string |
WordPress setting | Custom format for times. The default is your standard WordPress setting. More on PHP date and time formats |
hide_io_date |
bool |
false |
Whether to hide the date of irregular openings if they are in the table. |
template |
string |
table |
Identifier for the template to use. Possible values are table and list |
week_offset |
int |
0 |
Number of weeks the shortcode data shall be offset. Might be a positive or negative integer. Example: 1: Show data of next week
|
Corresponds to the Is Open Widget.
The [op-is-open] shortcode displays a message whether the specified venue (set) is currently open or not.
The following attributes are available (Also mind the Common Attributes):
| Name | Type | Default | Description |
|---|---|---|---|
open_text |
string |
We're currently open (translated) | Caption to show when the venue is open |
closed_text |
string |
We're currently closed (translated) | Caption to show when the venue is closed |
closed_holiday_text |
string |
We\'re currently closed for %1$s. (translated) |
Caption to show when the venue is closed and if there is one or more holidays, show them in a comma separated list Note: show_closed_holidays must be set to true for this to be displayed.
|
show_next |
bool |
false |
When true, a message telling the next open period will be displayed if the venue (set) is currently closed. |
show_today |
string (enum) |
never |
When to show today's opening hours The following values are valid:
|
show_closed_holidays |
bool |
false |
Show today's holiday name(s) when closed |
next_format |
string |
We're open again on %2$s (%1$s) from %3$s to %4$s |
A custom string format for the next open period message. You can populate the string with the following placeholders:
|
today_format |
string |
Opening Hours today: %1$s |
A custom string format for the today's opening hours message. You can populate the string with the following placeholders:
|
open_class |
string |
op-open |
CSS class if the venue (set) is open |
closed_class |
string |
op-closed |
CSS class if the venue (set) is closed |
date_format |
string |
WordPress setting | PHP date format for the date of the next open period. More on PHP date and time formats |
time_format |
string |
WordPress setting | PHP date format for the start and end time of the next open period. More on PHP date and time formats |
Corresponds to the Holidays Widget.
The [op-holidays] shortcode displays all holidays in the specified set in a table or list.
The following attributes are available (Also mind the Common Attributes):
| Name | Type | Default | Description |
|---|---|---|---|
highlight |
bool |
false |
Whether to highlight currently active holidays |
include_past |
bool |
false |
Whether to include past holidays |
class_holiday |
string |
op-holiday |
CSS class for a single holiday |
class_highlighted |
string |
highlighted |
CSS class for highlighted holidays |
date_format |
string |
WordPress setting | PHP date format for the start and end date of the holidays. More on PHP date and time formats |
template |
string |
table |
Identifier for the template to use. Possible values are table and list |
Corresponds to the Irregular Openings Widget.
The [op-irregular-openings] shortcode displays all irregular openings in the specified set in a table or list.
The following attributes are available (Also mind the Common Attributes):
| Name | Type | Default | Description |
|---|---|---|---|
highlight |
bool |
false |
Whether to highlight currently active irregular openings. |
include_past |
bool |
false |
Whether to include past irregular openings |
class_highlighted |
string |
highlighted |
CSS class for highlighted irregular openings |
date_format |
string |
WordPress setting | PHP date format for the date of the irregular openings. More on PHP date and time formats |
time_format |
string |
WordPress setting | PHP date format for the start and end time of the irregular openings. More on PHP date and time formats |
template |
string |
table |
Identifier for the template to use. Possible values are table and list |
Corresponds to the Schema.org Widget.
The [op-schema] shortcode adds a JSON-LD record to the WordPress site representing the opening hours of a given Set. Refer to the docs on Schema.org integration for more information.
The following attributes are available (This shortcode does not process the Common Attributes):
| Name | Type | Default | Description |
|---|---|---|---|
set_id |
number|string |
none | The Set id or Set alias of the set |
exclude_holidays |
bool |
false |
When enabled, holidays are not considered for specialOpeningHoursSpecification |
exclude_irregular_openings |
bool |
false |
When enabled, irregular openings are not considered for specialOpeningHoursSpecification |
schema_attr_type |
string |
Place |
The @type property of the schema.org object. |
schema_attr_name |
string |
Name of the seleted Set | The name property of the schema.org object. |
schema_attr_description |
string |
Description of the selected Set | The name property of the schema.org object. |
If you worked with previous verions of the Plugin you may miss the settings page. The new version of the Plugin uses your WordPress setting you can set under Settings > General
Furthermore you may also set your custom date and time formates per Widget / Shortcode.
The calculation of the Is Open status depends on the Timezone setting in WordPress. Please double check your Timezone setting under Settings > General before opening an issue.
The Plugin provides very minimal styling, which is the red and green colors for the open / closed messages. All other kind of styling is left to the WordPress Theme you are using or your custom CSS.
To disable the styling of the text color the op_use_front_end_styles filter hook can be used.
The development of the Opening Hours Plugin takes place at GitHub.
If you want to contribute feel free to fork the repository and send pull requests.
The project uses GitFlow. You can get more information on GitFlow on the GitFlow Cheat Sheet.
When forking the repository for contributions please fork from the develop branch. If the pull request will be accepted it will be released to the master branch for a new version of the Plugin.
The core logic of the Plugin (classes that are not in the OpeningHours\Module namespace) is covered with PHPUnit tests (version 4.8).
If you find an issue in the core logic please write one or more unit test which demonstrate this issue. If you add something to the core logic please also write a unit test. Also, before sending a pull request, run all unit tests to check whether your change has broken anything (it will be automatically tested by travis anyway).
(Plugin) translation files (.po and .mo) files contain translations for all strings that are included in the plugin source code, e.g. labels for the widget edit inputs. In this plugin this are mostly strings that occur in the WordPress admin.
This means you can customize every string presented on your WordPress Front-End site using Widget and/or Shortcode options. If the Plugin has not yet been translated to your language and you are fine with English in your WordPress admin you do not have to submit your own translations but can cutomize the Widget/Shortcode strings to match the language of your site.
However, you can still submit your translations to Polyglots so other Plugin users can benefit from it.
The translations of weekdays are not included in the Plugin translations but are loaded from the WordPress core translations. This serves the purpose, that these are always translated to the language that your WordPress installation runs on independently of the Plugin translation progress.
Polyglots is the name of the community of volunteers translating WordPress resources like Themes, Plugins and also the WordPress core. It has become a central place for WordPress translation and is tightly coupled with the WordPress Theme/Plugin repositories.
Since version 2.0 the translation of the Opening Hours Plugin takes place at translate.wordpress.org. Advantages of using Polyglots:
- Larger translation community
- Translation can be separated from the actual development of the Plugin
- Supports automatic translation updates, so you do not have to wait for the next release to get new translations
If you want to contribute to translations and there is no Project Translation Editor for your locale, please drop me a message or open an issue with your WordPress.org username and I will request an editorship for your locale.
You can find out more about project translation roles here.
If you have already translated the Plugin on translate.jannikportz.de, I have transferred all translations to the translate.wordpress.org project. You will then also need to become a Project Translation Editor to approve your translations (I know this is a bit tedious). So in this case please also drop me a message or open an issue with your WordPress.org account name.
If you can not translate the whole plugin or don't want to wait until everything is approved you may perform the following steps to immediately use your translations.
- Select the translation set in the list of available languages.
- Scroll to the bottom.
- In the line below the legend, select
all currentasMachine Object Message (.mo)and clickExport. - Rename the file to
wp-opening-hours-{locale}.mo(replace{locale}with the actual locale of the translation, e.g.de_DEfor German). - Move the file to
/path/to/wordpress/wp-content/languages/plugins
Translations via Pull Request on GitHub are no longer supported and won't be merged in the future, as translation now takes place at WordPress Polyglots. Please refer to the section on WordPress Polyglots
translate.jannikportz.de has been shut down in favor of WordPress Polyglots. Please refer to the section on WordPress Polyglots
- Fix a bug that would cause redundant database writes caused by a DB_VERSION mismatch
- Add filter
op_shortcode_template_path - Deprecate filter
op_shortcode_templatein favor ofop_shortcode_template_path - Consistently use en dashes to separate dates and times in default formats
- Add filter
op_set_post_type_arguments
- Add support for custom user locales in the admin panel for cases when the user locale differs from the site locale
- Added [op-schema] shortcode and Schema.org Widget for structured JSON-LD representation of opening hours, holidays and irregular openings
- Added button for Shortcode Builder in Set edit page
- Fixed a warning occuring in the Overview shortcode with PHP >= 7.2
- Added method
OpeningHours->clearSetProviders()toOpeningHourssingleton
- Fix concerning time formats of Irregular Openings and Periods when saving by @Braunson
- Fixed JavaScript conflicts with other plugins
- Fixed a bug that did not load the parent set's irregular openings and holidays in active child sets.
- Fixed a bug that blocked irregular openings and periods on the days after irregular openings that go beyond midnight.
- Added today's opening hours in Is Open shortcode / widget
- Automatically hide past Holidays and Irregular Openings in the respective shortcodes / widgets
- Sort Holidays and Irregular Openings ascendingly by start date
- Use WordPress shipped version of jquery-ui to prevent conflicts with other plugins
- Merge dates of Holidays if they only span one day
- Added offset option to Overview shortcode / widget
- Added filters
op_is_open_format_nextop_is_open_format_todayop_overview_model
- Various bug fixes
- fixed bug concerning child set initialization. thanks to @nikomuse
- Added support for UTC offset timezones
- Fixed timezone bug in WordPress 4.7
- Fixed a bug that didn't show next open Period when there are no regular Periods but Irregular Openings in the current Set
- Added SetAlias functionality
- Minor fixes including:
- Fixed mixed content error (@foomep)
- Fixed auto convert issue
- Fixed PHP 5.3 incompatibility issues
Completely new Plugin. When Updating you will have to set up your Opening Hours and Widgets / Shortcodes again!
I'd be very pleased if you donated a small amount if you like the plugin as I put much effort and much of my free time into the development
of this plugin.
You can donate via:
PayPal:
Copyright © 2016 Jannik Portz
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/.