Download the PHP package liturgical-calendar/components without Composer

On this page you can find all versions of the php package liturgical-calendar/components. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package components

CodeFactor php version Packagist Packagist stats

Stato traduzione ApiOptions

Stato traduzione WebCalendar

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. 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). It also requires PHP ext-intl. To check if you have all the requirements you can run composer check-platform-reqs --no-dev. If you intend on contributing to the repository and installing development requirements, you should run composer check-platform-reqs.

CalendarSelect

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

[!CAUTION] When setOptions is set to OptionsType::DIOCESES_FOR_NATION, the nationFilter option MUST also be set, otherwise an exception will occur.

To produce the \<select> element, call the ->getSelect() method on the CalendarSelect instance.

Example:

The options can also be set by using the methods of the same name after instantiating the CalendarSelect instance, rather than passing them into the constructor. These methods allow for chaining.

Example:

[!CAUTION] When using the ->setOptions() method with a value of OptionsType::DIOCESES_FOR_NATION, the ->nationFilter() method MUST be called BEFORE calling the ->setOptions() method, otherwise an exception will occur.

ApiOptions

Produces a number of html \<select> elements, with \<option>s 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 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.

[!NOTE] Other than setting the as html element as a string value in the wrapper option, or enabling the wrapper with a boolean value, we can also set wrapper to an associative array with the desired options. The following three examples are equivalent:

[!NOTE] Other than setting the as html element as a string value in the formLabel option, or enabling the formLabel with a boolean value, we can also set formLabel to an associative array with the desired options. The following three examples are equivalent:

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:

Each of these has it's own ->class(), ->id(), ->labelClass(), ->wrapper(), ->wrapperClass(), ->disabled() and ->selectedValue() 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:

Updating the options for the Locale input

The default options for the Locale \<select> input are the locales supported by the API for the General Roman Calendar. However, national calendars and diocesan calendars have their own set of supported locales. In order to set the options to those supported by a given national or diocesan calendar, we can use the ->setOptionsForCalendar(string $category, string $calendar_id) method, where $category has a value of either nation or diocese, and $calendar_id corresponds to the calendar_id property of the national or diocesan calendar.

Example:

We can then set the default selected value for the localeInput based on the calendar response, using the settings->locale property from the calendar response:

Disabling inputs and setting default selected values

We can set the default selected value on the inputs as well as disable them. For example, after requesting a national or diocesan calendar, we might want to disable the ApiOptions inputs seeing that can't send any other value than those that are determined by the requested calendar. And we might want to set their default selected options to those of the requested calendar.

If no national or diocesan calendar was requested, but only the General Roman Calendar, then the inputs won't be disabled, their default selected values however will be set to those that were requested for the Calendar instance.

WebCalendar

A WebCalendar is instantiated with a response object from the Liturgical Calendar API. It does not currently take care of making the request, the request must first be sent to the API and the response must be transformed into an object, and passed in to the WebCalendar constructor.

CSS classes

Most of the table styling should be handled with CSS styling rules.

To this end, a number of CSS classes are created by default in the resulting table.

[!NOTE] The WebCalendar component currently suppresses the grade_display for celebrations of rank 7, since it is more explanatory than actually useful for display in a web calendar, having a value along the lines of 'celebration with precedence over solemnities'.

Chainable methods

The WebCalendar instance also has a number of methods that allow to further adjust and customize the layout of the calendar. These methods allow for chaining, making it easy to call them one after the other:

Non chainable methods

There a few methods that return a value, and therefore do not allow for chaining, because they do not return the instance but rather a value.

Examples

An examples folder has been included in the repo to allow for easy testing. Currently there is a /webcalendar subfolder with an example of usage of the WebCalendar component. To quickly test locally, cd into the /webcalendar subfolder and run php -S localhost:3000, then open your browser at http://localhost:3000. You should see a form with ApiOptions and CalendarSelect. Click on Submit to see the actual web calendar.

Note that this will use the default remote API. If you would like to test against a local instance of the API, first make sure that you have installed the development requirements with composer install (whereas composer install --no-dev would install without development requirements). With development requirements in place, copy /examples/webcalendar/.env.example to /examples/webcalendar/.env.development, and set the value of API_PORT to the port of your local API instance. If you are spawning an instance of the API on port 8000, then set API_PORT to 8000. As long as APP_ENV is set to development, the /examples/webcalendar example will use your local API instance instead of the remote production API. For more information on spawning a local instance of the API, see the Liturgical Calendar API Readme - testing locally.

Tests

The package includes a few unit tests to ensure that the component is working as expected. In order to run the tests, clone the package repository locally and install 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.

Translations

The few translatable strings in the component are handled via weblate. Click on the following badges to contribute to the translations.

ApiOptions translations

Stato traduzione

Stato traduzione

WebCalendar translations

Stato traduzione

Stato traduzione


All versions of components with dependencies

PHP Build Version
Package Version
Requires php Version >=8.1
ext-intl Version *
ext-json Version *
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package liturgical-calendar/components contains the following files

Loading the files please wait ....