Skip to content
Snippets Groups Projects
Commit f40f9360 authored by Mark Miller's avatar Mark Miller
Browse files

Issue #3196722: Update README before 1.x release

parent c8d89e67
No related branches found
No related tags found
No related merge requests found
......@@ -21,20 +21,17 @@ all the css, js, and template assets necessary for them to work, and using an
info.yml file to declare these components and their framework dependencies to
Drupal.
* For a full description of this module, visit the project page:
https://www.drupal.org/sandbox/mrjmd/2664138
### REQUIREMENTS
There are no special requirements at this time. In the future, we may abstract
some items to a component_api project.
There are no special requirements at this time.
### INSTALLATION
* Enable the module and at least one javascript framework sub-module (Angular 2
is the most fleshed out currently).
* Enable the module and at least one javascript framework sub-module. The Vue
submodule is currently the most actively developed and available here:
[Decoupled Blocks: Vue.js](https://www.drupal.org/project/pdb_vue).
* For Angular 2 use:
- Before enabling the Angular 2 sub-module you must navigate to the pdb_ng2
directory and run `npm install`.
......@@ -51,6 +48,97 @@ some items to a component_api project.
* Save your page and the decoupled component will appear!
#### Minimum configuration in component Yaml
```yaml
# Required.
name: My custom component
machine_name: my-custom-component
type: pdb
presentation: ng2 # Name of the submodule like ng2, react, vue, etc.
# Optional.
description: 'I describe the component'
category: 'NG2' # Category label that appears in block selection form.
version: '1.0.0' # By default, this is just for informational purposes.
```
#### Attaching JS and CSS via component Yaml
CSS Simplified format:
```yaml
add_css:
header:
component:
'component-name.css': {}
```
Extended format allowing dependencies on other libraries:
```yaml
add_css:
header:
css:
component:
'component-name.css': {}
dependencies:
- pdb/another-component/header
```
JavaScript Simplified format:
```yaml
add_js:
footer:
'component-name.js': {}
```
Extended format allowing dependencies on other libraries:
```yaml
add_js:
footer:
js:
'component-name.js': {}
dependencies:
- core/drupal.ajax
- pdb/another-component/footer
```
#### Block Form fields via component Yaml
Declare fields that site editors can fill out when placing a block. This data
will be automatically passed to the browser Window via
`drupalSettings.pdb.configuration` and keyed by the block's UUID.
```yaml
configuration:
example_field_name:
type: textfield
title: 'What do you want to say?'
default_value: 'Hello world!'
```
#### Entity Context via compenent Yaml
Components can use the context of the main page entity. This data will be
automatically passed to the browser Window via `drupalSettings.pdb.contexts`.
```yaml
contexts:
entity: node
# context_key: context_value
```
#### Changing Component directory
By default, components will be discovered inside modules and themes. You can
change this to scan other directories outside of modules and themes.
In the `settings.php` file you can define directory paths with the
`pdb_search_dirs` key. This can also be an array of paths.
```php
$settings['pdb_search_dirs'] = DRUPAL_ROOT . '/pdb_components';
```
### DEVELOPING FOR PDB
......@@ -59,11 +147,10 @@ some items to a component_api project.
- Writing components for existing frameworks should be straightforward, write
them as usual and add an info.yml file declaring them to the module. Some
framework implementations may provide extra tooling or require additional
boilerplate to use full functionality, see their individual README.txt
boilerplate to use full functionality, see their individual README.md
files for more information.
- When you find gaps in functionality you need, post them to the github issue
queue, as this module is still in early development stages.
- When you find gaps in functionality you need, post them to the issue queue.
* Writing your own framework definitions:
......@@ -86,20 +173,20 @@ some items to a component_api project.
builder to fill out. Configuration values are passed to the client via
drupalSettings.pdb.
- Use a JSON endpoint.
- Use a [JSON:API](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module)
endpoint.
- Use the GraphQL module.
- Use the [GraphQL module](https://www.drupal.org/project/graphql).
### MAINTAINERS
Author:
Original Author:
* Matt Davis (mrjmd) - (https://www.drupal.org/u/mrjmd)
<matt.davis at yourdrupaldev DOT com>
Current maintainers:
* Matt Davis (mrjmd) - (https://www.drupal.org/u/mrjmd)
<matt.davis at yourdrupaldev DOT com>
* Mark Miller (segovia94) - (https://www.drupal.org/u/segovia94)
* Emmanuel Cortes (emacoti) - (https://www.drupal.org/u/emacoti)
Early Contributors:
* Jason Smith
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment