carto

<!DOCTYPE html>   <html class="no-js" lang="en" >  <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Language Elements — carto documentation</title> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="index" title="Index" href="genindex.html"/> <link rel="search" title="Search" href="search.html"/> <link rel="top" title="carto documentation" href="index.html"/> <link rel="next" title="Styling Concepts" href="styling_concepts.html"/> <link rel="prev" title="Installation & Usage" href="installation_usage.html"/> <script src="_static/js/modernizr.min.js"></script> </head> <body class="wy-body-for-nav" role="document"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"> <a href="index.html" class="icon icon-home"> carto </a> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> Contents: <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="installation_usage.html">Installation & Usage</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Language Elements</a><ul> <li class="toctree-l2"><a class="reference internal" href="#color">Color</a></li> <li class="toctree-l2"><a class="reference internal" href="#float">Float</a></li> <li class="toctree-l2"><a class="reference internal" href="#uri">URI</a></li> <li class="toctree-l2"><a class="reference internal" href="#string">String</a></li> <li class="toctree-l2"><a class="reference internal" href="#boolean">Boolean</a></li> <li class="toctree-l2"><a class="reference internal" href="#expressions">Expressions</a></li> <li class="toctree-l2"><a class="reference internal" href="#numbers">Numbers</a></li> <li class="toctree-l2"><a class="reference internal" href="#percentages">Percentages</a></li> <li class="toctree-l2"><a class="reference internal" href="#functions">Functions</a></li> <li class="toctree-l2"><a class="reference internal" href="#mapnik-render-time-variables">Mapnik Render-Time Variables</a></li> <li class="toctree-l2"><a class="reference internal" href="#resetting-properties">Resetting properties</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="styling_concepts.html">Styling Concepts</a></li> <li class="toctree-l1"><a class="reference internal" href="mapnik_api.html">Mapnik API documentation</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" role="navigation" aria-label="top navigation"> <a href="index.html">carto</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html">Docs</a> »</li> <li>Language Elements</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/language_elements.rst.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="language-elements"> <h1>Language Elements<a class="headerlink" href="#language-elements" title="Permalink to this headline">¶</a></h1> Below is a list of values and an explanation of any expression that can be applied to properties in CartoCSS. <div class="section" id="color"> <h2>Color<a class="headerlink" href="#color" title="Permalink to this headline">¶</a></h2> CartoCSS accepts a variety of syntaxes for colors - HTML-style hex values, rgb, rgba, hsl, hsla, hsluv, and hsluva. It also supports the predefined HTML colors names, like <cite>yellow</cite> and <cite>blue</cite>. <div class="highlight-default"><div class="highlight"><pre>#line { line-color: #ff0; line-color: #ffff00; line-color: rgb(255, 255, 0); line-color: rgba(255, 255, 0, 1); line-color: hsl(100, 50%, 50%); line-color: hsla(100, 50%, 50%, 1); line-color: hsluv(100, 50%, 50%); // same values yield different color than HSL line-color: hsluva(100, 50%, 50%, 1); line-color: yellow; } </pre></div> </div> Especially of note is the support for HSL and HSLuv, which can be easier to reason about than RGB. CartoCSS also includes several color operation functions <a class="reference external" href="http://lesscss.org/functions/#color-operations">borrowed from LessCSS</a>: <div class="highlight-default"><div class="highlight"><pre>// lighten and darken colors lighten(#ace, 10%); darken(#ace, 10%); // saturate and desaturate saturate(#550000, 10%); desaturate(#00ff00, 10%); // increase or decrease the opacity of a color fadein(#fafafa, 10%); fadeout(#fefefe, 14%); // spin rotates a color around the color wheel by degrees spin(#ff00ff, 10); // mix generates a color in between two other colors. mix(#fff, #000, 50%); // get color components hue(#ff00ff); saturation(#ff00ff); lightness(#ff00ff); alpha(hsla(100, 50%, 50%, 0.5)); </pre></div> </div> These functions all take arguments which can be color variables, literal colors, or the results of other functions operating on colors. All the above mentioned functions also come in a functionp-variant (e.g. <code class="docutils literal">lightenp</code>), which force a given color into HSLuv color space. </div> <div class="section" id="float"> <h2>Float<a class="headerlink" href="#float" title="Permalink to this headline">¶</a></h2> Float is a fancy way of saying ‘number’. In CartoCSS, you specify just a number - unlike CSS, there are no units, but everything is specified in pixels. <div class="highlight-default"><div class="highlight"><pre>#line { line-width: 2; } </pre></div> </div> It’s also possible to do simple math with number values: <div class="highlight-default"><div class="highlight"><pre>#line { line-width: 4 / 2; // division line-width: 4 + 2; // addition line-width: 4 - 2; // subtraction line-width: 4 * 2; // multiplication line-width: 4 % 2; // modulus } </pre></div> </div> </div> <div class="section" id="uri"> <h2>URI<a class="headerlink" href="#uri" title="Permalink to this headline">¶</a></h2> URI is a fancy way of saying URL. When an argument is a URI, you use the same kind of <code class="docutils literal">url('place.png')</code> notation that you would with HTML. Quotes around the URL aren’t required, but are highly recommended. URIs can be paths to places on your computer, or on the internet. <div class="highlight-default"><div class="highlight"><pre>#markers { marker-file: url('marker.png'); } </pre></div> </div> </div> <div class="section" id="string"> <h2>String<a class="headerlink" href="#string" title="Permalink to this headline">¶</a></h2> A string is basically just text. In the case of CartoCSS, you’re going to put it in quotes. Strings can be anything, though pay attention to the cases of <code class="docutils literal">text-name</code> and <code class="docutils literal">shield-name</code> - they actually will refer to features, which you refer to by putting them in brackets, as seen in the example below. <div class="highlight-default"><div class="highlight"><pre>#labels { text-name: "[MY_FIELD]"; } </pre></div> </div> </div> <div class="section" id="boolean"> <h2>Boolean<a class="headerlink" href="#boolean" title="Permalink to this headline">¶</a></h2> Boolean means yes or no, so it accepts the values <code class="docutils literal">true</code> or <code class="docutils literal">false</code>. <div class="highlight-default"><div class="highlight"><pre>#markers { marker-allow-overlap: true; } </pre></div> </div> </div> <div class="section" id="expressions"> <h2>Expressions<a class="headerlink" href="#expressions" title="Permalink to this headline">¶</a></h2> Expressions are statements that can include fields, numbers, and other types in a really flexible way. You have run into expressions before, in the realm of ‘fields’, where you’d specify <code class="docutils literal">"[FIELD]"</code>, but expressions allow you to drop the quotes and also do quick addition, division, multiplication, and concatenation from within CartoCSS syntax. <div class="highlight-default"><div class="highlight"><pre>#buildings { building-height: [HEIGHT_FIELD] * 10; } </pre></div> </div> </div> <div class="section" id="numbers"> <h2>Numbers<a class="headerlink" href="#numbers" title="Permalink to this headline">¶</a></h2> Numbers are comma-separated lists of one or more number in a specific order. They’re used in line dash arrays, in which the numbers specify intervals of line, break, and line again. <div class="highlight-default"><div class="highlight"><pre>#disputedboundary { line-dasharray: 1, 4, 2; } </pre></div> </div> </div> <div class="section" id="percentages"> <h2>Percentages<a class="headerlink" href="#percentages" title="Permalink to this headline">¶</a></h2> In CartoCSS, the percentage symbol, <code class="docutils literal">%</code> universally means <code class="docutils literal">value/100</code>. It’s meant to be used with ratio-related properties, like opacity rules. <div class="admonition attention"> Attention You should not use percentages as widths, heights, or other properties - unlike CSS, percentages are not relative to cascaded classes or page size, they’re, as stated, simply the value divided by one hundred. </div> In an example: <div class="highlight-default"><div class="highlight"><pre>#world { // this syntax polygon-opacity: 50%; // is equivalent to polygon-opacity: 0.5; } </pre></div> </div> </div> <div class="section" id="functions"> <h2>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h2> Functions are comma-separated lists of one or more functions. For instance, transforms use the <code class="docutils literal">functions</code> type to allow for transforms within CartoCSS, which are optionally chainable. <div class="highlight-default"><div class="highlight"><pre>#point { point-transform: scale(2, 2); } </pre></div> </div> </div> <div class="section" id="mapnik-render-time-variables"> <h2>Mapnik Render-Time Variables<a class="headerlink" href="#mapnik-render-time-variables" title="Permalink to this headline">¶</a></h2> Mapnik >= 3.0.0 supports variables of the form <code class="docutils literal">@var</code>. These can be used from CartoCSS by specifying them as strings. For example: <div class="highlight-default"><div class="highlight"><pre>#layer { line-width: '@zoom'; } </pre></div> </div> For this to have any effect you have to pass the variables to Mapnik at render time in a hashmap of the form <code class="docutils literal">variable_name:variable_value</code>. </div> <div class="section" id="resetting-properties"> <h2>Resetting properties<a class="headerlink" href="#resetting-properties" title="Permalink to this headline">¶</a></h2> You can reset properties by specifying them with the keyword <code class="docutils literal">none</code>. They will then be removed from the symbolizer thus using their default value or not using them at all. This does not work or makes sense for all properties like e.g. not for <code class="docutils literal">text-face-name</code>. For an overview over properties where this works or makes sense see <a class="reference external" href="https://github.com/mapbox/carto/blob/master/test/rendering-mss/issue_214.mss">this list</a>. </div> </div> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> <a href="styling_concepts.html" class="btn btn-neutral float-right" title="Styling Concepts" accesskey="n">Next </a> <a href="installation_usage.html" class="btn btn-neutral" title="Installation & Usage" accesskey="p"> Previous</a> </div> <hr/> <div role="contentinfo"> © Copyright 2017, Carto contributors. </div> Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT:'./', VERSION:'', COLLAPSE_INDEX:false, FILE_SUFFIX:'.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <script type="text/javascript" src="_static/js/theme.js"></script> <script type="text/javascript"> jQuery(function () { SphinxRtdTheme.StickyNav.enable(); }); </script> </body> </html>