helper_gui.html

<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>helper_gui &#8212; regolith - software group content managment system</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/cloud.css" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Noticia+Text:400,i,b,bi|Open+Sans:400,i,b,bi|Roboto+Mono:400,i,b,bi&amp;display=swap" type="text/css" />
    
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>

    
    
     
        <script src="_static/jquery.cookie.js"></script>
    

    
     
        <script src="_static/cloud.base.js"></script>
    

    
     
        <script src="_static/cloud.js"></script>
    

    <link rel="shortcut icon" href="_static/regolith-logo.ico"/>
    <link rel="search" title="Search" href="search.html" /> 
        <meta name="viewport" content="width=device-width, initial-scale=1">
  </head><body>
    <div class="relbar-top">
        
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
    <li><a href="index.html">regolith</a> &#187;</li>

        <li class="nav-item nav-item-this"><a href="">helper_gui</a></li> 
      </ul>
    </div>
    </div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="helper-gui">
<h1>helper_gui<a class="headerlink" href="#helper-gui" title="Permalink to this heading">¶</a></h1>
<p>Regolith helpers can add to, list from, or update existing collections in your databases. While helpers can be accessed through command line/terminal, the Helper gui is a more comfortable and accessible way to use them.</p>
<p>As with regular regolith, <cite>helper_gui</cite>  must be run from a directory containing a regolithrc.json file and it will use the config parameters it finds in there.  To use the gui, navigate to such a directory and type <cite>regolith_helper</cite>, e.g.,</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">cd</span> path/to/database/local
$ helper_gui
</pre></div>
</div>
</section>
<section id="layout">
<h1>Layout<a class="headerlink" href="#layout" title="Permalink to this heading">¶</a></h1>
<a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/layout.png"><img alt="Layout image" class="align-center" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/layout.png" style="width: 600px;" /></a>
<p>The sidebar on the left hand side contains the available helpers, and the right hand side contains the required and optional arguments for each of the helpers.</p>
</section>
<section id="examples">
<h1>Examples<a class="headerlink" href="#examples" title="Permalink to this heading">¶</a></h1>
<p>There are three main types of helpers:</p>
<ul class="simple">
<li><p>Adders (start with <a href="#id1"><span class="problematic" id="id2">a_</span></a>),</p></li>
<li><p>Listers (start with <a href="#id3"><span class="problematic" id="id4">l_</span></a>, ‘lister’ is included),</p></li>
<li><p>Updaters (start with <a href="#id5"><span class="problematic" id="id6">u_</span></a>),</p></li>
</ul>
<p>Other helpers are:</p>
<ul class="simple">
<li><p>Finishers (start with <a href="#id7"><span class="problematic" id="id8">f_</span></a>),</p></li>
<li><p>Validators (start with <a href="#id9"><span class="problematic" id="id10">v_</span></a>),</p></li>
</ul>
<p>As well as a few specialized ones such as
<em>makeappointments</em></p>
<p>Here we pick representative helpers and discuss how to use the gui for each one.</p>
<p>The gui is pretty self explanatory in general.</p>
<ul class="simple">
<li><p>First select the helper that you want to use in the left hand column.</p></li>
<li><p>Fields then appear on the right of the gui with all of the required and optional arguments for the selected helper.</p></li>
<li><p>After filling in the required fields, as well as any desired optional fields, press start.</p></li>
<li><p>The helper will then be run in the same way as it would if run from the command line.</p></li>
<li><p>The output from the helper will appear in the status field</p></li>
<li><p>To run another helper hit <cite>Edit</cite> and start over</p></li>
<li><p>To rerun the same helper with the same inputs, hit <cite>restart</cite></p></li>
<li><p>You can leave the helper gui running indefinitely and use it whenever you want.  However, to close it hit <cite>close</cite> or click the red X.</p></li>
</ul>
<section id="l-members">
<h2>l_members<a class="headerlink" href="#l-members" title="Permalink to this heading">¶</a></h2>
<p>l_members will list group members from the people collection.   l_members doesn’t have any required fields, and if no optional arguments are selected, it will list all the group members in the database regardless of status.</p>
<a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/l_members.png"><img alt="l_members image" class="align-center" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/l_members.png" style="width: 600px;" /></a>
<p>A short description is given for each entry.    The other optional arguments are quite self explanatory.</p>
<p>The <em>Verbose</em>  radio button in all the helpers will give more information in the output.</p>
<p>All helpers also have the <strong>filter</strong> and <strong>keys</strong> fields that allow filtering for a particular value on any top level field.  If the filter is satisfied the helper will return the value of the keys given in the keys field.  If the <strong>keys</strong> field is left blank just the id’s of the documents that satisfy the filter are returned.</p>
<p>For example,  to get the honors of all the people that contain “Andrew” in the “name” fields you would put <cite>name Andrew</cite> in the filter field and <cite>honors</cite> in the filter field.   Multiple filters can be specified and use the AND logic, so typing <cite>aka andrew bio columbia</cite> will find all people with andrew in the list of aka’s who also have Columbia somewhere in their bio.</p>
<p>Putting <cite>name avatar</cite> in the keys field will return the values of the <cite>name</cite> and the <cite>avatar</cite> field for the documents that satisfy the filter.   The filter field must contain pairs of words (for <cite>key value</cite>) but as in the example, multiple pairs may be specified.</p>
</section>
<section id="a-projectum">
<h2>a_projectum<a class="headerlink" href="#a-projectum" title="Permalink to this heading">¶</a></h2>
<p>This helper will add a new projectum (i.e., mini-project) to the projecta collection.</p>
<a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/a_projectum.png"><img alt="a_projectum image" class="align-center" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/a_projectum.png" style="width: 600px;" /></a>
<p>The required fields are name and lead.</p>
<p>The <cite>description</cite> is a string and does not need to be enclosed in quotes in the gui (it does need to be in quotes on the command line).</p>
<p>For entries that take a list of entries, simply type in entries separated by spaces.  You may use quotation marks if a list entry  contains spaces.  The <cite>collaborators</cite> and <cite>group_members</cite> fields take IDs for entries linked to people that can be found in the <cite>contacts</cite> and <cite>people</cite> collections, respectively, e.g., sbillinge.</p>
<p>For due-date you may type it in ISO format (e.g. 2021-07-23) or select the data using the built int date selector.</p>
<p>A special kind of projectum is a paper submission checklist and selecting this radio button will generate one of these and add it to the collection.</p>
</section>
<section id="u-logurl">
<h2>u_logurl<a class="headerlink" href="#u-logurl" title="Permalink to this heading">¶</a></h2>
<p>u_logurl can be used to update the log url for any projectum in the projecta collection.</p>
<a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/u_logurl.png"><img alt="u_logurl image" class="align-center" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/u_logurl.png" style="width: 600px;" /></a>
</section>
</section>
<section id="database-field">
<h1>database field<a class="headerlink" href="#database-field" title="Permalink to this heading">¶</a></h1>
<p>For adders and updaters, the helper needs to know which database the new/updated entry should be added to.  If the <em>database</em> field is left blank, the first database in the regolithrc.json file will be selected.  However, the name of any database that is in the regolithrc.json can be entered in this <em>database</em> field.  For example, if you run the helper gui from a database called rg-db-private, which contains private information visible only to yourself, but you want to update an entry and have it visible to the entire world, and you have a public database called <cite>rg-db-public</cite> listed in the regolithrc.json, then you would type <cite>rg-db-public</cite> (or whatever is in the name field of the desired database in regolithrc.json).</p>
<p>The <em>date</em> field is rarely used, as a default of today’s date is taken.  The contents of this field is generally used for testing.</p>
</section>
<section id="workflow">
<h1>Workflow<a class="headerlink" href="#workflow" title="Permalink to this heading">¶</a></h1>
<p>This u_milestone helper exemplifies an important pattern in a number of the helpers.  The workflow goes as follows:</p>
<ol class="arabic">
<li><p>Type a fragment of the projectum id that you remember</p>
<blockquote>
<div><a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow1.png"><img alt="workflow1 image" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow1.png" style="width: 400px;" /></a>
</div></blockquote>
</li>
<li><p>Hit start</p></li>
<li><p>The helper will return a list of all projecta that contain that fragment</p>
<blockquote>
<div><a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow3.png"><img alt="workflow3 image" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow3.png" style="width: 400px;" /></a>
</div></blockquote>
</li>
<li><p>Note the full id of in your target projectum</p></li>
<li><p>Click edit to get back to the front page</p></li>
<li><p>Now knowing the full id of your target projectum, type it in the projectum_id field</p>
<blockquote>
<div><a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow6.png"><img alt="workflow6 image" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow6.png" style="width: 400px;" /></a>
</div></blockquote>
</li>
<li><p>Click start again</p></li>
<li><p>The helper will return a numbered list of all milestones in for that projectum</p>
<blockquote>
<div><a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow8.png"><img alt="workflow8 image" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow8.png" style="width: 400px;" /></a>
</div></blockquote>
</li>
<li><p>Without changing the entry in the id field, add the number in the list of your target milestone</p></li>
<li><p>Add any edits you would like to make to the milestone via the other fields</p>
<blockquote>
<div><a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow10.png"><img alt="workflow10 image" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow10.png" style="width: 400px;" /></a>
</div></blockquote>
</li>
<li><p>Click start again</p></li>
<li><p>The correct entry will get updated and a message returned that verifies success</p>
<blockquote>
<div><a class="reference internal image-reference" href="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow12.png"><img alt="workflow12 image" src="https://github.com/regro/regolith/blob/master/docs/helper_gui_images/workflow12.png" style="width: 400px;" /></a>
</div></blockquote>
</li>
</ol>
<p>Note that unless you specify the right database in the <em>database</em> field the update will be inserted in the default database which may, or may not, contain the rest of the projectum information.  This can be confusing until you get the hang of it.</p>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
        <p class="logo"><a href="index.html" title="index">
          <img class="logo" src="_static/regolith-logo.svg" alt="Logo"/>
        </a></p><div class="sphinx-toc sphinxlocaltoc">
    <h3><a href="index.html">Page contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">helper_gui</a></li>
<li><a class="reference internal" href="#layout">Layout</a></li>
<li><a class="reference internal" href="#examples">Examples</a><ul>
<li><a class="reference internal" href="#l-members">l_members</a></li>
<li><a class="reference internal" href="#a-projectum">a_projectum</a></li>
<li><a class="reference internal" href="#u-logurl">u_logurl</a></li>
</ul>
</li>
<li><a class="reference internal" href="#database-field">database field</a></li>
<li><a class="reference internal" href="#workflow">Workflow</a></li>
</ul>

  </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
    
    
        <div class="sidebar-toggle-group no-js">
            
            <button class="sidebar-toggle" id="sidebar-hide" title="Hide the sidebar menu">
                 «
                <span class="show-for-small">hide menu</span>
                
            </button>
            <button class="sidebar-toggle" id="sidebar-show" title="Show the sidebar menu">
                
                <span class="show-for-small">menu</span>
                <span class="hide-for-small">sidebar</span>
                 »
            </button>
        </div>
    
      <div class="clearer"></div>
    </div>
    <div class="relbar-bottom">
        
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
    <li><a href="index.html">regolith</a> &#187;</li>

        <li class="nav-item nav-item-this"><a href="">helper_gui</a></li> 
      </ul>
    </div>
    </div>

    <div class="footer" role="contentinfo">
        &#169; Copyright 2015, Anthony Scopatz.
    </div>
    <!-- cloud_sptheme 1.4 -->
  </body>
</html>