endpoint-share-api-polyfill
Version:
This is a polyfill for the `Web Share API` that can be used in desktop too, so your users can share in their twitter, facebook, messenger, linkedin, sms, e-mail, print, telegram or whatsapp.
1,713 lines (572 loc) • 29.1 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: ShareTarget</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Class: ShareTarget</h1>
<section>
<header>
<h2><span class="attribs"><span class="type-signature"></span></span>ShareTarget<span class="signature">(config)</span><span class="type-signature"></span></h2>
<div class="class-description">A class to allow custom share targets to the polyfill of navigator.share()
These just work off of opening constructed url in new tab for now
todo: file download/share suport
todo: refien options and enable custom options
todo: allow ShareTarget defaults</div>
</header>
<article>
<div class="container-overview">
<h2>Constructor</h2>
<h4 class="name" id="ShareTarget"><span class="type-signature"></span>new ShareTarget<span class="signature">(config)</span><span class="type-signature"></span></h4>
<div class="description">
https://web.dev/web-share-target/
Register a possible url if the one you want is not provided
url = origin + action + params.join('&'); I try to deal with the / and ? properly
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>config</code></td>
<td class="type">
</td>
<td class="description last">This is the config like in the manifest but with a few extra options
<h6>Properties</h6>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">the targetName can be used with shareTo</td>
</tr>
<tr>
<td class="name"><code>niceName</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
config.name
</td>
<td class="description last">UNOFFICIAL human frendly name for the UI</td>
</tr>
<tr>
<td class="name"><code>origin</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL this is the extra pesice of info not in the manifest that we need for a share_target</td>
</tr>
<tr>
<td class="name"><code>icon</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL IMPORTANT MUST HAVE class='the-icon' in svg tag; todo add suport for using manifest icons this is simply an svg pasted in</td>
</tr>
<tr>
<td class="name"><code>canShare</code></td>
<td class="type">
<span class="param-type">function</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">todo a function that takes (data, options) passed in to navigator.share and tells us if it can use this data. note the data is passed</td>
</tr>
<tr>
<td class="name"><code>share_target</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">the defonition of the share url and its required paramater
<h6>Properties</h6>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>action</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">The URI placed after the orgin ie '/share/</td>
</tr>
<tr>
<td class="name"><code>method</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"GET"
</td>
<td class="description last">the http methof for the fetch</td>
</tr>
<tr>
<td class="name"><code>enctype</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
"multipart/form-data"
</td>
<td class="description last">the encoding type to send https://web.dev/web-share-target/#accepting-files</td>
</tr>
<tr>
<td class="name"><code>params</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">Each parameter of {@see ShareTarget.share} can be mapped to a url search parameter of choice ie url: 'the_share_url' => /share?the_share_url=${url}
Theoretically you can add any arg you want but you must provide it when you call share(data) in case the user selects the target that needs it. you should make your target flexible to missing args
<h6>Properties</h6>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>title</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">the Header of the share link defaults to url if not provided</td>
</tr>
<tr>
<td class="name"><code>text</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">the main body of the share message defaults to title : desc if not provided</td>
</tr>
<tr>
<td class="name"><code>url</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">the url</td>
</tr>
<tr>
<td class="name"><code>files</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">todo files suport
<h6>Properties</h6>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>accept</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>desc</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="description last">UNOFFICIAL a description of what is being shared if text is provided and not desc text is used for desc
NOTE YOU CAN ONLY USE UNOFFICIAL PARAMS WITH sharePolyfill.share() not navigator.share = sharePolyfill.share if your app depends on these and you dont want to use native navigator.share ever</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td class="name"><code>image</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL an image url for the share card</td>
</tr>
<tr>
<td class="name"><code>app_id</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL an app id/ token</td>
</tr>
<tr>
<td class="name"><code>redirect</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL a redirect url for when the shareTarget is done</td>
</tr>
<tr>
<td class="name"><code>hashtags</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL a array of labels for use in twitter like hashtags</td>
</tr>
<tr>
<td class="name"><code>language</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
'en'
</td>
<td class="description last">UNOFFICIAL for defining the language the share_target should disply in</td>
</tr>
<tr>
<td class="name"><code>provider</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
window.location.host
</td>
<td class="description last">UNOFFICIAL</td>
</tr>
<tr>
<td class="name"><code>via</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
window.location.href
</td>
<td class="description last">UNOFFICIAL the referring host/ thing default to window.location.href</td>
</tr>
<tr>
<td class="name"><code>category</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL what category to submit this share into</td>
</tr>
<tr>
<td class="name"><code>payload</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">'title : url\n desc \n tags' this is a useful glob of the args for use in copy etc</td>
</tr>
<tr>
<td class="name"><code>user_id</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL the user id of the person sharing</td>
</tr>
<tr>
<td class="name"><code>phone_number</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL the phone numbers to share to if we know used for sms</td>
</tr>
<tr>
<td class="name"><code>email_address</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL the email address to share to (used for gmail/yahoo etc)</td>
</tr>
<tr>
<td class="name"><code>cc_email_address</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL bcc emails comma seperated usually used with email</td>
</tr>
<tr>
<td class="name"><code>bcc_email_address</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">UNOFFICIAL cc emails comma seperated usually used with email</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td class="name"><code>execute</code></td>
<td class="type">
<span class="param-type">function</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">If desired you may override the actual execute function all data will be passed just before execution for you to do with as you please</td>
</tr>
<tr>
<td class="name"><code>defaults</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
</td>
<td class="description last">this lets you set defult paramaters, this is recommended for all
unofficial paramaters needed as we should not asume the end user will pass them in.
For example we could pass in the app_id when registering so we do not have to pass it in every time we call navigator.share()</td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="share.js.html">share.js</a>, <a href="share.js.html#line67">line 67</a>
</li></ul></dd>
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>// 'telegram.me': 'https://t.me/share/url?url=' + url + '&text=' + text + '&to=' + phone_number,
sharePolyfill.registerShareTarget(new ShareTarget({
name: 'telegram',
niceName: "Telagram",
origin: 'https://t.me',
icon: '<svg class="the-icon" width="31" height="32" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><path fill="#0088cc" d="M248 8C111 8 0 119 0 256s111 248 248 248 248-111 248-248S385 8 248 8zm121.8 169.9l-40.7 191.8c-3 13.6-11.1 16.9-22.4 10.5l-62-45.7-29.9 28.8c-3.3 3.3-6.1 6.1-12.5 6.1l4.4-63.1 114.9-103.8c5-4.4-1.1-6.9-7.7-2.5l-142 89.4-61.2-19.1c-13.3-4.2-13.6-13.3 2.8-19.7l239.1-92.2c11.1-4 20.8 2.7 17.2 19.5z"></path></svg>',
share_target: {
action: 'share/url?',
method: 'get',
params: {
url: 'url',
text: 'text',
phone_number: 'phone_number',
// hash_tags: 'hashtags'
}
}
}))
sharePolyfill.re</code></pre>
</div>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="share"><span class="type-signature"></span>share<span class="signature">(data)</span><span class="type-signature"></span></h4>
<div class="description">
Execute a share action on this target this will perform the fetch in accordance to the config or simply execute the function forwarding data
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>data</code></td>
<td class="type">
</td>
<td class="description last">See constructor for template arg info</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="share.js.html">share.js</a>, <a href="share.js.html#line153">line 153</a>
</li></ul></dd>
</dl>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="SharePolyfill.html">SharePolyfill</a></li><li><a href="ShareTarget.html">ShareTarget</a></li></ul><h3>Global</h3><ul><li><a href="global.html#sharePolyfill">sharePolyfill</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.11</a> on Sun Oct 29 2023 07:27:00 GMT-0600 (Mountain Daylight Saving Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>