https://github.com/userfrosting/grav-plugin-uf-adapter
Adapter to allow you to use your UF templates, assets, and config variables in Grav.
https://github.com/userfrosting/grav-plugin-uf-adapter
Last synced: about 2 months ago
JSON representation
Adapter to allow you to use your UF templates, assets, and config variables in Grav.
- Host: GitHub
- URL: https://github.com/userfrosting/grav-plugin-uf-adapter
- Owner: userfrosting
- License: mit
- Created: 2017-03-09T21:40:39.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-08-04T17:00:10.000Z (almost 8 years ago)
- Last Synced: 2025-01-06T03:43:51.823Z (over 1 year ago)
- Language: PHP
- Size: 15.6 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Uf Adapter Plugin
This adapter allows you to use your UF templates, assets, and config variables in [Grav CMS](http://github.com/getgrav/grav). It is implemented as a Grav plugin.
You can add a Grav blog to your UserFrosting project by creating a `blog/` directory in your main UserFrosting project directory, and then installing Grav to `blog/`:
```bash
myUserFrostingProject/
├── app/
├── blog/
| └──
├── build/
├── licenses/
├── migrations/
├── public
└── webserver-configs/
```
When this plugin is installed to your Grav blog, it will add the following services to Grav's dependency injection container:
- `ufAssets` - UserFrosting's asset loader
- `ufConfig` - UserFrosting's `Config` object, which contains the [merged result of all config files](https://learn.userfrosting.com/sprinkles/contents#config) from your Sprinkles.
- `ufLocator` - `UniformResourceLocator` to help find and resolve resources in your Sprinkles.
The plugin will then use these services to do the following:
- Load UserFrosting templates from any Sprinkles declared in your `sprinkles.json`, into Grav's Twig view. By default, these will be loaded _before_ any and all Grav templates. Namespaced template paths for each Sprinkle will also be added (`userfrosting`, `userfrosting.core`, `userfrosting.account`, etc).
- Add the UserFrosting asset loader to Twig. Since Grav already has an `assets` Twig variable, UserFrosting's asset loader will be aliased as `ufAssets` in Twig.
- Merge UserFrosting's `site` config variable into Grav's `site` variable. Grav's site variables will be overwritten by any with the same name in UserFrosting's config.
## Installation
Installing the Uf Adapter plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
### GPM Installation (Preferred)
The simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's terminal (also called the command line). From the root of your Grav install type:
bin/gpm install uf-adapter
This will install the Uf Adapter plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/uf-adapter`.
### Manual Installation
To install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `uf-adapter`. You can find these files on [GitHub](https://github.com/alexander-weissman/grav-plugin-uf-adapter) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
You should now have all the plugin files under
/your/site/grav/user/plugins/uf-adapter
> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav) and the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) to operate.
## Configuration
Before configuring this plugin, you should copy the `user/plugins/uf-adapter/uf-adapter.yaml` to `user/config/plugins/uf-adapter.yaml` and only edit that copy.
Here is the default configuration and an explanation of available options:
```yaml
enabled: true
```
Next, you will need to set a `site.uri.main` variable in your **UserFrosting** configuration, so that Grav knows where the main site directory is located. This is important, because inside Grav, `site.uri.public` will end up pointing to **Grav**'s root url (which is not necessarily the same).
Finally, you will need to add the following dependencies to Grav's `composer.json` file:
```
"require": {
"userfrosting/assets": "^4.0.1",
"userfrosting/config": "^4.0.0",
"vlucas/phpdotenv": "^2"
},
"autoload": {
"files": [
"../app/defines.php",
"../app/helpers.php"
]
}
```
and then run `composer update` in the `blog/` directory. Unfortunately, this is the only way to add Composer dependencies to Grav at the moment.
## Usage
You should create a [Grav theme](https://learn.getgrav.org/themes/theme-basics) that extends the UserFrosting templates imported by this plugin. For example, you might create a theme that contains the following base template:
```
{% extends 'layouts/basic.html.twig' %}
{% block stylesheets_site %}
{{ ufAssets.css() | raw }}
{% endblock %}
{% block body_matter %}
{{ page.header.title }}
{{ page.content }}
{% endblock %}
{% block scripts_site %}
window.jQuery || document.write('<script src="{{ ufAssets.url('assets://vendor/jquery/dist/jquery.min.js', true) }}"><\/script>')
{{ ufAssets.js() | raw }}
{% endblock %}
```
As you can see, we've extended UserFrosting's core `layouts/basic.html.twig`, but we've overridden the `stylesheets_site` and `scripts_site` blocks to use the `ufAssets` asset manager variable. If we didn't do this, the references to `assets` in the base template would resolve to Grav's asset manager instead (which we might not want).
## To Do
- [ ] Figure out how to remove requirement for `site.uri.main` config variable
- [ ] Maybe alias Grav's asset manager, instead of our own?