This repository has been archived by the owner on Jan 4, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.html
183 lines (111 loc) · 11 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="utf-8"/>
</head>
<body>
<h1 id="scroll-to-anchor">Scroll-to-anchor</h1>
<h2 id="addanchorsanduseasmoothscrollinganimationforabetteruserexperience.">Add anchors and use a smooth scrolling animation for a better user experience.</h2>
<figure>
<img src="/assets/banner-1544x500.png" alt="Scroll-to-anchor" />
<figcaption>Scroll-to-anchor</figcaption>
</figure>
<h3 id="description">Description </h3>
<p>Are some of your readers impatient, want to skip long text and immediately jumpt to the summary? This plugin helps you to create anchors in your posts or pages and provides a smooth scrolling animation when the link to an anchor has been clicked.</p>
<p>For more convenience the plugin adds an anchor icon to the toolbar of the classic(1) visual editor for post and pages (and your own custom post types, if enabled in the settings). Adding a new anchor is no more than the click on that icon, after you marked a text passage or placed the cursor at the desired position of your text. A popup window will ask for a name of the anchor and then insert a shortcode into your text, which automatically gets replaced with the correct HTML in the frontend. (Need custom styling of the anchor? You may add individual CSS class names each time you insert a new anchor. If you don’t need that, just leave the field empty.)</p>
<p>Once an anchor has been added, you can link to it: Add and select text (e.g. “Jump to the summary”), click the link icon in the toolbar and enter the name of your anchor, preceded by a pound sign, e.g. <em>#summary</em>. That’s all.</p>
<p>Links may not contain spaces, but you can use them in your anchor names anyway. If you name your anchor e.g. <em>Summary Chapter Two</em>, you’ll see an information that the <em>link</em> to that anchor has been changed into e.g. <em>#summary-chapter-two</em>.</p>
<p>For a <strong>better user experience</strong>, a JavaScript function replaces the typical behaviour to directly jump to the anchor. Instead the visitor of your website sees a smooth scrolling animation. (If this is too fast/slow, you can change the speed under <strong>Settings > Reading</strong>.)</p>
<p>A couple of other settings provide just as much flexibility as you may need: If your website has a sticky header, you can set an offset for the scrolling animation. You can also choose if you want anchors to be displayed in the front end and set a descriptive expression to precede the anchor’s name.</p>
<p>Some users reported conflicts with other plugins, which (ab-)use anchor tags for various reasons. To avoid issues, this plugin already excludes Woocommerce Tabs and Bootstrap Accordions, but you <em>could</em> still run into issues with themes or plugins. To deal with this, you can add one or more CSS class names for sections, in which this plugin should be disabled. Although this is a little more complicated than I hoped for, it seems to be the best workaround. I’m happy to hear your thoughts, how this might even be improved in the future.</p>
<p>(1)<strong>Currently</strong> the plugin <strong>doesn’t support WordPress' new editor “Gutenberg”</strong>, but I hope to catch up soon and be able to extend the functionality of this little helper plugin.</p>
<p>I made this plugin because I love WordPress. Period. I won’t ask for donations, no upsell, no sketch of the team.
<strong>But I love to get your feedback to learn more.</strong></p>
<h3 id="installation">Installation </h3>
<p>You can install <strong>Scroll to Anchor</strong> automatically from the plugin directory, or by uploading the files manually to your server. After activating <strong>Scroll to Anchor</strong> you’ll be forwarded to the settings section at the bottom of the menu <strong>Settings > Reading</strong>.</p>
<p>To uninstall, just deactivate and delete the plugin. Remember to remove the shortcodes you may have added using the plugin.</p>
<h3 id="frequentlyaskedquestions">Frequently Asked Questions </h3>
<h4 id="q:whydontiseeanyadditonalsettingspage">Q: Why don’t I see any additonal settings page? </h4>
<p>To keep the plugin as unobstrusive as possible, I didn’t add yet another settings page. Instead I added a settings section at <strong>Settings > Reading</strong>.</p>
<h4 id="q:arethereanyrestrictionsforanchornames">Q: Are there any restrictions for anchor names? </h4>
<p>The plugin is disabled for anchors, if</p>
<ul>
<li>the anchor starts with <code>#respond</code> (usually comments),</li>
<li>the anchor starts with <code>#tab</code> and a body-class <code>.woocommerce</code> is provided (WooCommerce’s product tabs),</li>
<li>the anchor is within a section <code>.accordion</code></li>
<li>you set other classes to be excluded.</li>
</ul>
<h4 id="q:caniuseanchornameswithspacesandmixupper-lowercaseletters">Q: Can I use anchor names with spaces and mix upper-/lowercase letters? </h4>
<p>As links may not contain spaces, your anchor name will be sanitized and spaces replaced with hyphens. If you e.g. add an anchor and set it’s name as <em>Summary Chapter Two</em>, you’ll see a message that the link to this anchor should be #summary-chapter-two. Howevery, if you chose to display anchors in the front end, they will just show up as you named them, e.g. <em>Anchor: Summary Chapter Two</em>.</p>
<h4 id="q:icreatedacustomposttype.canigetthescrolltoanchoriconinthetoolbarwheneditingpostsofthatposttype">Q: I created a custom post type. Can I get the Scroll to Anchor icon in the toolbar when editing posts of that post type? </h4>
<p>Go to Settings > Reading and select the custom post types, where you want the icon to appear in the toolbar.</p>
<h4 id="q:canisimplyusealinkahreftopaattheendofmypage">Q: Can I simply use a link <code><a href="#">Top</a></code> at the end of my page? </h4>
<p>The link target <code>#</code> is often used as a placeholder and the typical functionality replaced by a JavaScript function. To avoid conflicts with such functions, Scroll to Anchor ignores links using the hash symbol only. If you want to provide a link to the top of your page, please use <code><a href="#top">Top</a></code> instead. (More Information (on MDN)[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href].)</p>
<h4 id="q:doesscrolltoanchorsupportwordpressneweditorgutenberg">Q: Does Scroll to Anchor support WordPress' new editor Gutenberg? </h4>
<p>Sorry, not yet. Stay tuned.</p>
<h3 id="screenshots">Screenshots </h3>
<figure>
<img src="https://github.com/pixolin/scroll-to-anchor/blob/master/assets/screenshot-1.png" alt="Settings > Reading" />
<figcaption>Settings > Reading</figcaption>
</figure>
<figure>
<img src="https://github.com/pixolin/scroll-to-anchor/blob/master/assets/screenshot-2.png" alt="Adding a new anchor" />
<figcaption>Adding a new anchor</figcaption>
</figure>
<figure>
<img src="https://github.com/pixolin/scroll-to-anchor/blob/master/assets/screenshot-3.png" alt="Creating link to anchor" />
<figcaption>Creating link to anchor</figcaption>
</figure>
<h3 id="changelog">Changelog </h3>
<h4 id="0.6.0">0.6.0 </h4>
<p>Fix: When a link with the anchor #top is clicked, Scroll to Anchor scrolls to the top of the page at the specified speed. The specified offset value is ignored.
License now GPLv2 <em>or later</em>. Thank you Udo Meisen for the talk about OpenSource Licensing.</p>
<h4 id="0.5.0">0.5.0 </h4>
<p>Adds new setting to select custom post types to show anchor icon in the toolbar.</p>
<h4 id="0.4.3.1">0.4.3.1 </h4>
<p>Fix: replaces incorrect sanitization in shortcode, which broke shortcodes with uppercase-letters. Also corrections in l18n and readme-file.</p>
<h4 id="0.4.3">0.4.3 </h4>
<p>Enhancement: TinyMCE modals now can be localized.
Fix:</p>
<ul>
<li>Anchor names now may contain spaces, uppper-/lowercase letters and even German umlauts. If you e.g. add an anchor “Großes Glück”, you will see a message that the anchor id was added as <code>#grosses-glueck</code> (but will display as <em>Anchor: Großes Glück</em> in the front end). This seems to be the best solution for SEO and should give you a little more flexibility naming your anchors.</li>
<li>Anchors may now encapsule content. However, if you want to use both, enclosing and not enclosing shortcodes <em>and</em> updated from a previous version, you need to add closing slashes to your previously existing, not enclosing anchors (e.g. <code>[sta_anchor id="top" /]</code>). If you just edit new pages, don’t worry.</li>
<li>You get a warning in the TinyMCE modal, if you left the field for the anchor name empty</li>
</ul>
<h4 id="0.4.2">0.4.2 </h4>
<p>Fix: Code Bug, optimizes SVG file. Thanks to Sergej Müller.</p>
<h4 id="0.4.1">0.4.1 </h4>
<p>Fix: error handling when variable $current[‘exceptions’] is empty.</p>
<h4 id="0.4.0">0.4.0 </h4>
<p>Enhancement: Adds settings field to exclude CSS classes and avoid conflitcs with animations by third party themes and plugins, e.g. for accordions or tabs. Bootstrap’s CSS class .accordion is excluded by default now.</p>
<h4 id="0.3.7">0.3.7 </h4>
<p>Customized JavaScript according to <a href="https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/">WordPress Coding Standards</a></p>
<h4 id="0.3.6">0.3.6 </h4>
<p>Improvements in the JavaScript. Special thanks to Felix Arntz (flixos90).</p>
<h4 id="0.3.5">0.3.5 </h4>
<p>Release date: April 8, 2016
Bug-Fix: added exception for Woocommerce Tabs
(thank you for feedback by francismacomber)</p>
<h4 id="0.3.4">0.3.4 </h4>
<p>Release date: March 26, 2016
Bug-Fix: Settings weren’t deleted from the database due to a wrong variable name.
Enhancement: Changes initial setting after installation to hide the anchor in the front end by default. Settings menu rearranged and with easier to understand descriptions.</p>
<h4 id="0.3.3">0.3.3 </h4>
<p>Release date: March 14, 2016
Bug-Fix: Replaces hook used to show settings link</p>
<h4 id="0.3.2">0.3.2 </h4>
<p>Release date: March 12, 2016
Enhancement: Menu plugins now shows link to settings section</p>
<h4 id="0.3.1">0.3.1 </h4>
<p>Release date: February 13, 2016
Enhancement: .pot-File for translation and German formal translation added.
Bug-Fixes: Some minor changes like removing unnecessary variables.</p>
<h4 id="0.3">0.3 </h4>
<p>Release date: February 12, 2016
Initial release.</p>
<hr />
<p>The banner for the WordPress Plugin Repository is based on the image <a href="http://www.photolib.noaa.gov/htmls/theb0139.htm">“Coast and Geodetic Survey Ship FATHOMER. In service 1905–1941.”</a> published in <strong>Public Domain</strong> by National Oceanic and Atmospheric Administration/Department of Commerce, USA. Photograph by C&GS Season’s Report Miller, 1911.</p>
<p>Text in the background is from the novel <em>Moby Dick</em> by Herman Melville, <strong>Public Domain</strong>.</p>
<p>And just in case you wonder about the maritime elements – this plugin is about <em>anchors</em>. :)</p>
</body>
</html>