Adding Some Developper Docs

youknowriad · Apr 18, 2018 · 38b3765 · 38b3765
1 parent 9441615
commit 38b3765
Show file tree

Hide file tree

Showing 21 changed files with 431 additions and 0 deletions.
diff --git a/assets/logo.sketch b/assets/logo.sketch
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,22 @@
+# Gutenberg Custom Fields
+
+GCF or Gutenberg Custom Fields allows you to control the content of the Gutenberg edit screen by creating pre-filled templates.
+Navigate to the "GCF" admin page, create a new template, select a post type and add fields as you wish.
+The Gutenberg Editor will be pre-filled with the corresponding post type's template.
+
+## Features
+
+* Customize the title, the name of the post_meta key and the type of the field.
+* Several fields types available: Text, Textarea, Image, Number, Email, Repeater and more to come.
+* Based on Gutenberg Native Extensibility APIs (blocks and templates).
+* Templates Lock level.
+* Create custom field types
+* Add a Free HTML Area
+
+## Installation
+
+Grab it from [the WordPress Plugin Repository](https://wordpress.org/plugins/gutenberg-custom-fields/).
+
+## Demo
+
+[GCF Quick Start](intro.webm ":include :type=video controls width=100% height=400px")
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -0,0 +1,11 @@
+![logo](icon.svg)
+
+# GCF <small>1.5.1</small>
+
+> WordPress Custom Fields, the Gutenberg way.
+
+[GitHub](https://github.com/youknowriad/gcf)
+[Plugin](https://wordpress.org/plugins/gutenberg-custom-fields/)
+[Get Started](#gutenberg-custom-fields)
+
+![color](#f0f0f0)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,14 @@
+* [**Home**](/)
+* **Fields**
+  * [Text](fields/text.md)
+  * [Textarea](fields/textarea.md)
+  * [Number](fields/number.md)
+  * [Email](fields/email.md)
+  * [Image](fields/image.md)
+  * [Date](fields/date.md)
+  * [DateTime](fields/datetime.md)
+  * [Time](fields/time.md)
+  * [Free HTML Area](fields/free.md)
+  * [Repeater](fields/repeater.md)
+* [**Create custom GCF field types**](custom-fields.md)
+* [**Contribute**](contribute.md)
diff --git a/docs/contribute.md b/docs/contribute.md
@@ -0,0 +1,23 @@
+# Contribute
+
+## Getting Started
+
+GCF is a JavaScript-heavy plugin. The backend is only there to hook into WordPress's different API. The UI is entirely rendered in the client as a React application. The `config-app` script holds the React Application for the admin page area and the `fields` script is a generic script to retrieve, defined and extend field types.
+
+### Local Environment
+
+First, you need a WordPress Environment to run the plugin on, install the Gutenberg plugin from the WordPress plugin repository and then clone this repository right into your `wp-content/plugins` directory.
+
+Next, open a terminal (or if on Windows, a command prompt) and navigate to the repository you cloned. Now type `npm install` to get the dependencies all set up. Then you can type `npm run dev` in your terminal or command prompt to keep the plugin building in the background as you work on it.
+
+## Contribute to the Documentation
+
+Documentation is written in markdown and automatically generated from the [docs](https://github.com/youknowriad/gcf/tree/master/docs) folder.
+
+## Localizing Gutenberg Plugin
+
+To translate GCF in your locale or language, [select your locale here](https://translate.wordpress.org/projects/wp-plugins/gutenberg-custom-fields) and translate _Development_ (which contains the plugin's string) and/or _Development Readme_ (please translate what you see in the Details tab of the [plugin page](https://wordpress.org/plugins/gutenberg/)).
+
+A Global Translation Editor (GTE) or Project Translation Editor (PTE) with suitable rights will process your translations in due time.
+
+Language packs are automatically generated once 95% of the plugin's strings are translated and approved for a locale.
diff --git a/docs/custom-fields.md b/docs/custom-fields.md
@@ -0,0 +1,34 @@
+# Create custom GCF field types
+
+GCF allows you to register your own custom field types. Defining a field type means defining the `editForm` function of the field (and potentially a `configForm` as well): a higher order component used to edit the field's value.
+
+```js
+const myCustomFieldType = {
+  // Identifier of your field type, a good practice is use a namespace
+  name: "myplugin/field",
+
+  // Label of your field type
+  label: "My Custom Field Type",
+
+  // Function returning a Component used to edit the field value.
+  editForm: fieldConfig => ({ value, onChange }) => {
+    return (
+      <label>
+        {fieldConfig.title || fieldConfig.name}
+        <input
+          type="text"
+          value={value || ""}
+          onChange={event => {
+            onChange(event.target.value);
+          }}
+          placeholder="Write"
+        />
+      </label>
+    );
+  }
+};
+
+wp.data.dispatch("gcf/fields").register(myCustomFieldType);
+```
+
+Last thing, make sure your script registering your custom fields is loaded in Gutenberg before the editor initialization and in the GCF Admin page before the `gcf-config-app` script.
diff --git a/docs/fields/date.md b/docs/fields/date.md
@@ -0,0 +1,15 @@
+# Date
+
+**Type:** string
+
+This field allows users to specify a date using a date picker.
+The saved format is `YYYY-MM-DDTHH:ii:ss`.
+
+### Template usage
+
+```php
+<?php
+	$rawValue = get_post_meta( $post_id, $field_name );
+	echo date_i18n( get_option( 'date_format' ), strtotime( $rawValue ) );
+?>
+```
diff --git a/docs/fields/datetime.md b/docs/fields/datetime.md
@@ -0,0 +1,15 @@
+# DateTime
+
+**Type:** string
+
+This field allows users to specify a date using a date picker and hour/minutes inputs.
+The saved format is `YYYY-MM-DDTHH:ii:ss`.
+
+### Template usage
+
+```php
+<?php
+	$rawValue = get_post_meta( $post_id, $field_name );
+	echo date_i18n( get_option( 'date_format' ), strtotime( $rawValue ) );
+?>
+```
diff --git a/docs/fields/email.md b/docs/fields/email.md
@@ -0,0 +1,11 @@
+# Email
+
+**Type:** string
+
+This field creates an email input.
+
+### Template usage
+
+```php
+<?php echo get_post_meta( $post_id, $field_name ); ?>
+```
diff --git a/docs/fields/free.md b/docs/fields/free.md
@@ -0,0 +1,11 @@
+# Free HTML Area
+
+**Type:** string
+
+In some use cases, you want to use fields to add structured data to your CPT but at the same time, you want to allow random HTML to be saved as post content. The Free HTML Area is the field that allows you exactly that: It adds a container block saved to post content containing any HTML where you can use all Gutenberg defined blocks.
+
+### Template usage
+
+```php
+<?php echo get_the_content(); ?>
+```
diff --git a/docs/fields/image.md b/docs/fields/image.md
@@ -0,0 +1,11 @@
+# Image
+
+**Type:** string
+
+This field allows you to upload or select an image from the media library. The field stores the URL of the selected image.
+
+### Template usage
+
+```php
+<?php echo get_post_meta( $post_id, $field_name ); ?>
+```
diff --git a/docs/fields/number.md b/docs/fields/number.md
@@ -0,0 +1,11 @@
+# Number
+
+**Type:** number
+
+This field creates a numeric input.
+
+### Template usage
+
+```php
+<?php echo get_post_meta( $post_id, $field_name ); ?>
+```
diff --git a/docs/fields/repeater.md b/docs/fields/repeater.md
@@ -0,0 +1,17 @@
+# Repeater
+
+**Type:** string (JSON encoded array)
+
+This field is used to store a repeatable list of fields. All other field types can be added as sub fields (except the Free HTML Area).
+**Example:** For a CPT representing a person, you can use this field to store a list of addresses or phone numbers.
+
+### Template usage
+
+```php
+<?php
+	$my_list = json_decode( get_post_meta( $post_id, $field_name ), true );
+	foreach ( $my_list as $item ) {
+		echo $time['field1']; // field1 is the name of the subfields
+	}
+?>
+```
diff --git a/docs/fields/text.md b/docs/fields/text.md
@@ -0,0 +1,11 @@
+# Text
+
+**Type:** string
+
+This field creates a single-line text input.
+
+### Template usage
+
+```php
+<?php echo get_post_meta( $post_id, $field_name ); ?>
+```
diff --git a/docs/fields/textarea.md b/docs/fields/textarea.md
@@ -0,0 +1,11 @@
+# Textarea
+
+**Type:** string
+
+This field creates a multi-line text area.
+
+### Template usage
+
+```php
+<?php echo get_post_meta( $post_id, $field_name ); ?>
+```
diff --git a/docs/fields/time.md b/docs/fields/time.md
@@ -0,0 +1,15 @@
+# Time
+
+**Type:** string
+
+This field allows users to specify a time (hour and minutes).
+The saved format is `YYYY-MM-DDTHH:ii:ss`.
+
+### Template usage
+
+```php
+<?php
+	$rawValue = get_post_meta( $post_id, $field_name );
+	echo date( 'H:i', strtotime( $rawValue ) );
+?>
+```
diff --git a/docs/icon.svg b/docs/icon.svg
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,61 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>gutenberg-custom-fields</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
+  <style>
+    .edit-in-github {
+      float: right;
+      margin-top: 5px;
+    }
+
+    .edit-in-github a {
+      opacity: 0.3;
+      text-decoration: none;
+    }
+
+    .edit-in-github a:hover {
+      opacity: 1;
+    }
+  </style>
+</head>
+
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'GCF',
+      loadSidebar: true,
+      coverpage: true,
+      themeColor: '#2F71A5',
+      repo: 'https://github.com/youknowriad/gcf',
+      plugins: [
+        function (hook, vm) {
+          hook.beforeEach(function (html) {
+            var url = 'https://github.com/youknowriad/gcf/blob/master/docs/' + vm.route.file
+            var editHtml = '<div class="edit-in-github">[📝 Edit](' + url + ' )</div>\n'
+
+            return editHtml
+              + html
+          })
+        }
+      ]
+    }
+  </script>
+  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
+  <script src="https://unpkg.com/docsify-copy-code@2"></script>
+  <script src="//unpkg.com/prismjs/components/prism-php.min.js"></script>
+  <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
+  <script>
+    if (typeof navigator.serviceWorker !== 'undefined') {
+      navigator.serviceWorker.register('sw.js')
+    }
+  </script>
+</body>
+
+</html>
diff --git a/docs/intro.webm b/docs/intro.webm