Download the PHP package liturgical-calendar/components without Composer

Liturgical Calendar Components for PHP

A collection of reusable frontend components, that work with the Liturgical Calendar API (currently hosted at https://litcal.johnromanodorazio.com/api/dev/).

Installing the package

Installing the package in your project is as simple as composer require liturgical-calendar/components. To install without dev dependencies, after we have composer requireed the package: composer install --no-dev.

Include in your project's PHP script with include_once 'vendor/autoload.php'; (adjust the path to vendor/autoload.php accordingly).

Note that this package requires PHP >= 8.1, seeing it makes use of Enums (which were introduced in PHP 8.1).

CalendarSelect

Produces an html \<select> element the options of which are populated with data from the Liturgical Calendar API /calendars route. Can be instantiated with an array of options with the following keys:

• url: The URL of the liturgical calendar metadata API endpoint. Defaults to https://litcal.johnromanodorazio.com/api/dev/calendars.
• locale: The locale to use for the calendar select. Defaults to 'en'. This is the locale that will be used to translate and order the names of the countries. This should be a valid PHP locale string, such as 'en' or 'es' or 'en_US' or 'es_ES'.

To produce the \<select> element, call the ->getSelect() method on the CalendarSelect instance. You may optionally pass in an array of options that can have the following keys:

• class: The class or classes to apply to the select element, default calendarSelect.
• id: The id to apply to the select element, default calendarSelect.
• options: The type of select options to return. Valid values are 'nations', 'diocesesGrouped', or 'all', default all.
• label: A boolean indicating whether to include a label element or not, default false.
• labelStr: The string to use for the label element, default "Select a calendar".

Example:

ApiOptions

Produces a number of html \<select> elements, with options that correspond to the values of parameters that can be sent in a request to the Liturgical Calendar API /calendar route. The only \<select> element with options that are populated from the Liturgical API /calendars route is that of the locale parameter, with current supported language locales.

To produce the \<select> elements, call the ->getForm() method on the ApiOptions instance. Here is an example of the most basic usage:

Output:

Differentiate parameters according to API path

The \<select> elements that are output can be differentiated between those that correspond to parameters that can be sent on any path of the /calendar/* route (therefore for any Liturgical Calendar requested whether General Roman, national or diocesan), and those that only make sense on the base /calendar route (therefore only for the General Roman calendar). To differentiate the output, pass in the PathType enum with one of the two possible enum values:

The output will be similar to the previous output, with a <br> separating the year_type and accept header \<select> elements from the other \<select> elements.

Set locale for language names and display values

We can change the locale for the ApiOptions component, which will affect:

• the locale select element, so that the language names in the select options are output according to the set locale
• the display values of the eternal_high_priest select element (since the final value is a boolean, the display values are simply text representations of boolean values, and not the actual value that is sent in an API request)
• the display values of the epiphany select element (which are descriptive to make them more comprehensible)

The locale select will now look like this:

Set a wrapper and a label

We can optionally set a \<form> or \<div> wrapper around the whole of the output, and we can also set the class and id of the wrapper element, and we can also set a label for the form (which will be included within the wrapper element):

Set a common wrapper element for each of the form select inputs

The ApiOptions component allows for fine grained control via a number of methods.

For example we can set a common wrapper element that will be wrapped around each of the form select elements, via the Input::setGlobalWrapper() and Input::setGlobalWrapperClass() methods. We can also set a common class to be used on all of the form select elements, via the Input::setGlobalInputClass() method.

Output:

Fine grain control of single form select inputs

Usually we would want to have the same wrapper and wrapper classes and select element classes on all of the form select inputs. However, if we do need for any reason to have finer grained control on a specific select element, say for example we would like to set an id attribute on a specific select element, we can do so by targeting the relative input. The select inputs are available on the ApiOptions instance as the following properties:

• epiphanyInput
• ascensionInput
• corpusChristiInput
• eternalHighPriestInput
• yearTypeInput
• localeInput
• acceptHeaderInput

Each of these has it's own ->class(), ->id(), ->labelClass(), ->wrapper(), and ->wrapperClass() methods. If a global input wrapper or input class is also set, the single input's fine-grained methods will override the global settings for the specific input instance.

Output:

Tests

The package includes a few unit tests to ensure that the component is working as expected. In order to run the tests, install the package with the dev dependencies:

Then run the composer test script, which calls the included PHPUnit package to run the tests in the tests folder.

To run a single test class or a single method within a class, use the composer test-filter script followed by the desired Class or Class::method, e.g. composer test-filter CalendarSelectTest::testIsValidLocale.