oh-opening-hours/oh-opening-hours

The "O/H - Opening Hours" WordPress plugin provides a range of customization options for displaying your business's operating hours with the use of Shortcodes and Widgets.

O/H - Opening Hours 🕐

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

Contents

• Features
• Installation
  • WordPress Plugin Installer
  • Manual Installation
  • Composer
  • Clone GitHub Repository
• Getting Started
  • Setting up your Opening Hours
  • Child Sets
• Widgets
  • Overview Widget
  • Is Open Widget
  • Holidays Widget
  • Irregular Openings Widget
  • Schema.org Widget
• Shortcodes
  • Shortcode Builder
  • Common Attributes
  • [op-overview] Shortcode
  • [op-is-open] Shortcode
  • [op-holidays] Shortcode
  • [op-irregular-openings] Shortcode
  • [op-schema] Shortcode
• Troubleshooting / FAQ
• Contributing
  • Contributing to Code
  • Contributing to Translations
• Changelog
• Credits
• License

Further Reading

• Schema.org Integration
• Developer Guide
• Filters
• Set Providers

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

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!

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

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.

↑ 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 in list view 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 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 list view 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 options Schema.org Widget 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. Schema.org Widget options ↑ Table of Contents Shortcodes About Shortcodes 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 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! Shortcode Builder 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. 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 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 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 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. %1$s A comma separated formatted string of todays holiday(s) 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 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: %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 op-schema Shortcode 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. ↑ 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. How can I change the styling of the widgets / shortcodes? 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. ↑ 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. ↑ Table of Contents Changelog v1.0.0 initial version fix security issues improvements ↑ Table of Contents Credits O/H - Opening Hours is based on the original plugin by Jannik Portz. 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