Skip to content

Commit

Permalink
Updating documentation for WPooW library
Browse files Browse the repository at this point in the history
  • Loading branch information
chido committed Oct 27, 2018
1 parent 13f2a55 commit 79db233
Show file tree
Hide file tree
Showing 20 changed files with 128 additions and 123 deletions.
44 changes: 22 additions & 22 deletions docs/CustomElements-Create.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@ id: custom_elements-create
title: Creating Custom Element
---

Sometimes there are situation when you might need to create custom elements that utilise the wpOOW elements features. To
do this all you need to do is extend the wpOOW `BaseElement` class and override the methods
Sometimes there are situations when you might need to create custom elements that utilise the WPooW elements' features. To
do this all you need to do is extend the WPooW `BaseElement` class and override the methods

* ReadView
* EditView
* ProcessPostData

This method definitions of each of these methods are highlighted below
These methods are highlighted below in more detail:-

## Methods to Override

Expand All @@ -19,14 +19,14 @@ This method definitions of each of these methods are highlighted below
```yaml
Description:
Method called when rendering the ReadView of the element. This method should return a
html string. The curent value of the element can be accessed by using the
html string. The current value of the element can be accessed through the
GetDatabaseValue method (highlighted below)


Paramters:
Parameters:
$post:
Type: PostType
Description: The Post Type associate with the current element when being viewed
Description: The PostType associated with the current element when being viewed

Returns: String
```
Expand All @@ -43,17 +43,17 @@ This method definitions of each of these methods are highlighted below
```yaml
Description:
Method called when rendering the EditView of the element. This method should return
a html string, of which the html element must have a 'name' attribute for
its input type which is the same id of the element being render (i.e $this->id).
This is used to process data correct when a POST request is made.
a html string, of which this html string must have an input dom element with
a 'name' attribute that is the same as the id of the element being render (i.e $this->id).
This is used to process data correctly when a POST request is made (see example below)0.
Another important note it to call the parents EditView method, as this generates the
wp_nonce required for the elements input field.
Another important thing to note is to call the parents EditView method first, as this
generates the wp_nonce required for the elements input field.
The curent value of the element can also be accessed by using the GetDatabaseValue
The current value of the element can also be accessed by using the GetDatabaseValue
method.
Paramters:
Parameters:
$post:
Type: PostType
Description: The Post Type associate with the current element when being viewed
Expand All @@ -65,8 +65,7 @@ This method definitions of each of these methods are highlighted below
// Example
function EditView($post){
parent::EditView($post)
echo sprintf('<input type="text" id="%s" name="%s" value="%s"/>',
$this->id,
echo sprintf('<input type="text" name="%s" value="%s"/>',
$this->id,
$this->$this->GetDatabaseValue($post));
}
Expand All @@ -76,19 +75,20 @@ This method definitions of each of these methods are highlighted below

```yaml
Description:
This method is called when we about to save the data for the element. Override this
method to get the correct data to save through the 'SaveElementData' method (see below)
This method is called when saving the data for the element. Override this method
and call the 'SaveElementData' method after obtaining the appropriate data
for the element to persist the data (see example below).
Note - it is important to call the parent ProcessPostData method first before continuing
with operations as this ensure the data being returned has been santised
correctly (although you might still need to do again for your specific element
Note - it is important to call the parent's ProcessPostData method first before continuing
with operations as this ensures that the data being saved has been sanitised
correctly (although you might still need to do so again for your specific element
type)
Paramters:
Parameters:
$post:
Type: PostType ID
Description: The ID of the Post Type being saved
Description: The ID of the PostType being saved
Returns: String
```
Expand Down
22 changes: 11 additions & 11 deletions docs/CustomElements-FullExample.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
id: custom_elements-full_example
title: Full Example
---
Below is an example in which we replace the rating control with a slider
Below is an example in which we replace the rating text element in our example with a slider.

```php
class CustomRatingSelectorSimple extends BaseElement{
Expand Down Expand Up @@ -50,8 +50,8 @@ class CustomRatingSelectorSimple extends BaseElement{
}
```

As can be seen from the example above we are using jquery-ui slider component. This means we are going to have to download
these files and add the components folder. There is also a additional css file we will use to style our slider. The content
As can be seen from the example above we are using the jquery-ui slider component. This means we are going to have to download
these files and add them to the components folder. There is also an additional css file we will use to style our slider. The content
of that css file is below:-

```css
Expand All @@ -68,8 +68,8 @@ of that css file is below:-
}
```

As one would expect when using a jquery library, there is need to usually a need to initialize some javascript somewhere.
For this component we will need to initialize the javascript for both the read_view and edit_view. The javascript we use
As one would expect when using a jquery library, there is need to usually initialize some javascript somewhere.
For this component we will need to initialize the javascript for both the read_view and edit_view. The javascript we will use
is highlighted below:-

```js
Expand Down Expand Up @@ -101,7 +101,7 @@ is highlighted below:-
})();
```

Lastly we need to create our read_view and edit_view templates. This are highlighted below:-
Lastly we need to create our read_view and edit_view templates. These are highlighted below:-

```twig
<!-- Read View -->
Expand All @@ -120,8 +120,8 @@ Lastly we need to create our read_view and edit_view templates. This are highlig
```

And that's it! I added this at the root of my plugin, but you can theoretically add it anywhere, resulting in a file
structure as follows:-
And that's it! I added this at the root of my plugin (but you can theoretically add it anywhere) resulting in a file
structure that looks like this:-

```bash
wpoowbookreviewer
Expand All @@ -139,8 +139,8 @@ wpoowbookreviewer
└── wpoowbookreviewer.php
```

All we need to do now is use our custom component in creating a post type. To do this we replace the `_myRating` element
creation with our new component, after including it.
All we need to do now is use our custom component in creating our PostType. To do this we replace the `_myRating` element
creation with our new component (after including it).

```php

Expand All @@ -155,7 +155,7 @@ function CreateBookReviewPostType(){

```

The final element looks something like this
The final element looks something like this:-

| Edit View | Read View |
| ------------- | ------------- |
Expand Down
46 changes: 24 additions & 22 deletions docs/CustomElements-UsingJavascript.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,15 @@
id: custom_elements-using_javascript
title: Using Javascript (and CSS)
---
Sometimes you need to create elements that use javascript. Such is the case if you are using some compound/interactive
Sometimes you need to create elements that use javascript. For example if you are creating some compound/interactive
UI element. When your element uses javascript you need to use the `EnqueueElementBaseScript` and the `EnqueueElementScript`
methods to enqueue the appropriate scripts.
methods to enqueue your scripts appropriately.

The `EnqueueElementBaseScript` method is used to enqueue scripts that will be used by all instance of your element
type (more like a shared library). **Note:-** This method should only be used in the `BaseScriptsToLoad` method, which
you will have to overwrite from the BaseElements class. If you don't you will get a `doing_it_wrong` WordPress error. And example of this is
The `EnqueueElementBaseScript` method is used to enqueue scripts that will be used by all instances of your element
type (more like a shared library).

**Note:-** This method should only be used in the `BaseScriptsToLoad` method, which
you will have to overwrite from the BaseElements class. If you don't you will get a `doing_it_wrong` WordPress error. An example of this is
below:-

```php
Expand All @@ -24,7 +26,7 @@ The `EnqueueElementBaseScript` method is used to enqueue scripts that will be us
```

`EnqueueElementScript` is used to enqueue javascript for a particular instance of your custom element type, for
instance if you will require to bind to your custom element id. This method should be used with the `ReadView` method
instance if you require some javascript to use the id of your custom element. This method should be used within the `ReadView` method
or the `EditView` method.


Expand All @@ -43,25 +45,25 @@ The `EnqueueElementBaseScript` method is used to enqueue scripts that will be us

**Important Notes:-**

* When you custom element use javascript to get the parsed value, you should set this value to a hidden input field
in you read/edit view that has the name set to you element id. This will allow wpOOW to pick up the value correctly
when a post is made
* All javascript that are enqueued using the the `EnqueueElementBaseScript` or `EnqueueElementScript` go through the
* When your custom element uses javascript to get the parsed value (user inputted value, that might be processed), you should set this value to a hidden input field
in your read/edit view that has the name set to your element's id. This will allow WPooW to pick up the value correctly
when a post is made (see [Full Example below](/docs/custom_elements-full_example.html))
* All javascript files that are enqueued using the the `EnqueueElementBaseScript` or `EnqueueElementScript` go through the
twig template engine. This means you can use twig template placeholders in your javascript. This is useful for passing
value from you code
values from your code.

## JS enqueuing methods

```php

/**
* Used to add base script for the element. This script will be shared by all instances for this type.
* Only call this withing the BaseScriptsToLoad method as you will get `doing_it_wrong` word press error
* Used to add base scripts for the element. This script should be shared by all instances of this type.
* Only call this method within the BaseScriptsToLoad method else you will get a `doing_it_wrong` WordPress error
*
* @param $handle - name used by WordPress to recognise this script
* @param $src - location of the file
* @param array $shared_variable - dictionary of variable to use in your javascript file using twig templating placeholders
* @param array $deps - javascript dependancies
* @param array $shared_variable - dictionary of variable to use in your javascript file when replacing the twig templating placeholders
* @param array $deps - javascript dependencies
* @param bool $ver - file version, for browser caching
* @param bool $in_footer - add to the footer or header of html
*/
Expand All @@ -72,11 +74,11 @@ protected function EnqueueElementBaseScript($handle, $src, $shared_variable = []

```php
/**
* Used to and a instance specific script. The script will be added for each instance of the element.
* Also not this script will be added inline
* Used to add a instance specific script. The script will be added for each instance of the element.
* Also note, this script will be added inline
*
* @param $src_path - location of the file
* @param array $shared_variables - dictionary of variable to use in your javascript file using twig templating placeholders
* @param array $shared_variables - dictionary of variable to use in your javascript file when replacing the twig templating placeholders
* @param null $handler - name used by WordPress to recognise this script
*/
protected function EnqueueElementScript($src, $shared_variables= [], $handler=null)
Expand All @@ -85,7 +87,7 @@ protected function EnqueueElementScript($src, $shared_variables= [], $handler=nu
# Using CSS in your custom element

Similarly to enqueuing a javascript file for your element you can also enqueue a css file. The process is exactly
this same as that of enqueuing a javascript, with the caveat that you use the `EnqueueElementBaseCSS` method instead.
this same as that of enqueuing a javascript file, with the caveat that you use the `EnqueueElementBaseCSS` method instead.
Similar to the EnqueueElementBaseScript method you should only call this method within the `BaseScriptsToLoad` method.

```php
Expand All @@ -104,12 +106,12 @@ function BaseScriptsToLoad()
```php

/**
* Used to add base css for the element. The css will be shared by all instances for this type.
* Only call this withing the BaseScriptsToLoad method as you will get `doing_it_wrong` word press error
* Used to add base css for the element. The css should be shared by all instances of this type.
* Only call this within the BaseScriptsToLoad method else you will get `doing_it_wrong` word press error
*
* @param $handle - name used by WordPress to recognise this script
* @param $src - location of the file
* @param array $deps - css dependancies
* @param array $deps - css dependencies
* @param bool $ver - file version, for browser caching
* @param string $media - what type of media it applies too
*/
Expand Down
8 changes: 4 additions & 4 deletions docs/CustomElements-UsingTwig.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@
id: custom_elements-using_twig
title: Using Twig for templating
---
For more complex elements you might might want to use a template. wpOOW comes embedded with the [twig](https://twig.symfony.com/) template
For more complex elements you might want to use a html template. WPooW comes embedded with the [twig](https://twig.symfony.com/) template
engine (which is used to render the predefined elements). The template engine can also be used to render your
custom elements.

Using the examples above we could the change the `ReadView` and the `EditView` to the following
Using the examples above we could the change the `ReadView` and the `EditView` to the following:-

```php
// Example
Expand All @@ -29,5 +29,5 @@ function EditView( $post)
```

In the examples above we are saying use the template `read_view.twig` / `edit_view.twig` to render this elements
with the parameter value...etc. The location of the template files should relative to the php file of your
custom element
with the parameters value...etc. The location of the template files is relative to the php file of your
custom element (unless in the construction of the element you specify a different elementPath See [Elements Overview Above](/docs/elements-introduction.html))
14 changes: 7 additions & 7 deletions docs/DataAccess-PostType.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ foreach ($bookReviews->Query()->Select()->Fetch() as $book)
Description:
Used to specify the columns you want returned. Returns all columns if nothing is specified

Paramters:
$colums:
Parameters:
$column:
Type: array
Description: Array of PostType field/column names to return

Expand All @@ -34,19 +34,19 @@ foreach ($bookReviews->Query()->Select()->Fetch() as $book)
```yaml
Description:
Used to specify field to order by
Used to specify the field to order by

Paramters:
Parameters:
$fieldname:
Type: string
Decription: PostType field name you want to order by
Description: PostType field name you want to order by
$asc_desc:
Type: string
Description: ASC for ascending order based on the fieldname and DESC for descending
order based on the fieldname
$fieldname:
Type: boolean
Description: if you want to treat the value from the colum as a number when ordering,
Description: if you want to treat the value from the column as a number when ordering,
else treat as a string

Returns: WPooWQueryObject
Expand All @@ -56,7 +56,7 @@ foreach ($bookReviews->Query()->Select()->Fetch() as $book)
```yaml
Description:
Excutes the generated wp_query and yeilds the result
Executes the generated wp_query and yields the result

Returns: Generator
```
6 changes: 3 additions & 3 deletions docs/DataAccess.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ id: da-introduction
title: Overview
---

In WordPress the are ways to access/manipulate the data saved in the database. These methods can be used to access the data
saved by the declared WPooW PageTypes'. The WPooW library does however have wrapper class for this which you can use with declared PageTypes. This making
it easier to access data saved through a declared WPooW PageTypes.
In WordPress they are ways to access/manipulate the data saved in your database. These methods can be used to access the data
saved by the declared WPooW PageTypes'. The WPooW library does however provide wrapper methods you can use with your declared PageTypes to access the data, making
it easier to access the data saved through a declared WPooW PageType.
4 changes: 2 additions & 2 deletions docs/Elements-Checkbox.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ id: elements-checkbox
title: Checkbox
---

Checkbox element for boolean items
Checkbox element for boolean items.

| Read View | Edit View |
| ------------- | ------------- |
Expand All @@ -16,7 +16,7 @@ Constructor
* @param $id
* @param string $label - the label of the element
* @param array $permissions - View, edit, read rights of the elemenet.
See wpOOWPermissions in the Overview section.
See WpooWPermissions in the Overview section.
*
**/

Expand Down
8 changes: 4 additions & 4 deletions docs/Elements-Date.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ id: elements-date
title: Date
---

Date element for date values. The used the browsers standard datetime picker, hence will appear
Date element for date values. This uses the browser's standard datetime picker, hence will appear
slightly different on each browser.

| Read View | Edit View |
Expand All @@ -17,7 +17,7 @@ Constructor
* @param $id
* @param string $label - the label of the element
* @param array $permissions - View, edit, read rights of the elemenet.
See wpOOWPermissions in the Overview section.
See WpooWPermissions in the Overview section.
*
**/

Expand All @@ -43,5 +43,5 @@ foreach ($bookReviewPostType->Query()->Select()->Fetch() as $row)
}
```

**Note:-** for the wpOOW Datetime element we declare it using the class `wpAPIDateTime`. This is because php already has
it own `DateTime` class, which would result in a conflict between the two.
**Note:-** for the WPooW Datetime element we declare it using the class `wpAPIDateTime`. This is because php already has
it's own `DateTime` class, which would result in a conflict between the two.
Loading

0 comments on commit 79db233

Please sign in to comment.