tmdinosaurcenter
/
tainacan
mirror of https://github.com/tainacan/tainacan
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

More improvements on Extra View Modes documentation.

This commit is contained in:
Mateus Machado Luna 2019-01-10 09:35:58 -02:00
parent 06e5e6d39a
commit 8a57146fd5
2 changed files with 44 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
docs/extra-view-modes.md
View File

@ -9,7 +9,7 @@ Extra View Modes are a way of creating your own templates for items list visuali
- Thumbnails
- Slideshow
Each has it's specificities, but in case you're not satisfied with them, a developer can easily create a plugin to offer a custom way of displaying items list.
Each has it's specificities, but in case you're not satisfied with them, a developer can easily create a plugin to offer a custom template for displaying items list.
## Creating your extra view mode
@ -23,7 +23,7 @@ As shown in [our post for extra view modes](http://tainacan.org/2018/06/13/custo
As in any WordPress Plugin, you'll first need to create a php header as follows:
```
```php
<?php
/*
Plugin Name: Name of Your Extra View Mode Plugin
@ -31,7 +31,6 @@ Plugin URI: A URL for a related link
Description: An extra view modes plugin for Tainacan
Author: Your Name Here
Version: 0.1
Text Domain: tainacan-extra-viewmodes
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-3.0.html
*/
@ -39,7 +38,7 @@ License URI: http://www.gnu.org/licenses/gpl-3.0.html
defined( 'ABSPATH' ) or die( 'No script kiddies please!' );
```
Only Plugin Name is obligatory. Save the file with a name unique to your plugin, a good practice is to use the plugin name, such as `name-of-your-extra-view-mode-plugin.php`.
Only Plugin Name is obligatory. Save the file with a name unique to your plugin (a good practice is to use the plugin name, such as `name-of-your-extra-view-mode-plugin.php`).
The rest of the file will contain the register function for your view mode. We discuss it in details ahead:
@ -48,10 +47,10 @@ add_action( 'after_setup_theme', function() {
tainacan_register_view_mode('MyViewMode', [
'label' => 'My View Mode',
'description' => 'This is my view mode. It looks great the way it is.',
'icon' => '<span class="icon"><i class="mdi mdi-view-quilt mdi-24px"></i></span>',
'description' => 'This is my view mode. It looks great the way it is.',
'dynamic_metadata' => false,
'template' => __DIR__ . '/my-view-mode.php',
'template' => __DIR__ . './my-view-mode.php',
]);
} );
@ -59,30 +58,32 @@ add_action( 'after_setup_theme', function() {
?> /* End of file */
```
The function `tainacan_register_view_mode` is part of Tainacan's plugin. It's first paramether is a unique slug that will be used to identify your view-mode. Then follows an array of paramethers:
The function `tainacan_register_view_mode` is part of Tainacan's plugin. It's first paramether is a unique *slug* that will be used to identify your view mode. Then follows an array of paramethers:
| Type | Name | Description | Default |
|--------|------------------|-------------|-------------------------------------------|
| string | label | Label, visible to users. | Same of the variable $slug |
| string | label | Label, visible to users on the view modes dropdown. | Same of the variable $slug |
| string | icon | HTML that outputs an icon that represents the view mode. Visible to users on view modes dropdown. | None |
| string | description | Description, visible only to editors in the admin. | None |
| string | type | Type. Accepted values are 'template' or 'component'. | 'template' |
| string | template | Full path to the template file to be used. Required if $type is set to template. | 'theme-path/tainacan/view-mode-{$slug}.php' |
| string | template | Full path to the template file to be used. Required if $type is set to template. | 'theme-path/tainacan/view-mode-{$slug}.php' |
| string | component | Component tag name. The web component js must be included and must accept two props: 1) items: the list of items to be rendered ; 2) displayed-metadata: list of metadata to be displayed; | 'view-mode-{$slug}' |
| string | thumbnail | Full URL to an thumbnail that represents the view mode. Displayed only in Admin. | None |
| string | icon | HTML that outputs an icon that represents the view mode. | None |
| string | skeleton_template | HTML that outputs a preview of the items to be loaded, such as gray blocks, representing the items. | None |
| string | thumbnail | Full URL to a thumbnail that represents the view mode. Displayed only in Admin. | None |
| string | skeleton_template | HTML that outputs a preview of the items to be loaded, such as gray blocks, mimicking the shape of the items. | None |
| bool | show_pagination | Wether to display or not pagination controls. | true |
| bool | full-screen | Wether the view mode will display full screen or not. | false |
| bool | dynamic_metadata | Wether to display or not (and use or not) the "displayed metadata" selector. | false |
| bool | implements_skeleton | Wheter the view modes taks care of showing it's own Skeleton/Ghost css classes for loading items. | false |
| bool | implements_skeleton | Wheter the view modes takes care of showing it's own Skeleton/Ghost css classes for loading items. | false |
The *type* parameter is one of the most relevants here. When registering view modes, you can either create a simple PHP `template`, using WordPress functions, as the ones in our sample plugin, or more complex Vue.js `component`. When passing a template, the file path should be provided, while for components the name of previously loaded .vue component must be provided. Vue components must also have two props, one for receiving the items list as a parsed JSON Object and other for an array of metadata that will be displayed.
The `type` parameter is one of the most relevants here. When registering view modes, you can either create a simple PHP `template` using WordPress functions (as the ones in our sample plugin), or more complex Vue.js `component`. When passing a template, the file path should be provided, while for components the name of previously loaded .vue component must be provided. Vue components must also have two props, one for receiving the items list as a parsed JSON Object and other for an array of metadata that will be displayed.
View modes as Cards and Grid do not allow users to choose which metadata should be displayed, but rather decide that only certain will be visible. For this kind of view mode, it is used the *dynamic_metadata* parameter as `false`.
View modes as Cards and Grid do not allow users to choose which metadata should be displayed, but rather decide that only certain will be visible. For this kind of view mode, it is used the `dynamic_metadata` parameter as `false`.
## Making a Template extra view mode
By default a spinning circle loading animation is shown when items are being fetch. Most of our oficial view modes override this by implementing a so called skeleton/ghost list, that mimics a list of gray blocks in the shape of items before they arrived. If your view mode does that, you should set `implements_skeleton` to true and provide a HTML template with such skeleton to `skeleton_template`. Tainacan will take care of rendering this skeleton while items are being loaded.
The file indicated on the register above should point to the .php file where your template lives. It will probably have some structure similar to the following sample:
## Making an extra view mode template
The file path indicated on the register above should point to the .php file where your template lives. It will probably have some structure similar to the following sample:
```php
<?php if ( have_posts() ) : ?>
@ -91,25 +92,31 @@ The file indicated on the register above should point to the .php file where you
<?php while ( have_posts() ) : the_post(); ?>
<a class="my-view-mode-item" href="<?php the_permalink(); ?>">
<p class="my-view-mode-title">
<?php the_title(); ?>
</p>
<?php if ( has_post_thumbnail() ) : ?>
<div
style="background-image: url(<?php the_post_thumbnail_url( 'tainacan-medium' ) ?>)"
class="my-view-mode-thumbnail">
<?php the_post_thumbnail( 'tainacan-medium' ); ?>
<div class="skeleton"></div>
<a class="my-view-mode-item" href="<?php the_permalink(); ?>">
<div class="media">
<?php if ( tainacan_current_view_displays('thumbnail') ): ?>
<a href="<?php the_permalink(); ?>">
<?php if ( has_post_thumbnail() ): ?>
<?php the_post_thumbnail('tainacan-medium', array('class' => 'mr-4')); ?>
<?php else: ?>
<?php echo '<div class="mr-4"><img alt="Thumbnail placeholder" src="'.get_stylesheet_directory_uri().'/assets/images/thumbnail_placeholder.png"></div>'?>
<?php endif; ?>
</a>
<?php endif; ?>
<div class="list-metadata media-body">
<?php if ( tainacan_current_view_displays('title') ): ?>
<p class="metadata-title">
<a href="<?php the_permalink(); ?>">
<?php the_title(); ?>
</a>
</p>
<?php endif; ?>
<?php tainacan_the_metadata(array('metadata__in' => $view_mode_displayed_metadata['meta'], 'exclude_title' => true, 'before_title' => '<h3 class="metadata-label">', 'before_value' => '<p class="metadata-value">')); ?>
</div>
<?php else : ?>
<div
style="background-image: url(<?php echo get_template_directory_uri() . '/assets/images/thumbnail_placeholder.png'?>)"
class="grid-item-thumbnail">
<?php echo '<img alt="Thumbnail placeholder" src="' . get_template_directory_uri() . '/assets/images/thumbnail_placeholder.png">'?>
<div class="skeleton"></div>
</div>
<?php endif; ?>
</div>
</a>
<?php endwhile; ?>
@ -134,4 +141,4 @@ The file indicated on the register above should point to the .php file where you
<?php endif; ?>
```
The classes `my-view-mode-container`, `my-view-mode-item`, `my-view-mode-title`, `my-view-mode-thumbnail` and so forth should be implemented by you on your style file. Other classes as the `skeleton`, `section` are part of Tainacan's plugin CSS.
The classes `my-view-mode-container` and `my-view-mode-item`, and so forth should be implemented by you on your style file. Other classes as the `skeleton`, `section` are part of Tainacan's plugin CSS, and can be used if you wish to keep a standard.

1
src/admin/scss/_buttons.scss
View File

@ -8,6 +8,7 @@ button.link-style:active {
color: $secondary;
padding: 0;
margin: 0;
font-weight: normal;
background: transparent;
&:hover {