lektor-website/docs/api/db/obj/index.html

509 lines
17 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<link rel="stylesheet" href="../../../../static/styles.css?h=dff0aaad">
<link rel="stylesheet" href="../../../../static/pygments.css">
<link rel="shortcut icon" href="../../../../static/favicon.png?h=fa09bedd">
<title>SourceObject | Documentation | Lektor Static Content Management System</title>
</head>
<body class="default">
<nav class="navbar navbar-inverse navbar-static-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed"
data-toggle="collapse" data-target="#navbar"
aria-expanded="false" aria-controls="navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="../../../../">Lektor</a>
</div>
<div id="navbar" class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li><a href="../../../../downloads/">Download</a></li>
<li class="active"><a href="../../../">Documentation</a></li>
<li><a href="../../../../showcase/">Showcase</a></li>
<li><a href="../../../../plugins/">Plugins</a></li>
<li><a href="../../../../community/">Community</a></li>
<li><a href="../../../../blog/">Blog</a></li>
</ul>
</div>
</div>
</nav>
<div class="body-wrapper">
<div class="container">
<div class="row">
<div class="col-sm-3">
<ul class="tree-nav nocontent">
<li><a href="../../../">Welcome</a></li>
<li><a href="../../../what/">What is Lektor</a>
<li><a href="../../../installation/">Installation</a>
<li><a href="../../../quickstart/">Quickstart</a>
<li><a href="../../../project/">Project</a>
<li><a href="../../../content/">Content</a>
<li><a href="../../../templates/">Templates</a>
<li><a href="../../../themes/">Themes</a>
<li><a href="../../../guides/">Guides</a>
<li><a href="../../../deployment/">Deployment</a>
<li><a href="../../../plugins/">Plugins</a>
<li><a href="../../../models/">Data Modelling</a>
<li><a href="../../../cli/">Command Line</a>
<li><a href="../../">API</a>
<ul>
<li><a href="../../build/">Build System</a>
<li><a href="../../databags/">Databags</a>
<li><a href="../">Database</a>
<ul>
<li><a href="../asset/">Asset</a>
<li><a href="../types/">Builtin Field Types</a>
<li><a href="../expression/">Expression</a>
<li><a href="../f/">F</a>
<li><a href="../get-alts/">get_alts()</a>
<li><a href="../pad/">Pad</a>
<li><a href="../query/">Query</a>
<li><a href="../record/">Record</a>
<li class="active"><a href="./">SourceObject</a>
<ul>
<li><a href="alt/">alt</a>
<li><a href="is-child-of/">is_child_of()</a>
<li><a href="is-discoverable/">is_discoverable</a>
<li><a href="is-hidden/">is_hidden</a>
<li><a href="is-undiscoverable/">is_undiscoverable</a>
<li><a href="is-visible/">is_visible</a>
<li><a href="parent/">parent</a>
<li><a href="path/">path</a>
<li><a href="record/">record</a>
<li><a href="source-filename/">source_filename</a>
<li><a href="url-path/">url_path</a>
<li><a href="url-to/">url_to()</a>
</ul>
<li><a href="../system-fields/">System Fields</a>
<li><a href="../type/">Type</a>
</ul>
<li><a href="../../environment/">Environment</a>
<li><a href="../../plugins/">Plugins</a>
<li><a href="../../project/">Project</a>
<li><a href="../../publisher/">Publisher</a>
<li><a href="../../templates/">Template API</a>
<li><a href="../../utils/">Utilities</a>
</ul>
<li><a href="../../../search/">Search</a>
</ul>
<div class="visible-md-block visible-lg-block">
<h4>This Page</h4>
<ul class="toc">
<li><a href="#virtual-source-objects">Virtual Source Objects</a></li>
</ul>
</div>
</div>
<div class="col-sm-9 doc-styling">
<h1><i class="glyphicon glyphicon-leaf"></i> <code class="mod">lektor.sourceobj.</code><code class="obj">SourceObject</code></h1>
<ul class=page-meta>
</ul>
<p>Source objects is the common interface for all things that come out of the
database. There are two types of source objects:</p>
<ul>
<li><a href="../record/" class="ref">Records</a> which are pages and attachments from the
<code>contents/</code> folder.</li>
<li><a href="../asset/" class="ref">Assets</a> which are files and directories from the
<code>assets/</code> folder.</li>
</ul>
<p>Whatever object you have in hand that comes from the database, they will
at least provide a minimal useful set of API methods and properties.</p>
<p>Plugins can subclass source objects to come up with their own source
objects if needed. In addition to that there is a special source object
called the <code>VirtualSourceObject</code> which is more useful for plugin usage.</p>
<h2 id="virtual-source-objects">Virtual Source Objects</h2><p>Most plugins will not have source objects that actually originate on the
file system. This means that their "source" is entirely virtual. Because
this is a very common situation there is a base class, the
<code>VirtualSourceObject</code> which plugins can subclass. The constructor takes one
argument which is the source record the virtual source lives below. Virtual
sources are separated from the records they belong to with an at sign (<code>@</code>)
in the path. The part after the at sign is called the “virtual path”.</p>
<p>For instance in the below example the canonical path for the object would be
the record's path + <code>@source</code>. So if the record was <code>/hello</code> then the
path would be <code>/hello@source</code>. The true base record it belongs to can be
referenced from the <a href="record/" class="ref">record</a> property.</p>
<div class="hll"><pre><span></span><span class="kn">from</span> <span class="nn">lektor.sourceobj</span> <span class="kn">import</span> <span class="n">VirtualSourceObject</span>
<span class="kn">from</span> <span class="nn">lektor.utils</span> <span class="kn">import</span> <span class="n">build_url</span>
<span class="k">class</span> <span class="nc">Source</span><span class="p">(</span><span class="n">VirtualSourceObject</span><span class="p">):</span>
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">path</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">record</span><span class="o">.</span><span class="n">path</span> <span class="o">+</span> <span class="s1">&#39;@source&#39;</span>
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">source_content</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">record</span><span class="o">.</span><span class="n">source_filename</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
<span class="k">return</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">&#39;utf-8&#39;</span><span class="p">)</span>
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">url_path</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="n">build_url</span><span class="p">([</span><span class="bp">self</span><span class="o">.</span><span class="n">record</span><span class="o">.</span><span class="n">url_path</span><span class="p">,</span> <span class="s1">&#39;source.txt&#39;</span><span class="p">])</span>
</pre></div>
<p>For more information see <a href="../../environment/add-build-program/" class="ref">add-build-program</a> as well as
<a href="../../environment/virtualpathresolver/" class="ref">virtualpathresolver</a>.</p>
<div class="child-pages nocontent">
<div class="row">
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="alt/">alt</a>
</h4>
<p class="summary">The alt the source object corresponds to if available.</p>
</div>
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-cog"></i>
<a href="is-child-of/">is_child_of()</a>
</h4>
<p class="summary">Indicates if the record is a page or attachment.</p>
</div>
</div>
<div class="row">
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="is-discoverable/">is_discoverable</a>
</h4>
<p class="summary">Indicates that a record can be discovered via .children</p>
</div>
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="is-hidden/">is_hidden</a>
</h4>
<p class="summary">Indicates if the object is hidden or not.</p>
</div>
</div>
<div class="row">
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="is-undiscoverable/">is_undiscoverable</a>
</h4>
<p class="summary">The inverse of is_discoverable.</p>
</div>
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="is-visible/">is_visible</a>
</h4>
<p class="summary">Indicates if the object is visible or not.</p>
</div>
</div>
<div class="row">
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="parent/">parent</a>
</h4>
<p class="summary">The parent object for this source object.</p>
</div>
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="path/">path</a>
</h4>
<p class="summary">The path in the source tree of the source object.</p>
</div>
</div>
<div class="row">
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="record/">record</a>
</h4>
<p class="summary">A reference to the associated base record.</p>
</div>
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="source-filename/">source_filename</a>
</h4>
<p class="summary">Returns the filename of the source file.</p>
</div>
</div>
<div class="row">
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-info-sign"></i>
<a href="url-path/">url_path</a>
</h4>
<p class="summary">The absolute URL path of the source object.</p>
</div>
<div class="col-md-6 child">
<h4>
<i class="glyphicon glyphicon-cog"></i>
<a href="url-to/">url_to()</a>
</h4>
<p class="summary">Generates a URL relative to another path.</p>
</div>
</div>
</div>
<div class="comment-box">
<h2>Comments</h2>
<div id="disqus_thread"></div>
<script>
var disqus_config = function() { this.page.identifier = "/docs/api/db/obj"; this.page.url = "https://www.getlektor.com/docs/api/db/obj/"; };
(function() {
var d = document, s = d.createElement('script');
s.src = '//lektordocumentation.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>
Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript"
rel="nofollow">comments powered by Disqus.</a>
</noscript>
</div>
</div>
</div>
</div>
</div>
<div class="bottomsummary">
<div class="container">
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-sm-4 icon-bar">
<a href="https://github.com/lektor/lektor/" title="Lektor on GitHub"
><i class="fa fa-github"></i></a>
<a href="https://github.com/lektor/lektor/issues/" title="Report Issues for Lektor"
><i class="fa fa-bug"></i></a>
<a href="https://twitter.com/getlektor" title="Find Lektor on Twitter"
><i class="fa fa-twitter"></i></a>
<a href="https://gitter.im/lektor/lektor" title="Chat on Gitter"
><i class="fa fa-comment"></i></a>
<a href="https://github.com/lektor/lektor-website/tree/master/content/docs/api/db/obj/contents.lr" title="View source for this page"><i class="fa fa-code"></i></a>
</div>
<div class="col-sm-8">
<a href="../../../../license/">License & Copyright</a>
<a href="../../../../contact/">Contact</a>
Made with <i class="fa fa-fw fa-heart" title="Heart"><span hidden>Heart</span></i> in Carinthia
</div>
</div>
</div>
</footer>
<script type=text/javascript src="../../../../static/app.js?h=8b801996" charset="utf-8"></script>
<script>
((window.gitter = {}).chat = {}).options = {
room: 'lektor/lektor',
activationElement: null
};
document.write('<button class="js-gitter-toggle-chat-button">Toggle Chat</button>');
var dnt = navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack;
if (dnt != "1" && dnt != "yes") {
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-70822533-1', 'auto');
ga('set', 'anonymizeIp', true);
ga('send', 'pageview');
} else {
console.debug("Respecting Do-Not-Track, not running analytics.");
}
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>
<script async defer id="github-bjs" src="https://buttons.github.io/buttons.js"></script>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>
</body>
</html>