Public git repository for WP Opening Hours Plugin. Starting from version 2.0
PHP JavaScript CSS

README.md

WordPress Opening Hours

Build Status gitcheese.com Flattr this git repo Donate

Opening Hours is a highly customizable WordPress plugin to set up your venue's opening hours and display them with Shortcodes and Widgets.

Contents

Further Reading

Features

  • 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")

↑ Table of Contents

Installation

WordPress Plugin Installer

  1. Go to your WordPress dashboard
  2. Navigate to "Plugins"
  3. Click "Install"
  4. Search for "Opening Hours"
  5. Click "Install" on the Plugin "Opening Hours" by Jannik Portz
  6. Activate the Plugin

Manual Installation

  1. Download the .zip-archive from https://wordpress.org/plugins/wp-opening-hours/
  2. Unzip the archive
  3. Upload the directory /opening-hours to your wp-content/plugins
  4. In your Admin Panel go to Plugins and active the Opening Hours Plugin
  5. Now you can edit your Opening Hours in the Settings-Section
  6. Place the Widgets in your Sidebars or use the Shortcode in your posts and Pages

Composer

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"
}

From GitHub repository

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)

  1. Open your command line and navigate to the project directory
  2. Make sure you have already loaded the submodules. If not run git submodule update
  3. If you do not already have gulp installed globally run npm install -g gulp
  4. npm install
  5. gulp 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.

↑ Table of Contents

Getting Started

Setting up your Opening Hours

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.

Opening Hours Menu

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.

Specify Set name

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.

Specify Opening Hours

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.

Specify Holidays

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.

Specify Irregular Openings

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.

Specify Set name

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.

Specify Set Alias

Step 8: Save the data by clicking the "Save"/"Publish"-Button. Any changes will not be saved without saving the whole Set!

Child Sets

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".

Specify parent Set

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.

Specify child Set criteria

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.

↑ Table of Contents

Widgets

Overview Widget

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:
  • Nothing
  • Running Period
  • Current Weekday
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.

Overview Widget in table view

Overview Widget Table

Overview Widget in list view

Overview Widget List

Overview Widget Options

Overview Widget Options

Is Open Widget

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:
  • %1$s The formatted date of the next open period
  • %2$s The name of the weekday of the next open period
  • %3$s The formatted start time of the next open period
  • %4$s The formatted end time of the next open period
Example: 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:
  • %1$s The formatted time ranges of all periods
  • %2$s The formatted start time of the first period
  • %3$s The formatted end time of the last period
Example: 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

Is Open Widget showing next open Period

Is Open Widget

Is Open Widget Options

Is Open Widget Options

Holidays Widget

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

Holidays Widget in table view

Holidays Widget in table view

Holidays Widget in list view

Holidays Widget in list view

Holidays Widget Options

Holidays Widget options

Irregular Openings Widget

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

Irregular Openings Widget in list view

Irregular Openings Widget in list view

Irregular Openings Widget options

Irregular Openings Widget options

↑ Table of Contents

Shortcodes

General

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 TinyMCE editor.

The basic format of a shortcode is:

[shortcode-tag an_attribute="attr_value" another_attribute="another_attr_value"]

Heads up
Shortcode attributes of type bool can either be true (meaning "yes") or false (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!

Common attributes for all Shortcodes

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.

op-overview Shortcode

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
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

op-is-open Shortcode

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
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:
  • never
  • open
  • always
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:
  • %1$s The formatted date of the next open period
  • %2$s The name of the weekday of the next open period (translated)
  • %3$s The formatted start time of the next open period
  • %4$s The formatted end time of the next open period
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:
  • %1$s The formatted time ranges of all periods
  • %2$s The formatted start time of the first period
  • %3$s The formatted end time of the last period
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

op-holidays Shortcode

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

op-irregular-openings Shortcode

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

↑ Table of Contents

Troubleshooting / FAQ

Where can I set the standard date and time formats?

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 Is Open Widget / Shortcode does not work properly

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.

↑ Table of Contents

Contributing

Contribute to Code

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.

GitFlow

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.

Unit Testing

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).

Contribute to Translations

(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.

WordPress Polyglots

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.

  1. Select the translation set in the list of available languages.
  2. Scroll to the bottom.
  3. In the line below the legend, select all current as Machine Object Message (.mo) and click Export.
  4. Rename the file to wp-opening-hours-{locale}.mo (replace {locale} with the actual locale of the translation, e.g. de_DE for German).
  5. Move the file to /path/to/wordpress/wp-content/languages/plugins

Pull Request on GitHub

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

translate.jannikportz.de has been shut down in favor of WordPress Polyglots. Please refer to the section on WordPress Polyglots

↑ Table of Contents

Changelog

v2.1.3

  • Fix concerning time formats of Irregular Openings and Periods when saving by @Braunson

v2.1.2

  • Fixed JavaScript conflicts with other plugins

v2.1.1

  • 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.

v2.1

  • 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_next
    • op_is_open_format_today
    • op_overview_model
  • Various bug fixes

v2.0.5

  • fixed bug concerning child set initialization. thanks to @nikomuse

v2.0.4

  • Added support for UTC offset timezones

v2.0.3

  • Fixed timezone bug in WordPress 4.7

v2.0.2

  • Fixed a bug that didn't show next open Period when there are no regular Periods but Irregular Openings in the current Set

v2.0.1

  • Added SetAlias functionality
  • Minor fixes including:
    • Fixed mixed content error (@foomep)
    • Fixed auto convert issue
    • Fixed PHP 5.3 incompatibility issues

v2.0.0

Completely new Plugin. When Updating you will have to set up your Opening Hours and Widgets / Shortcodes again!

↑ Table of Contents

Donate

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:

GitCheese: gitcheese.com
flattr: Flattr this git repo
PayPal: Donate

License

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/.

↑ Table of Contents