You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+87-4Lines changed: 87 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@ You should now have all the plugin files under
22
22
23
23
/your/site/grav/user/plugins/static-social-embeds
24
24
25
-
> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav) and the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) to operate.
25
+
> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav), the [Error](https://github.com/getgrav/grav-plugin-error), [Problems](https://github.com/getgrav/grav-plugin-problems)and [Shortcode Core](https://github.com/getgrav/grav-plugin-shortcode-core) plugins to operate. Also, the [CURL PHP extension](https://secure.php.net/curl) must be enabled for this plugin to work.
26
26
27
27
### Admin Plugin
28
28
@@ -32,18 +32,101 @@ If you use the admin plugin, you can install directly through the admin plugin b
32
32
33
33
Before configuring this plugin, you should copy the `user/plugins/static-social-embeds/static-social-embeds.yaml` to `user/config/plugins/static-social-embeds.yaml` and only edit that copy.
34
34
35
-
Here is the default configuration and an explanation of available options:
35
+
Here is the default configuration and a short explanation of available options. Extensive explanations are available in the admin page of the plugin.
36
36
37
37
```yaml
38
38
enabled: true
39
+
40
+
# The plugin ships its own JS and CSS to run the static embeds.
41
+
# If you want to provide your own, feel free to disable them.
42
+
built_in_css: true
43
+
built_in_js: true
44
+
45
+
# The plugin can download images, videos, and GIFs, to ensure a
46
+
# complete independence from the social networks, at the cost of
47
+
# some disk space.
48
+
downloaded_content:
49
+
images: true
50
+
videos: true
51
+
52
+
# Options for Twitter: embed theme (with the default CSS, matches the
53
+
# light & dark Twitter themes) and API credentials required to load
54
+
# tweets (an explanation on how to create an application is available
55
+
# below).
56
+
twitter:
57
+
theme: light
58
+
consumer_key: null
59
+
consumer_secret: null
60
+
access_token: null
61
+
access_token_secret: null
62
+
63
+
# Options for Mastodon: embed theme (with the default CSS, matches the
64
+
# light & dark Mastodon themes).
65
+
mastodon:
66
+
theme: light
67
+
68
+
# Options for Instagram: embed theme (with the default CSS, the light theme
69
+
# matches Instagram, and the dark one was created from the light one and
70
+
# some inspiration from Twitter own dark theme).
71
+
instagram:
72
+
theme: light
39
73
```
40
74
75
+
Themes can be `light` or `dark` as for now and for the built-in CSS. If you want to add your own, themes only add a CSS class to the embeds containers: `sse-theme-[thetheme]` (e.g. `sse-theme-light` or `sse-theme-dark`); you can put anything there and reference it on your CSS file.
76
+
77
+
### Twitter setup
78
+
79
+
To use Twitter embeds, you'll need to register an application. This is done in a few simple steps.
80
+
81
+
1. Go to [the Twitter Apps page](https://apps.twitter.com/app/new) to create an application. You don't need to provide a callback URL (we never use that).
82
+
2. Then, click the **Keys and access tokens** tab and at the bottom of the page, click **Create my Access Token**.
83
+
3. Finally, copy the credentials in the configuration file (or in the admin).
84
+
41
85
Note that if you use the admin plugin, a file with your configuration, and named static-social-embeds.yaml will be saved in the `user/config/plugins/` folder once the configuration is saved in the admin.
42
86
87
+
### Customization
88
+
89
+
If you want to customize the embeds' HTML code, you can override the `partials/static-social-embeds` templates. The template name is the same as the shortcode name (see below), e.g. `toot.html.twig` for Mastodon embeds template. Templates context vary for different social networks; checkout built-in templates or shortcode classes to know which variables you can use.
90
+
43
91
## Usage
44
92
45
-
**Describe how to use the plugin.**
93
+
The plugin supports static embeds for Twitter, Mastodon and Instagram posts. It tries to match original embeds styles, so it's close to the real embeds, wut without any request to the social networks: independence!
94
+
95
+
Three shortcodes are declared to embed status: `tweet`, `toot` and `instagram`, for respectively Twitter, Mastodon and Instagram. They accept one parameter: the status URL to embed. Use them in your articles like this:
The following shortcodes will be rendered as below (for light and dark themes, with built-in CSS & JS).
106
+
107
+
108
+
109
+
Texts, images (single or multiples), videos (single or multiples), GIFs, are supported for all networks above. Mastodon toots supports CW and sensitive images.
110
+
111
+
Extensive caching is used to retrieve data and medias only once per embed. The first page load may be slow (especially if there are a lot of embeds in the page), but subsequent calls will be lightning-fast, as all data will be read from the cache, without any request to the social networks (no tracking, yay!). This also means that if an embed status is deleted, it will be kept on your site if the cache is not deleted. Custom locations are used for the cache files.
112
+
113
+
- Raw data is stored in `<root>/cache/static-social-embeds`. You can delete this folder at any time: embeds data will be retrieved from the social networks if not found in the cache.
114
+
- Images and videos are stored in `<root>/images/static-social-embeds`. You _should not_ delete this folder without deleting the above cache folder: if images are downloaded, links to images and videos references this medias cache folder. If you delete it, all images from existing embeds will be broken, except if you remove the data cache folder, as it will trigger a re-download of the medias (or references of CDN URLs if you disable the medias download).
115
+
116
+
The plugin is translated in English and French.
117
+
118
+
## Technical considerations regarding Instagram
119
+
120
+
While Twitter and Mastodon data are retrieved using their respective API, there is no way to do that with Instagram (or there is, but deprecated and soon-to-be-removed in december 2018). We scrap an internal JSON embed in the post pages to retrieve data (thanks to [RSSBridge](https://github.com/RSS-Bridge/rss-bridge/blob/master/bridges/InstagramBridge.php) for the tip). As it isn't official, it may break anytime.
121
+
122
+
Data is cached without expiration, so as long as you don't delete the cache, existing embeds will never break. New ones will. Feel free to open an issue if such problem occurs (but this is pretty stable for a few years now and I hope it will remains as such).
123
+
124
+
## Thanks
125
+
126
+
- Thanks to [`jedkirby/tweet-entity-linker`](https://github.com/jedkirby/tweet-entity-linker) used to parse tweets and add entities links (hashtags, mentions…) referenced in Twitter's JSON statuses.
46
127
47
128
## To Do
48
129
49
-
- [ ] Future plans, if any
130
+
- [ ] Support for Twitter pools.
131
+
- [ ] Support for Pleroma (should be simple as it's compatible with the Mastodon API) and maybe other networks (by request).
132
+
- [ ] Maybe option to proxy medias, allowing not to store them but still serve them from the website's domain.
0 commit comments