documentation/tutorial-url.html

Summary

Maintainability
Test Coverage
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Tutorial: URL Query String - Documentation</title>

    <script src="scripts/prettify/prettify.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">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-miew.css">
</head>

<body>

<div id="main">
    <h1 class="page-title">Tutorial: URL Query String</h1>

    <section>

<header>
    <h2>URL Query String</h2>

    
</header>

<article>
    <h1>URL Query String</h1>
<h2>Application Setup</h2>
<p>The <code>Miew</code> object constructor accepts various options as a parameter. You can pass specific values chosen for your
demonstration:</p>
<pre class="prettyprint source lang-js"><code>var viewer = new Miew({
  container: document.getElementsByClassName('miew-container')[0],
  load: '1CRN',
  reps: [{
    mode: 'LC',
  }, {
    selector: 'elem S',
    mode: 'VW',
    material: 'TR',
    colorer: ['UN', { color: 0xFFFFFF }],
  }],
  settings: {
    autoRotation: -0.5,
    bg: { color: 0xCCCCCC },
    axes: false,
    fps: false,
  },
});
</code></pre>
<p>Alternatively, you may allow user to override options with a URL Query String:</p>
<pre class="prettyprint source lang-js"><code>var _ = Miew.thirdParty.lodash;
var viewer = new Miew(_.merge({
    container: document.getElementsByClassName('miew-container')[0],
    load: '1CRN',
  }, 
  Miew.options.fromURL(window.location.search)
));
</code></pre>
<p>and then <a href="https://miew.opensource.epam.com/?m=LC&amp;m=VW&amp;s=elem+S&amp;mt=TR&amp;c=UN!color:0xFFFFFF&amp;autoRotation=-0.5&amp;bg.color=0xCCCCCC&amp;axes=0&amp;fps=0">pass the same values using a URL</a>:</p>
<pre class="prettyprint source"><code>?m=LC&m=VW&s=elem+S&mt=TR&c=UN!color:0xFFFFFF&autoRotation=-0.5&bg.color=0xCCCCCC&axes=0&fps=0
</code></pre>
<p>You may also apply the same options from any source, e.g. data attribute of the container:</p>
<pre class="prettyprint source lang-html"><code>&lt;div class=&quot;miew-container&quot; data-miew=&quot;m=LC&m=VW&s=elem+S&mt=TR&c=UN!color:0xFFFFFF&autoRotation=-0.5&bg.color=0xCCCCCC&axes=0&fps=0&quot;>&lt;/div>
</code></pre>
<p>It does not happen automatically, you need to retrieve and transform the string to an options object. Then combine
options together and pass them to the <code>Miew</code> constructor.</p>
<pre class="prettyprint source lang-js"><code>var _ = Miew.thirdParty.lodash;
var container = document.getElementsByClassName('miew-container')[0];
var viewer = new Miew(_.merge({
    container: container,
    load: '1CRN',
  }, 
  Miew.options.fromAttr(container.dataset.miew)
));
</code></pre>
<h2>Query String Format</h2>
<p>The easiest way to obtain a URL is to call <code>miew.getURL()</code>, however, you may decide to build the URL manually,
step by step. While constructing the string be aware that such special characters as whitespaces,
<code>+</code>, <code>=</code>, <code>&amp;</code>, <code>:</code>, <code>!</code> must be URL-encoded unless they are a part of formal syntax described below.
You may replace a space with a plus sign (<code>+</code>) instead of a <code>%20</code> code for better readability.</p>
<h3>Change Settings</h3>
<p>The query string consists of ampersand-separated <code>key=value</code> pairs. By default, the application treats them as a global setting
assignment. Use <a href="https://miew.opensource.epam.com/?autoRotation=0.1"><code>autoRotation=0.1</code></a> to enable rotation and set the speed, or <a href="https://miew.opensource.epam.com/?fog=0"><code>fog=0</code></a> to switch the fog off. You may even adjust
nested settings such as <a href="https://miew.opensource.epam.com/?modes.CA.radius=0.05"><code>modes.CA.radius=0.05</code></a> to change default tube radius in Cartoon Mode.
See <code>Settings</code> object for details.</p>
<h3>Execute Commands</h3>
<p>Besides changing global setting you may also specify some commands including those that form visual representation
of molecules. The commands operate in a left-to-right order. Some commands have shorter aliases for convenience.</p>
<p>Data source:</p>
<ul>
<li>
<p><strong>l</strong>, <strong>load</strong> = ( <em>pdbID</em> | <em>source</em> <strong>:</strong> <em>id</em> | <em>url</em> )<br>
Automatically load specified file or PDB ID on startup: <a href="https://miew.opensource.epam.com/?l=4xn6"><code>l=4xn6</code></a>.<br>
You may choose a different file source: <a href="https://miew.opensource.epam.com/?l=cif:4xn6"><code>l=cif:4xn6</code></a>, <a href="https://miew.opensource.epam.com/?l=pubchem:serotonin"><code>l=pubchem:serotonin</code></a>.</p>
</li>
<li>
<p><strong>t</strong>, <strong>type</strong> = <em>typeId</em><br>
Specify explicit type of the loaded file: <a href="https://miew.opensource.epam.com/?t=mmtf&amp;l=http://mmtf.rcsb.org/v1.0/full/4xn6"><code>t=mmtf&amp;l=http://mmtf.rcsb.org/v1.0/full/4xn6</code></a>.<br>
By default, the application determines the data type automatically by the file name (extension) or the
file source used.</p>
</li>
<li>
<p><strong>u</strong>, <strong>unit</strong> = <em>unitIndex</em><br>
Specify a biological unit to view: <a href="https://miew.opensource.epam.com/?l=3s95&amp;u=2"><code>l=3s95&amp;u=2</code></a>.<br>
By default, the application shows the first unit if it exists. You may also specify <code>u=0</code> to show the asymmetric
unit stored in the file.</p>
</li>
</ul>
<p>Visual representation:</p>
<ul>
<li>
<p><strong>p</strong>, <strong>preset</strong> = <em>presetName</em><br>
Choose one of the predefined visual configurations: <a href="https://miew.opensource.epam.com/?p=wire"><code>p=wire</code></a>.<br>
Unless you adjust representation details, the preset is chosen automatically (<code>autoPreset=1</code>)
based on a data source and type. In case you change selector, mode, coloring, or material,
the application will use the <code>default</code> preset as a base.</p>
</li>
<li>
<p><strong>s</strong>, <strong>select</strong> = <em>selectorString</em><br>
Select a subset of atoms: <a href="https://miew.opensource.epam.com/?s=residue+ALA,CYS"><code>s=residue+ALA,CYS</code></a>.</p>
</li>
<li>
<p><strong>m</strong>, <strong>mode</strong> = <em>modeId</em><br>
Change display mode: <a href="https://miew.opensource.epam.com/?m=VW"><code>m=VW</code></a>.</p>
</li>
<li>
<p><strong>c</strong>, <strong>color</strong> = <em>coloringId</em><br>
Change coloring rule: <a href="https://miew.opensource.epam.com/?c=RT"><code>c=RT</code></a>.</p>
</li>
<li>
<p><strong>mt</strong>, <strong>material</strong> = <em>materialId</em><br>
Change material: <a href="https://miew.opensource.epam.com/?mt=ME"><code>mt=ME</code></a>.</p>
</li>
<li>
<p><strong>r</strong>, <strong>rep</strong> = <em>repIndex</em><br>
Explicitly specify a representation to change: <a href="https://miew.opensource.epam.com/?r=0&amp;m=BS&amp;r=1&amp;m=TU"><code>r=0&amp;m=BS&amp;r=1&amp;m=TU</code></a>.</p>
</li>
<li>
<p><strong>dup</strong><br>
Duplicate the current representation and continue to modify it: <a href="https://miew.opensource.epam.com/?dup&amp;m=QS&amp;mt=TR"><code>dup&amp;m=QS&amp;mt=TR</code></a>.</p>
</li>
<li>
<p><strong>v</strong>, <strong>view</strong> = <em>encodedView</em><br>
Restore the view parameters: <a href="https://miew.opensource.epam.com/?v=1%2Bn4pwTVeI8Erh8LAtVogPZLruL4ZnAtAYhl/Pg%3D%3D"><code>v=1%2Bn4pwTVeI8Erh8LAtVogPZLruL4ZnAtAYhl/Pg%3D%3D</code></a>.<br>
The encoded string is not human readable and is usually obtained via <code>miew.view()</code> API call.</p>
</li>
</ul>
<p>A complex example follows (whitespaces are for better readability):</p>
<p><a href="https://miew.opensource.epam.com/?l=mmtf:1rx1&amp;s=not+hetatm&amp;m=CA&amp;c=SS&amp;s=hetatm+and+not+water&amp;m=LC&amp;c=EL&amp;s=sequence+6:7,17:19,43:45,62:64,77,95:99&amp;m=CS&amp;mt=PL&amp;bg.color=0xCCCCCC">l=mmtf:1rx1 &amp;<br>
s=not+hetatm &amp; m=CA &amp; c=SS &amp;<br>
s=hetatm+and+not+water &amp; m=LC &amp; c=EL &amp;<br>
s=sequence+6:7,17:19,43:45,62:64,77,95:99 &amp; m=CS &amp; mt=PL &amp;<br>
bg.color=0xCCCCCC</a></p>
<ul>
<li>load 1RX1 in mmtf format;</li>
<li>select &quot;<code>not hetatm</code>&quot;, set Cartoon mode with Secondary Structure coloring;</li>
<li>select &quot;<code>hetatm and not water</code>&quot;, set Licorice mode with coloring by Element;</li>
<li>select residues by their sequential numbers, set Contact Surface mode with the previous coloring (by Element)
and a Plastic material;</li>
<li>set <code>bg.color</code> global setting to &quot;<code>0xCCCCCC</code>&quot; (set light background).</li>
</ul>
<h3>Compressed Representations</h3>
<p>Instead of specifying representation indices explicitly (<a href="https://miew.opensource.epam.com/?r=0&amp;m=BS&amp;r=1&amp;m=TU"><code>r=0&amp;m=BS&amp;r=1&amp;m=TU</code></a>) you may omit them
(<a href="https://miew.opensource.epam.com?m=BS&amp;m=TU"><code>m=BS&amp;m=TU</code></a>). In such a case the first index is <code>rep=0</code> and it increments each time a duplicate key
is encountered. For example:</p>
<ul>
<li>
<p>Mode: <a href="https://miew.opensource.epam.com/?m=BS&amp;m=QS&amp;mt=TR"><code>m=BS&amp;m=QS&amp;mt=TR</code></a>,<br>
means <code>(m=BS)</code> + <code>(m=QS, mt=TR)</code>.</p>
</li>
<li>
<p>Coloring: <a href="https://miew.opensource.epam.com/?c=RT&amp;c=RI&amp;m=TU"><code>c=RT&amp;c=RI&amp;m=TU</code></a>,<br>
means <code>(c=RT)</code> + <code>(c=RI, m=TU)</code>.</p>
</li>
<li>
<p>Selector: <a href="https://miew.opensource.epam.com/?l=4xn6&amp;s=water&amp;c=CH&amp;s=residue+CYS&amp;m=VW&amp;c=AT"><code>l=4xn6&amp;s=water&amp;c=CH&amp;s=residue+CYS&amp;m=VW&amp;c=AT</code></a>,<br>
means <code>(s=water, c=CH)</code> + <code>(s=residue CYS, m=VW, c=AT)</code>.</p>
</li>
</ul>
<h3>Mode and Coloring Parameters</h3>
<p>Some display modes and coloring algorithms have tuning parameters. You may change their values via
URL. Append an exclamation mark and a comma-separated list of <code>key:value</code> pairs to the mode or coloring ID:</p>
<ul>
<li>
<p><a href="https://miew.opensource.epam.com/?m=BS!atom:0.1,bond:0.05,multibond:0"><code>m=BS!atom:0.1,bond:0.05,multibond:0</code></a><br>
set Balls and Sticks mode; ball radius is 0.1 of VDW radius, bond radius is 0.05 Å,
disable double and triple bonds display;</p>
</li>
<li>
<p><a href="https://miew.opensource.epam.com/?c=UN!color:0x00FF00"><code>c=UN!color:0x00FF00</code></a><br>
set Uniform coloing using green color;</p>
</li>
</ul>
</article>

</section>

</div>

<nav>
    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="SettingsObject.html">SettingsObject</a></li></ul><h3>Classes</h3><ul><li><a href="EntityList.html">EntityList</a></li><li><a href="EventDispatcher.html">EventDispatcher</a></li><li><a href="GROParser.html">GROParser</a></li><li><a href="GROReader.html">GROReader</a></li><li><a href="Helix.html">Helix</a></li><li><a href="LoaderList.html">LoaderList</a></li><li><a href="Logger.html">Logger</a></li><li><a href="Miew.html">Miew</a></li><li><a href="ParserList.html">ParserList</a></li><li><a href="PDBStream.html">PDBStream</a></li><li><a href="Strand.html">Strand</a></li><li><a href="StructuralElement.html">StructuralElement</a></li></ul><h3>Tutorials</h3><ul><li><a href="tutorial-embed.html">Embedding the Viewer</a></li><li><a href="tutorial-events.html">events</a></li><li><a href="tutorial-selectors.html">Selection Language</a></li><li><a href="tutorial-url.html">URL Query String</a></li></ul><h3><a href="global.html">Global</a></h3>
</nav>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.7</a> on Thu Dec 16 2021 21:46:10 GMT+0300 (Москва, стандартное время)
</footer>

<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>