Skip to content

Commit cb1d033

Browse files
recritrecrit
committed
updated library section with examples
1 parent abdb0ff commit cb1d033

File tree

5 files changed

+181
-35
lines changed

5 files changed

+181
-35
lines changed

‎Makefile‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,18 @@
11
.PHONY: build
22
build:
3-
@rm docs/pattern_kit.md
4-
@echo "---" > docs/pattern_kit.md
5-
@echo "title: Pattern Kit" >> docs/pattern_kit.md
6-
@echo "---" >> docs/pattern_kit.md
7-
@echo "INFO - Downloading Pattern Kit README.md ..."
8-
@curl --progress-bar -L "https://raw.githubusercontent.com/PatternBuilder/pattern-kit/master/README.md" >> docs/pattern_kit.md
3+
@if [ -z $(pkit) ] || [ $(pkit) -eq 1 ]; \
4+
then \
5+
rm docs/pattern_kit.md; \
6+
echo "---" > docs/pattern_kit.md; \
7+
echo "title: Pattern Kit" >> docs/pattern_kit.md; \
8+
echo "---" >> docs/pattern_kit.md; \
9+
echo "INFO - Downloading Pattern Kit README.md ..."; \
10+
curl --progress-bar -L "https://raw.githubusercontent.com/PatternBuilder/pattern-kit/master/README.md" >> docs/pattern_kit.md; \
11+
fi
912
@mkdocs build --clean
1013

1114
.PHONY: deploy
1215
deploy:
1316
@read -p "This will deploy your current code to http://patternbuilder.github.io/. Press ENTER to continue..."
14-
@make build
17+
@make build pkit=1
1518
@mkdocs gh-deploy -b master

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@ For full documentation visit [mkdocs.org](http://mkdocs.org).
2424

2525
* Ensure mkdocs is installed. See above.
2626
* Checkout the latest *dev* branch.
27-
* From the commandline, run `make build`
28-
- Downloads the latest files - Example: Pattern Kit's README.md.
27+
* From the commandline, run `make build` or `make build pkit=0`
2928
- Builds the site at "./site"
29+
- If pkit is not provided OR pkit=1, then the latest Pattern Kit's README.md is downloaded to pattern_kit.md.
3030

3131
## Deploying the site
3232

‎docs/pattern_builder_importer.md‎

Lines changed: 19 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: Pattern Builder Schema Importer Drupal Module
44

55
## Pattern Builder Schema Importer Drupal Module
66

7-
### TL;DR
7+
### What is it?
88

99
It converts an library of JSON Schemas into Drupal paragraph bundles, and the JSON schema properties are converted into Drupal fields.
1010

@@ -73,78 +73,75 @@ The schema used by Pattern Builder is based on [JSON Schema](http://json-schema.
7373

7474
1. Hidden on the edit form
7575

76-
- Schema: `"options: { "hidden": true }`
7776
- Drupal configuration: Field instance setting.
77+
- Schema: `"options: { "hidden": true }`
7878

7979
1. Read-only on the edit form
8080

81-
- Schema: `"readonly": true `
8281
- Drupal configuration: Field instance setting.
82+
- Schema: `"readonly": true `
8383

8484
1. Non-imported properties:
8585

8686
If a property does not need to be imported as a Drupal field, then it can be flagged to not import it with:
8787

88-
- Schema: `"options: { "import": false }`
8988
- Drupal configuration: None
89+
- Schema: `"options: { "import": false }`
9090

9191
1. Textarea
9292

9393
Textareas are imported to a Drupal field type of "text_long". A schema property is consider to be a textarea if one of the following is true:
9494

95-
- Schema: `"format": "textarea"` OR `"format": "html"`
9695
- Drupal configuration: Field type.
96+
- Schema: `"format": "textarea"` OR `"format": "html"`
9797

9898
1. WYSIWYG / Filtered text
9999

100100
Filter text in Drupal provides the user with the Input Format selector. These commonly are configured to use a WYSIWYG editor.
101101
A schema property is determined to allow filtered text if the following is set:
102102

103-
- Schema: `"format": "html"`
104103
- Drupal configuration: Field instance setting.
104+
- Schema: `"format": "html"`
105105

106106
1. Collapsible Field Groups and Field Collections
107107

108108
The [field_group](https://www.drupal.org/project/field_group) module is required by the importer in order to provide basic single level grouping. The schema can control the collapsibility of a group of properties with the following:
109109

110+
- Drupal configuration: Field group setting, Field Collecton Fieldset widget.
110111
- Schema:
111112

112113
```
113-
"options": {
114-
"collapsed": true,
115-
"disable_collapse": false
116-
}
114+
"options": {
115+
"collapsed": true,
116+
"disable_collapse": false
117+
}
117118
```
118119
119-
- Drupal configuration: Field group setting, Field Collecton Fieldset widget.
120-
121120
1. Form Grid Layout
122121
123122
This provides the ability to display grid style form elements.
124123
125124
- Global config: "admin/config/content/patternbuilder"
126125
- Row class: The class for the row container in the grid layout.
127126
- Column class prefix: The number of columns will be appended to the column class prefix. Example: "grid-columns-" results in "grid-columns-4".
128-
127+
- Drupal configuration: Field instance setting.
129128
- Schema:
130129
131130
```
132-
"options": {
133-
"grid_columns": 2
134-
},
135-
"items": {
136-
"format": "grid"
137-
}
131+
"options": {
132+
"grid_columns": 2
133+
},
134+
"items": {
135+
"format": "grid"
136+
}
138137
```
139138
140-
- Drupal configuration: Field instance setting.
141-
142139
1. Paragraphs preview display view mode
143140
144141
The importer can automatically setup up the "Paragraphs Editor Preview" view mode if the property is configured as "preview". The importer has some default formatters for some common fields (text, image). Refer to the patternbuilder_importer.api.php for hooks that allow setting custom formatters for the preview view mode.
145142
146-
- Schema: `"options: { "preview": true }`
147143
- Drupal configuration: Field display view mode settings.
144+
- Schema: `"options: { "preview": true }`
148145
149146
150147
### Optional Drupal Extensions

‎docs/pattern_builder_library.md‎

Lines changed: 149 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,161 @@ title: Pattern Builder PHP Library
66

77
### What is it?
88

9+
1. TLDR; It lets you take data from anywhere and sets it up to work with Twig rendering.
910
1. The library is a Symfony based PHP library that contains classes for setting data in the appropriate object layout for consumption and rendering by the Twig layer.
10-
1. Less jargon version: It lets you take data from anywhere and sets it up to work with Twig rendering.
11+
1. The Drupal Pattern Builder module uses this library to render the patterns while using Drupal to store the user entered data.
1112

1213

1314
### Where
1415

1516
1. GitHub: [https://github.com/PatternBuilder/pattern-builder-lib-php](https://github.com/PatternBuilder/pattern-builder-lib-php)
1617

1718

18-
### How
19+
### Install
1920

20-
1. Tech setup: TODO
21+
- Add the **latest release** of Pattern Builder library to your composer.json: `"require": {"pattern-builder/pattern-builder": "v1.1.0"}`
22+
- Run `composer install`
23+
- Drupal:
24+
The Drupal [Pattern Builder module](https://www.drupal.org/project/patternbuilder) includes a composer.json with the library. The module is maintained to be compatible with library.
25+
26+
27+
### Rendering a Schema
28+
29+
The following details how to render an example JSON schema named "band".
30+
31+
The Drupal Pattern Builder module automatically does all this through Drupal field storage, field widgets, and field formatters.
32+
33+
#### Example JSON Schema: band
34+
35+
```javascript
36+
{
37+
"$schema": "http://json-schema.org/draft-04/schema#",
38+
"title": "Band",
39+
"description": "A Band pattern",
40+
"type": "object",
41+
"properties": {
42+
"name": {
43+
"type": "string",
44+
"enum": ["band"],
45+
"options": {
46+
"hidden": true
47+
}
48+
},
49+
"background": {
50+
"title": "Background Options",
51+
"type": "object",
52+
"format": "grid",
53+
"properties": {
54+
"color": {
55+
"type": "string",
56+
"enum": ["white", "gray", "black", "rich-black", "red", "transparent"]
57+
},
58+
"isFixed" :{
59+
"title": "Fixed Background Option",
60+
"type": "boolean",
61+
"default": true
62+
}
63+
}
64+
},
65+
"header": {
66+
"title": "Header",
67+
"type": "object",
68+
"format": "grid",
69+
"properties": {
70+
"theme": {
71+
"type": "string",
72+
"enum": ["light", "dark"],
73+
"default": "light"
74+
},
75+
"content": {
76+
"type": "array",
77+
"maxItems": 1,
78+
"items": {
79+
"title": "Header Item",
80+
"oneOf": [
81+
{"$ref": "band_header.json"}
82+
]
83+
}
84+
}
85+
}
86+
},
87+
"content": {
88+
"title": "Content Items",
89+
"type": "array",
90+
"minItems": 1,
91+
"items": {
92+
"oneOf": [
93+
{"$ref": "card.json"},
94+
]
95+
}
96+
}
97+
}
98+
}
99+
```
100+
101+
- - -
102+
103+
#### Create a Schema Factory
104+
105+
###### Drupal Pattern Builder Module
106+
107+
```php
108+
$schema_factory = patternbuilder_get();
109+
```
110+
111+
###### Standalone Library
112+
113+
```php
114+
// Twig setup.
115+
$twig_loader = new \Twig_Loader_Filesystem(array(
116+
'/path/to/my/templates',
117+
));
118+
$twig = new \Twig_Environment($twig_loader);
119+
120+
// Logger: MyLogger extends \Psr\Log\AbstractLogger
121+
$logger = new MyLogger();
122+
123+
// JSON Schema setup.
124+
$retriever = new \JsonSchema\Uri\UriRetriever();
125+
$resolver = new \JsonSchema\RefResolver($retriever);
126+
127+
// Pattern Builder.
128+
$configuration = new \PatternBuilder\Configuration\Configuration($logger, $twig, $resolver);
129+
$schema_factory = new \PatternBuilder\Schema\Schema($configuration);
130+
```
131+
132+
- - -
133+
134+
#### Set Schema Values
135+
136+
```php
137+
// Load the band header schema and set values.
138+
$band_header = $schema_factory->load('band_header')
139+
->set('title', 'My Awesome Band')
140+
->set('headline', 'New content, new markup, new everything!');
141+
142+
// Create a card schema and set values.
143+
$card = $schema_factory->load('card')
144+
->set('title', 'Card 1')
145+
->set('background', array('color' => 'white'))
146+
->set('image', array('src' => 'http://example.com/cool-image.jpg'));
147+
148+
// Load the band schema and set values.
149+
$band = $schema_factory->load('band')
150+
->set('background', array('color' => 'black'))
151+
->set('header', array(
152+
'theme' => 'dark',
153+
'content' => $band_header
154+
))
155+
->set('content', $card);
156+
```
157+
158+
- - -
159+
160+
#### Render the Schema
161+
162+
163+
```php
164+
// Render the entire band - all the nested schemas and their TWIG templates.
165+
$band_markup = $band->render();
166+
```

‎docs/using_pattern_builder.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ title: Using Pattern Builder
3232
1. Not good for complex field setups since hand mapping takes time and is error prone.
3333
1. How:
3434
1. Override the node view of a given content type.
35-
1. Use the existing Drupal fields to build the render object using the PatternBuilder Library.
35+
1. Use the existing Drupal fields to build the render object using the PatternBuilder Library. For more detail, see section ["PHP Library" > "Rendering a Schema"](pattern_builder_library.md#rendering-a-schema).
3636
1. Set the node view content as the rendered object.
3737

3838
3. (TODO) Component library only, No importer

0 commit comments

Comments
 (0)