Download the PHP package bedita/web-tools without Composer

BEdita/WebTools plugin for CakePHP web apps using BEdita API

Installation

First, if vendor directory has not been created, you have to install composer dependencies using:

You can install this plugin into your CakePHP application using composer.

The recommended way to install composer packages is:

Helpers

WebComponents

This helper provides some methods to setup Custom Elements with some app variables in order to initialize client side JavaScript components. It aims to avoid the generation of inline JS dictionaries or variables using declarative assignments to HTML nodes. String and numeric values are added as node attributes, while objects and arrays using inline scripts.

Example

Create a js file in the webroot/js which contains the Custom Element definition:

webroot/js/components/awesome-video.js

Now you can initialize the element in a twig template:

templates/Pages/document.twig

You can also extends native tags in order to setup simple interactions with the is method:

webroot/js/components/awesome-table.js

templates/Pages/users.twig

Load assets with AssetRevisions

AssetRevisions with the help of an asset strategy can easily resolve the common issue of loading built versioned assets as js and css.

Through \BEdita\WebTools\View\Helper\HtmlHelper you can transparently link built assets placed in a custom folder or raw assets living in webroot/js or webroot/css.

Define which strategy to use

The best place to define which strategy your app will use is the Application::bootstrap()

There are two assets strategies out of the box:

• EntrypointsStrategy based on the entrypoints.json file generated by Webpack Encore
• RevManifestStrategy based on rev-manifest.json file generated by gulp-rev

Anyway you are free to define your own strategy implementing AssetStrategyInterface.

Use HtmlHelper to load assets

Once a strategy is set you can link assets using \BEdita\WebTools\View\Helper\HtmlHelper and its methods script(), css() and assets(), for example:

The javascript app asset will be searched first from your asset strategy falling back to CakePHP HtmlHelper if strategy doesn't resolve the asset.

In this way you can continue to load assets as it was placed in common webroot/js or webroot/css and delegate to \BEdita\WebTools\View\Helper\HtmlHelper the task of resolve the link to them.

Identifiers

ApiIdentifier

ApiIdentifier is an identifier of Authentication plugin that helps to identify a user through the BEdita API.

In order to use the identifier you need to install and load Authentication plugin in the application bootstrap in Application.php

Install

then load in app

then add the AuthenticationMiddleware

and take advantage of getAuthenticationService() hook to set up the identifier.

Identity and Identity Helper

To use them ensure to install Authentication plugin

and load plugin $this->addPlugin('Authentication') in Application::bootstrap().

Then setup your application to use Identity, for example

Identity exposes a handy hasRole() method:

IdentityHelper allows to delegate configured methods to Identity, for example in a TwigView template

Request policy

Using the RequestPolicy class it is possible to setup the access to controller and actions by identity's roles or by custom policy rules.

First of all install Authorization plugin

and load plugin $this->addPlugin('Authorization') in Application::bootstrap().

Then proceed with setup the policy in Application class. Add the AuthorizationMiddleware and the RequestAuthorizationMiddleware

and configure the policy

OAuth2 setup

Quick steps to use the OAuth2 tools provided.

1. Create a route to a path like /ext/login/{provider} to interact with the selected OAuth2 provider in config/routes.php. Each {provider} must match a provider configuration key, for instance google in the configuration example below, see OAuth2 providers structure. An example here:

2. Define a controller for the above routing rule. A minimal version of the login action could include just a simple redirect like this example:

3. Setup OAuth2Authenticator and OAuth2Identifier classes in your main Application class and create the corresponding OAuth2Providers configuration. See the paragraphs below for more details.

4. Add the OAuth2Middleware in your middleware stack just after the AuthenticationMiddleware in Application::middleware(). like this:

OAuth2 providers

To use OAuth2Authenticator and OAuth2Identifier classes you must pass the supported OAuth2 providers configuration when loading this classes in the authentication service. Here a brief example of how to do this in Application::getAuthenticationService():

We are setting up the OAUth2 authenticator and identifier only when the request path matches our oauth2 login route as defined above.

It is recommended to use a configuration key like OAuth2Providers to store the provider information, anyway you must pass providers settings array using the providers key. Other possibile configuration are:

• (OAuth2Authenticator) 'redirect' - default ['_name' => 'login'], redirect url route specified as named array
• (OAuth2Identifier) autoSignup - default false, set to true if you want an automatic signup to be performed if login fails
• (OAuth2Identifier) 'signupRoles' - default [], user roles to use during the signup process, used only if autoSignup is true

OAuth2 providers structure

The providers configuration structure is in the following example. Here a single google provider is defined. Mandatory configuration keys are class, setup, options and map explained below. Each provider key must match the auth_provider name defined and configured in BEdita API.

For a brief OAuth2 providers reference have a look at the OAuth2 providers configuration wiki page