<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[OddBird - Medium]]></title>
        <description><![CDATA[OddBird helps companies develop, design, and refactor custom mobile and web applications. We’re a tight-knit team of designers and developers ready to integrate with companies, scale applications, and improve results. We don’t just follow best-practice — we help define it. - Medium]]></description>
        <link>https://medium.com/oddbird-web?source=rss----316a2595b32---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>OddBird - Medium</title>
            <link>https://medium.com/oddbird-web?source=rss----316a2595b32---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 06:23:10 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/oddbird-web" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[How to Design More Intuitive Websites & Apps]]></title>
            <link>https://medium.com/oddbird-web/how-to-design-more-intuitive-websites-apps-c6d4181eee22?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/c6d4181eee22</guid>
            <category><![CDATA[ux]]></category>
            <category><![CDATA[ooux]]></category>
            <category><![CDATA[web-app-development]]></category>
            <category><![CDATA[web-design]]></category>
            <category><![CDATA[accessibility]]></category>
            <dc:creator><![CDATA[Sondra Eby]]></dc:creator>
            <pubDate>Fri, 02 Feb 2024 19:10:08 GMT</pubDate>
            <atom:updated>2024-02-02T19:10:08.794Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TGtAakv531FyJvApbErkrA.png" /><figcaption>Unmask your website for a more intuitive user experience</figcaption></figure><p>Do you want to make your website or web app more intuitive for the people who visit? If so, I’d like to introduce you to the world of Object-Oriented UX. As a UX designer at OddBird, using OOUX strategies to identify and avoid <em>un</em>intuitive objects has been key to our design process. A warning, though, before you continue: once you start seeing unintuitive objects, you won’t be able to unsee them!</p><p>Check out OddBird’s <a href="https://www.oddbird.net/wingingit/">Winging It</a> channel for a conversation between designers and developers on intuitive web design.</p><p><strong>Winging It</strong> episode 3: <a href="https://www.oddbird.net/2023/10/24/winging-it-03/">Intuitive Web Design with OOUX</a></p><h3>Objects on the Web</h3><p>I’ve been noticing unintuitive objects and working to avoid them since I first took Sophia Prater’s <a href="http://partners.ooux.com/348125/17189">Object-Oriented UX Course</a> in 2020, becoming a <a href="https://www.ooux.com/people/sondraeby">Certified OOUX Strategist</a>. To understand unintuitive objects, let’s first define what <em>objects</em> are in a digital system.</p><p>An <em>object</em> in a web project is something that has <strong>structure</strong>, <strong>instances</strong>, and <strong>purpose</strong>.</p><p>Just as the structure of an object in the physical world such as a chair includes the seat, back, and legs, the structure of a digital object includes all the stuff that makes up that object. For example, on a blog, an article is an object. The structure of an article includes the author, the title, the images and text, the published date and time, the updated date and time, the category or topic, and more.</p><p>Instances are all the specific occurrences of an object. To go back to a physical object, instances of the chair object in my house would include the pink roller chair I sit in at my desk, the small chair my daughter uses in her room, the tiny chair in my daughter’s dollhouse, and each chair at the kitchen table.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mJTi48N7j2Yd12NBESDGwQ.jpeg" /><figcaption><em>Five instances of a CHAIR object in a bookshop</em></figcaption></figure><p>Instances of a digital article object on a blog could include articles like: “<a href="https://www.oddbird.net/2023/10/30/when-to-choose-a-progressive-web-app/">When to Choose a Progressive Web App</a>,” “<a href="https://www.oddbird.net/2023/10/23/sqlalchemy-for-django-developers/">SQLAlchemy for Django Developers</a>,” or “<a href="https://www.oddbird.net/2023/10/19/fastapi-path-operations-for-django-developers/">FastAPI Path Operations for Django Developers</a>.”</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5xjhRykl7TtQQQxvxFmPng.jpeg" /><figcaption><em>Six instances of an ARTICLE object on OddBlog</em></figcaption></figure><p>The purpose of the chair object in our example from the physical world is to provide people (and dolls) a place to sit down. The purpose of the digital article object on the blog is to convey information to readers about specific topics of interest.</p><blockquote><em>“All humans think in objects — designers, end-users, and those who painted the caves of Chauvet. So, as we make our user experiences more object-oriented, we also make them more </em>intuitive<em>.”</em></blockquote><blockquote><em>–</em>Sophia Prater<em>, </em><a href="https://www.ooux.com/what-is-ooux"><em>ooux.com</em></a></blockquote><p>With that definition of objects in mind, let’s look at what makes a digital object <em>unintuitive</em> for people using the web. Though it may seem backward, looking at examples of digital objects gone wrong is a really impactful way to learn how to make them more intuitive.</p><h3>Unintuitive Objects on the Web</h3><p>There are four type of unintuitive objects: <strong>Isolated</strong>, <strong>Broken</strong>, <strong>Masked</strong>, and <strong>Shapeshifter</strong>. To find examples of these unintuitive objects, I decided to go spelunking through the website of one of my favorite places to visit — the Denver Zoo. The photography and graphic design are lovely, and what a great excuse to pore over pictures of cute animals!</p><h3>Isolated Objects</h3><p><em>Objects that are disconnected from related objects.</em></p><p>ANIMAL, HABITAT (where an animal lives), and DEMO (an animal demonstration event) are three essential objects at the zoo. The zoo website does include all three of these objects — ANIMAL, HABITAT, and DEMO. Hooray!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OohumfWtsMXvGLx3CCiTTg.jpeg" /><figcaption><em>ANIMAL, HABITAT, and DEMO are three important objects at the zoo</em></figcaption></figure><p>The ANIMAL object in the digital space of the Denver Zoo’s website is perhaps the most important object! If we look at specific instances of the ANIMAL object, though, we find the first type of unintuitive object called an isolated object. For example, the <em>African Penguin</em> is one instance of the ANIMAL object. The <em>Pinnacol African Penguin Point</em> is this penguin’s HABITAT at the zoo. And <em>Demonstration — African Penguin</em> is the name of the penguin DEMO that zoo visitors can attend.</p><p>These three objects ANIMAL, HABITAT, and DEMO are necessarily related in the physical world, and should be related on the website as well.</p><p>However, if we look at the African Penguin in the list of all the ANIMALS or on the African Penguin detail page, there is no link to the penguin’s HABITAT and not even any mention of the penguin DEMO.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uq2KhgpwmxmgRISEFqDgGw.jpeg" /><figcaption><em>Penguin ANIMAL detail and list views with no link to the penguin HABITAT</em></figcaption></figure><p>Likewise, if we visit the Pinnacol African Penguin Point HABITAT on the website, the African Penguin ANIMAL is at least listed, but it links back to the penguin HABITAT instead of to the penguin ANIMAL. Again, there is no mention of the penguin demonstration DEMO.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2sgjFVncCpZadnD6s2Gzrg.jpeg" /><figcaption><em>Penguin HABITAT with a broken link to the penguin ANIMAL</em></figcaption></figure><p>The HABITAT is also included on the map view of the zoo. But there is no link to the African Penguin ANIMAL nor to the DEMO in this map view either.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*irpW8Ua7Y0uO0JdzDN-E_A.jpeg" /><figcaption><em>No link to the penguin ANIMAL or the penguin DEMO on the map view</em></figcaption></figure><p>Further, the section of the site with information about the Demonstration — African Penguin DEMO — mentions the name of the HABITAT where the DEMO takes place and the name of the ANIMAL, but it doesn’t link to either.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*X6UZA6ZKC5bPbtdorYus4Q.jpeg" /><figcaption><em>DEMOs in a list with ANIMAL and HABITAT name, but no link to either related object</em></figcaption></figure><p>As a visitor at the zoo, I have opted to wander around and look at the physical signage hoping I won’t miss a fun event, rather than to try to piece together these unintuitive, isolated objects using the website.</p><p>To fix this isolation problem, as a designer using the OOUX method, I would define the ANIMAL, HABITAT, and DEMO objects at the very beginning of the project. I would list all of their relationships to each other in the system and prioritize the important relationships.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pUC-GDtJrmbejZIEhsj_8g.jpeg" /></figure><p>When designing the detail view of an ANIMAL object, I would be sure to include links to and from the HABITAT and DEMO objects to establish these high-priority relationships. I would likely even design a card view of the HABITAT and DEMO objects and nest those cards within the ANIMAL detail page.</p><h3>Broken Objects</h3><p><em>Objects that are not directly manipulatable.</em></p><p>A <em>broken object</em> is an object that isn’t directly manipulatable within a digital space.</p><p>One of my favorite things to do at the zoo is attend demonstrations like the feeding of the penguins. So DEMO is a really useful object for the zoo to include on its website. Hooray! Unfortunately, DEMO has been incorporated into the zoo’s website in a broken way.</p><p>For example, here are instances of the DEMO object in a list.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*64eG3wYrn84nUEEDiui5RQ.jpeg" /><figcaption><em>DEMO list view with no way to filter or sort</em></figcaption></figure><p>As someone who would like to attend the penguin DEMO, I want to click on an individual DEMO to see more details, like a description or a map showing the way to the location, but I can’t. There are also two different times when the penguin DEMO happens, and a variety of locations where DEMOS happen. As a person planning my visit to the zoo, it would be useful to see all the time options for one DEMO grouped together, or see only the DEMOS happening at a specific time, or all the DEMOS happening at one location. But I can’t sort or filter the DEMOS by time or location — I can’t take the actions I want to take when I encounter this DEMO object in this system. As a regular visitor to the zoo site, I would describe this experience as <em>unintuitive</em>.</p><p>If I were redesigning this DEMO list using the object-oriented method, again I would identify the DEMO object at the very beginning of the project and list all the actions people would like to take before designing a landing page like this or making any mockups at all.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/480/0*tCwWui5SQLtKDyIR.jpeg" /></figure><p>That way, when it comes time to design this landing page, I could focus on laying out and styling the interactions I had already identified instead of trying to figure out what the interactions should be while designing them. Splitting up these concerns means you’re less likely to forget or leave out important interactions. You’re more likely to create a digital experience where people can easily do all the things to an object that they expect to be able to do — a more <em>intuitive</em> web design!</p><h3>Masked Objects</h3><p><em>Objects that are styled to look the same, but are actually different.</em></p><p>As a designer, I have accidentally created my share of masked objects before I learned to design in objects.</p><p>To understand masked objects, let’s go straight to an example. When creating a landing page, it can seem like a big time saver and provide a unified look if everything uses the same card style. Leaving the zoo for a moment, let’s look at the DisneyPlus landing page. Here we see several rows of rectangles that all look identical except for the specific image and title.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*52PX4u40nfnqDQl1t2jt4g.jpeg" /><figcaption><em>DisneyPlus website with rows of shows designed as identical rectangles</em></figcaption></figure><p>It is quite easy to skim. But there are arguably two separate objects here that have an identical design — a MOVIE and a TV SERIES. As a DisneyPlus web app user, I have often searched for a movie to watch with my family, clicked one of these lovely boxes, and discovered to my dismay that it wasn’t a movie, but a TV series masquerading as a movie.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zn_FqU9yCsj5_-liYTRBVg.jpeg" /><figcaption><em>One rectangle goes to a TV SERIES detail page</em></figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*p-Oxgh7xFdoR7tD5sarksg.jpeg" /><figcaption><em>Another rectangle goes to a MOVIE detail page</em></figcaption></figure><p>If I were to redesign the DisneyPlus MOVIE and SERIES objects as two separate objects, I would list all of the attributes for each object, and then identify the unique and high priority attributes. For example, both a MOVIE and SERIES object have an image (with the title included), but a SERIES has <em>seasons</em> and <em>episodes</em> while a MOVIE has a <em>total length</em>. Even if I wanted a consistent rectangle card on my homepage, I could at least include the number of seasons on the SERIES card and the total length on the MOVIE card. To make a MOVIE and a SERIES even more instantly differentiated, I could make all MOVIE cards square and all SERIES cards rectangular.</p><p>MOVIES and SERIES arguably aren’t actually different objects in this system. They do have a large amount of the same attributes. Perhaps they are two different types of a VIDEO object. That decision is up to the UX designer — but even in that case, it would be a more intuitive experience to see a MOVIE or a SERIES tag on these cards.</p><h3>Shapeshifter Objects</h3><p><em>Objects that are styled to look different, but are actually the same.</em></p><p>In my experience, one of the most common reasons a website visitor will experience a site as <em>unintuitive</em> is due to shapeshifter objects. Not only is avoiding shapeshift objects a huge win for the user, but it can also save UX designers a lot of time creating mockups.</p><p>Let’s look again at the DEMO object on the zoo website. This object appears in at least two different list views on the website. These lists both display DEMOS, but the DEMO object looks different in each list. One list shows each DEMO title once with all the times the DEMO happens right under the title. The other list shows each DEMO title multiple times with only one of the times the DEMO happens. In the first list the times are in bold, while in the other list the times are italicized. In the first list the am and pm do not have punctuation, while in the other they do. The first list does not include the DEMO location – the other does.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*q65GMqMzoGFpz6-JmtasQw.jpeg" /><figcaption><em>Two versions of the DEMO list in which the DEMO styles shift</em></figcaption></figure><p>These are fairly minor differences. If you start to look for shapeshifters yourself, you will find much more dramatic redesigns of the same object on websites and apps for no discernable reason. Even with these small differences, as a visitor to the website it is not immediately obvious that these two lists contain instances of exactly the same DEMO object. We want our digital spaces to feel as intuitive as our physical spaces. Identifying and interacting with this DEMO object could be as intuitive as identifying and sitting down in a chair, if it looked and acted the same in every context.</p><p>Additionally, the designer of these two list views spent time redesigning the DEMO object in each context. Using OOUX, we can more efficiently identify objects upfront, design the list view, card view, and detail view for each object one time, and then use those same designs everywhere the object appears on the site.</p><p>_________________________________________________________________</p><h3>Need help making your website more intuitive?</h3><p>At OddBird, we care deeply about UX clarity, accessibility, and creating custom design web experiences that help people.</p><p><strong>If you’d like an OOUX analysis of your website </strong>or application, <a href="https://calendly.com/oddbird/discovery">schedule a 30 minute chat</a> with <a href="https://www.oddbird.net/authors/sondra/">Sondra Eby, our certified OOUX Strategist</a>, or hire OddBird for a redesign. Don’t hesitate to reach out. If you’re interested in learning more about object-oriented UX, check out <a href="https://www.ooux.com/">ooux.com</a>.</p><p>You can use our handy <a href="http://oddbird.net/contact/">contact form</a>, talk to <a href="https://twitter.com/oddbird">@OddBird</a> on Twitter, or <a href="https://front-end.social/@OddBird">@OddBird</a> on Mastodon. We’re excited to hear from you!</p><ul><li><a href="http://twitter.com/oddbird">@OddBird</a> on Twitter</li><li><a href="https://front-end.social/@OddBird">@OddBird</a> on Mastodon</li><li><a href="/service/mailto:birds@oddbird.net">birds@oddbird.net</a> by Email</li></ul><p><strong>Happy object-oriented UX designing!</strong></p><p><em>Originally published at </em><a href="https://www.oddbird.net/2023/11/09/unintuitive-objects/"><em>oddbird.net</em></a><em> on November 9, 2023.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c6d4181eee22" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/how-to-design-more-intuitive-websites-apps-c6d4181eee22">How to Design More Intuitive Websites &amp; Apps</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Herman Style Guides]]></title>
            <link>https://medium.com/oddbird-web/herman-style-guides-4bcadc57169f?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/4bcadc57169f</guid>
            <category><![CDATA[pattern-library]]></category>
            <category><![CDATA[development]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[style-guides]]></category>
            <category><![CDATA[design-systems]]></category>
            <dc:creator><![CDATA[Miriam Suzanne]]></dc:creator>
            <pubDate>Wed, 17 Jan 2018 21:52:15 GMT</pubDate>
            <atom:updated>2018-01-18T19:25:49.009Z</atom:updated>
            <content:encoded><![CDATA[<p><em>An agile approach to design systems on a budget</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vORF91ckjsOGqpzMPkH_ww.jpeg" /></figure><p><strong>Design systems streamline development, communication, and consistency</strong> — but often rely on dedicated teams and extended budgets. We wanted a tool to create and maintain living style guides andpattern libraries in an agile process, and on a budget. <a href="http://oddbird.net/herman/"><strong>Herman</strong></a> helps keep our development flow simple and our UX consistent as we iterate on patterns and scale over time.</p><p><em>We’ve just launched Herman 1.0 as a free, open source project for anyone to use and make contributions.</em> Check out the <a href="http://oddbird.net/herman/docs/"><strong>full documentation</strong></a>, or <a href="http://oddbird.net/contact/"><strong>contact us</strong></a> for help <a href="http://oddbird.net/services/design-systems-training/"><strong>putting your design system in place</strong></a>.</p><p>I spent the week after Thanksgiving in San Francisco, attending (and <a href="https://twitter.com/jina/status/935566434700222465">accidentally speaking at</a>) <a href="https://www.clarityconf.com/2017">Clarity</a> — a “<a href="https://www.designbetter.co/design-systems-handbook/">Design Systems</a>” conference organized by the wonderful <a href="https://www.patreon.com/sushiandrobots">Jina Anne</a>. If you don’t have experience with design systems, I highly recommend the <a href="https://www.designbetter.co/design-systems-handbook/">Handbook</a> which Jina co-authored — available free online.</p><p>I’m always curious how many attendees at a conference are working on enterprise projects over a long period of time vs. those of us who do consulting for multiple clients each year. These different contexts can lead to very different solutions — affecting team size, budget, process, architecture, and technical requirements.</p><p>I don’t know the exact mix at Clarity, but I think that design systems generally skew towards the enterprise projects for one reason: budget. Creating the beautiful <a href="https://www.lightningdesignsystem.com/">Salesforce Lightning Design System</a> requires an ongoing full-time dedicated team. Those of us doing agency work don’t often have that luxury, but our clients still need a system that will work for them.</p><p>So how can we make design systems part of an agile process — growing slowly along-side the application, the same way we write and maintain test-coverage as part of any project? How do we make documentation and design consistency the path of least resistance?</p><blockquote><strong>If it’s not documented, it doesn’t exist.</strong> Documentation should become the default — an integrated part of the development process.</blockquote><blockquote><em>— Miriam Suzanne (me)</em></blockquote><p>Design Systems can include a wide array of features, more than just a pattern library, and Herman does not cover the full gamut — but it doesn’t have to. With <a href="http://oddbird.net/herman/">Herman</a> we start small, documenting brand design tokens — <a href="http://oddbird.net/herman/docs/demo_colors.html">colors</a>, <a href="http://oddbird.net/herman/docs/demo_fonts.html">fonts</a>, <a href="http://oddbird.net/herman/docs/demo_sizes.html">sizes</a>, <a href="http://oddbird.net/herman/docs/demo_sizes.html">ratios</a>, and <a href="http://oddbird.net/herman/docs/demo_icons.html">icons</a> — before expanding into <a href="http://oddbird.net/herman/docs/demo_examples.html">practical patterns and components</a>, with automation to help us scale.</p><h3>Shared Problems, Unique Constraints</h3><p>The term “design system” refers generally to documenting &amp; distributing isolated patterns and components that can be used across one or more applications for consistent user experience. That usually involves some combination of “style guides” and/or “pattern libraries” — the detailed documentation of design tokens, UI patterns, components, and overall system guidelines.</p><p>Lightning Design and other massive projects can make this goal feel daunting, but we’ve found it useful to build what we can, as we go, even when the results are incomplete by comparison. These problems aren’t all-or-nothing. There is room for flexibility in our approaches, from one project to the next. The important question is <em>where can I start </em>improving design communication, clarity, and consistency?</p><p>At OddBird, our first style guide attempts failed because they required too much maintenance and attention. So we scaled back to automating color-palettes, and not much else. Over time we’ve added support for a wide array of features integrating with our Sass tooling, and Herman has evolved into a full-featured tool for agile design systems.</p><p>Now we use Herman across a range of products, from large client applications to our own internal toolkits. While there are a number of possible configuration options, the initial setup can be streamlined to make sense on even the smallest projects. We’ve even used Herman to <a href="http://oddbird.net/herman/docs/">begin documenting itself</a> — from design language to components and API.</p><p>The project is not complete — and never will be — but that’s the point. As time goes on, we’ll keep adding features that allow our systems to become larger, more complex, and more automated — with support for additional languages.</p><h3>Integrated Syntax, Built on SassDoc</h3><p>Style documentation tools have existed for some time, providing a great place to start without re-inventing the wheel. As a design-driven team using Sass/CSS, we love keeping our style documentation directly in with our stylesheets, using tools like <a href="http://warpspire.com/kss/">KSS</a> and <a href="http://sassdoc.com/">SassDoc</a>. When developers add a pattern in the stylesheet, they can document their work right at the source. When a pattern changes, all the edits can be made in a single location, so documentation is more likely to stay up-to-date.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Uvyr1lR-o0uH7ci7.jpg" /></figure><p>Those tools are great, but neither one is built to handle more complex design systems, integrated with markup templates and other languages. On the other side, many of the existing “style guide generators” are too intrinsically tied to specific JavaScript frameworks, separating documentation and styles. That may be a good solution for some, but it didn’t feel right for the way we work.</p><p>We decided to extend SassDoc, using their framework as a jumping-off point for something larger. The SassDoc syntax uses a variant on Sass line-comments to explicitly mark documentation for parsing:</p><pre>// Normal Sass comments are ignored by SassDoc</pre><pre>/// Comments that begin with 3 slashes <br>/// will be parsed as SassDoc documentation.</pre><p>In addition to allowing prose descriptions (parsed as markdown), SassDoc includes a number of explicit annotations, using an @annotation syntax. Here are just a few of their options:</p><pre>/// @group buttons <br>/// @access public <br>/// @param {color} $color [green] - The background color for the button <br>/// @example scss <br>///   .button { <br>///     @include call-to-action(red); <br>///   }</pre><p>Herman supports <a href="http://sassdoc.com/annotations/">all SassDoc annotations</a>, and we’ve added style guide features of our own…</p><h3>Visualizing Design Tokens</h3><p>A “design token” is an abstract bit of design language that normally becomes visible only when applied to more explicit patterns and components. Colors, fonts, scales, and grid-configurations act as “sub-atomic” aspects of a design system — often stemming directly from the brand, before any UI components have been built. This is a good place to start defining your system, and Herman can help you visualize these abstractions.</p><p>Herman provides display annotations for <a href="http://oddbird.net/herman/docs/demo_colors.html">colors</a> (@colors), <a href="http://oddbird.net/herman/docs/demo_fonts.html">fonts</a> (@fonts), <a href="http://oddbird.net/herman/docs/demo_sizes.html">sizes</a> (@sizes), and <a href="http://oddbird.net/herman/docs/demo_sizes.html">ratios</a> (@ratios):</p><pre>/// @colors brand-primaries <br>/// @font my-font (regular, bold) <br>///   &lt;any html head required for CDN font imports&gt; <br>/// @sizes my-spacing <br>/// @ratios my-modular-scale</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*EHteriqrPbcnVu5c.jpg" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*leD3zuI8AsSTd7lF.jpg" /></figure><p>In order to display that data, you will need to export all your Sass tokens to json, using our provided <a href="http://oddbird.net/herman/docs/api_json-export.html">Sass export utilities</a>. We’re working to make this step even more simple and automatic.</p><p>We also provide an @icons annotation to display all the SVG icons in a given folder:</p><pre>/// @icons path-to/my-assets/svg/</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*LxkOBFDp2TRYUZzA.jpg" /></figure><h3>Rendered Output &amp; Examples</h3><p>At the pattern level, we include more robust tools for rendering code examples and live patterns. While SassDoc only documents Sass abstractions, Herman allows <a href="http://oddbird.net/herman/docs/demo_examples.html">documentation of CSS selectors and markup patterns</a>.</p><p>We’ve extended SassDoc’s @example annotation for languages like <a href="http://sass-lang.com/">Sass</a> and <a href="https://mozilla.github.io/nunjucks/">Nunjucks</a> (we’re working on support for Vue components). Herman will display both input and compiled code, along with the rendered output when necessary:</p><pre>/// Add default button styles to an element. <br>/// @group buttons <br>/// @example html - submit button <br>///   {% import &#39;content.macros.j2&#39; as content %} <br>///   {{ content.button(&#39;Submit&#39;, attrs={&#39;type&#39;: &#39;submit&#39;}) }} [data-btn] { <br>  border: 1px solid currentColor;<br>  border-radius: 3em;<br>  color: pink;<br>  display: inline-block;<br>  padding: 0.25em 1em; <br>}</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*n1GMgGV4N1yQ9BGh.jpg" /></figure><h3>Prose, Pages, and Third-Party Links</h3><p>In building documentation — from basic reference docs to extensive design systems — we often find it useful to include additional prose and links to third-party docs for dependencies. There are several ways to do this in Herman:</p><h4>Free-floating Prose</h4><p>Any SassDoc comments (///) that are not attached to a specific Sass/CSS objects will appear as free-floating prose, and can be given generic annotations – such as @group, @example, @link, etc. – including the Herman design-token annotations.</p><h4>Additional Markdown Pages</h4><p>You can add any number of <a href="http://oddbird.net/herman/docs/CONFIGURATION.html#extradocs">markdown documents</a> to your style guide navigation, by defining extraDocs in your <a href="http://oddbird.net/herman/docs/CONFIGURATION.html">Herman configuration</a>. We use this to create an introduction to our design systems, provide quick access to a changelog, or document patterns that are not directly attached to Sass code.</p><h4>Third-party Links</h4><p>You can also add <a href="http://oddbird.net/herman/docs/CONFIGURATION.html#extralinks">external links</a> to third-party dependencies — so all relevant documentation is accessible in one place. Define extraLinks in your Herman configuration, and we’ll add links to the bottom of the sidebar.</p><h3>Open Source &amp; Actively Developed</h3><p>We’re using Herman on many of our production projects, and we have big plans for Herman’s future. We’ll keep adding features, and we invite you to do the same. The Herman code is <a href="https://github.com/oddbird/sassdoc-theme-herman">available on GitHub</a>, and we’d love to hear your thoughts. File issues for bug-reports, feature requests, or help getting started — or send us your pull requests.</p><p>We’ll keep providing our own tutorials and demos based on the questions we hear most, but we’d also love to list any style guides or pattern libraries you build with Herman, or any <a href="http://oddbird.net/herman/articles/">tutorials</a> you’ve written.</p><p>We’re always excited to collaborate, and we’ve provided some <a href="http://oddbird.net/herman/docs/CONTRIBUTING.html">“contributing” documentation</a> to help you get involved.</p><h3>Need help with your design system?</h3><p>At OddBird, we care deeply about test-coverage and documentation, accessibility, performance, and UX clarity. Herman is one part of our solution, but no tool can provide the magic bullet.</p><p><strong>If you need help with a refactor</strong> to improve design systems, performance, testing, documentation, or accessibility — eliminate technical debt, and put better processes in place — we’re here for you. Our <a href="http://oddbird.net/birds/">team of experts</a> can provide <a href="http://oddbird.net/services/design-systems-training/">a range of support, training, and consulting</a> across the full stack of product design &amp; development — helping find <em>the solution that best fits your team</em>. Don’t hesitate to reach out.</p><p>You can use our handy <a href="http://oddbird.net/contact/">contact form</a>, talk to <a href="https://twitter.com/oddbird">@OddBird</a> on Twitter, or join our <a href="http://friends.oddbird.net/">public Slack</a> (with a dedicated #herman channel). We’re excited to hear from you!</p><ul><li><a href="http://twitter.com/oddbird">@OddBird</a> on Twitter</li><li><a href="http://friends.oddbird.net/">OddBird Friends</a> public Slack</li><li><a href="/service/mailto:birds@oddbird.net">birds@oddbird.net</a> by Email</li></ul><p><em>Originally published at </em><a href="http://oddbird.net/2018/01/03/introducing-herman"><em>oddbird.net</em></a><em> on January 3, 2018.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4bcadc57169f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/herman-style-guides-4bcadc57169f">Herman Style Guides</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Welcome to Susy3!]]></title>
            <link>https://medium.com/oddbird-web/welcome-to-susy3-a0127e594b53?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/a0127e594b53</guid>
            <category><![CDATA[susy]]></category>
            <category><![CDATA[sass]]></category>
            <category><![CDATA[grid]]></category>
            <category><![CDATA[susy3]]></category>
            <category><![CDATA[css]]></category>
            <dc:creator><![CDATA[Miriam Suzanne]]></dc:creator>
            <pubDate>Wed, 19 Jul 2017 20:18:20 GMT</pubDate>
            <atom:updated>2017-07-20T17:20:52.962Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Make grid systems your fallback plan</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Fm4aWE88x9bWfkwtFyAMFA.jpeg" /></figure><p><strong>We’re excited to introduce Susy 3.0</strong>, a major update to our popular grid-math calculator — now more focused and flexible than ever. Susy was designed to make layout math easy, without forcing you into generic patterns and ugly markup. But grid systems are on the way out, replaced by real CSS layout specs that live in the browser. With Susy3, we want to help make that a smooth transition.</p><p><a href="http://oddbird.net/susy/"><strong>Susy3 Website</strong></a> »<br><a href="http://oddbird.net/susy/docs/"><strong>Susy3 Reference Docs</strong></a><strong> </strong>»</p><p>I remember when <a href="http://www.blueprintcss.org/">Blueprint</a> first came out. Besides <a href="https://meyerweb.com/eric/tools/css/reset/">Eric Meyer’s Reset</a>, it was one of the first open-source CSS libraries that our industry started using en-masse. That’s how I remember things, at least. I had just quit my day job as a junior print designer to start freelancing. A year later, I joined forces with <a href="http://oddbird.net/birds/#bird-carl">Carl</a> and then <a href="http://oddbird.net/birds/#bird-jonny">Jonny</a> to form OddBird.</p><p>At that point, every layout required extensive hacks to work across browsers, and CSS frameworks quickly took over. But there are some things you can’t do in a pure CSS API based on classes. <a href="http://blog.natbat.net/post/46614243624/css-systems">Natalie Downe</a> was proposing a more flexible approach to grids and toolkits, and <a href="http://chriseppstein.github.io/blog/">Chris Eppstein</a> was pushing hard to show how <a href="http://sass-lang.com/">Sass</a> and <a href="http://compass-style.org/">Compass</a> could revolutionize CSS-sharing and tool APIs.</p><p>Susy came out of that mix in July, 2009. Nothing terribly original, just putting the pieces together. I didn’t have a GitHub account at the time, so Carl published Susy on my behalf. The first draft was kind of ugly — but a few people took interest, and helped me clean it up. Three years later, it had become the inspiration for an entire genre of Sass grid systems — with several creative adaptations like <a href="https://github.com/at-import/Singularity">Singularity</a> to keep us on our toes.</p><h3>A Whole New World</h3><p>We work on a different web now. Browser-hacks are mostly a thing of the past, and we have real control over the box-model (one thing IE got right the first time). Flexbox and the CSS Grid module are providing real layout tools in the browser, with flexibility baked in.</p><p>Singularity recently <a href="https://snugug.com/musings/saying-goodbye-to-singularity/">shut down development</a>, and we considered doing the same thing. Grid systems are on the decline for a good reason. It’s time to move away from these tools, and put our layouts back in the browser. Instead of closing shop, though, we wanted to provide one more major update truly designed for the edge-cases that remain.</p><p>Susy3 is stripped down to the core — a grid-math module we call Su, and a syntax module to add API sugar over top. There are two primary API functions, span() and gutter(), and a total of four configuration settings.</p><p>That’s right, Susy3 has no mixins. When we wrote the mixins for Susy1 and Susy2, floats were (practically) the only option, and required a fair amount of hacking help. Mixins provided those shortcuts, at the expense of user flexibility. But mixins also created a black-box of CSS output, which made it more difficult for users to understand the code they were writing.</p><p>The core of Susy has always been the math, and the “natural-language” API. Accessing that math only through functions will allow Susy to get out of your way, and work with any future layout technique you need: floats, flexbox, tables, inline-block, even CSS Grids.</p><h3>CSS Grids</h3><p>If you have the <a href="http://caniuse.com/#feat=css-grid">browser-support matrix</a> to start using the <a href="https://css-tricks.com/snippets/css/complete-guide-grid/">CSS Grid module</a> directly, you should do it, and forget about Susy. Brilliant developers like <a href="https://gridbyexample.com/">Rachel Andrew</a> and <a href="http://jensimmons.com/post/feb-27-2017/learn-css-grid">Jen Simmons</a> have been working hard to provide tutorials, so I won’t go into detail — but the results really do feel like magic.</p><p>Remember the old 3-column “Holy Grail” layout, with equal-height fixed-width sidebars and a fluid center? Here it is, in a few lines of code:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*q_zZMi0n7CXLTyCM1byGHQ.png" /><figcaption>See the Pen <a href="https://codepen.io/mirisuzanne/pen/0229f885f9a574c6d049b9d30dffc609/">CSS Grid Demo</a> by Miriam Suzanne (<a href="https://codepen.io/mirisuzanne">@mirisuzanne</a>) on <a href="https://codepen.io/">CodePen</a>.</figcaption></figure><p>In most cases, you can also provide a float, flexbox, or css-table fallback by wrapping your grid code in the @supports (display: grid) {} feature-query. You may still want Susy around to help with the fallback options, until all your required browsers catch up.</p><h4>Susy Columns &amp; grid-template-columns</h4><p>The Susy3 syntax has a lot in common with CSS Grid, because we want to start moving people in that direction.</p><p>Our columns setting now matches the basic features of CSS grid-template-columns – requiring a list of column-sizes, with the optional susy-repeat() shortcut function, matching the CSS repeat() option:</p><pre>// Symmetrical layouts <br>$grid-template-columns: repeat(12, 120px); <br>$columns: susy-repeat(12, 120px); </pre><pre>// Asymmetrical and mixed-unit layouts <br>$grid-template-columns: 120px repeat(4, 1fr) 30em; <br>$columns: 120px susy-repeat(4) 30em;</pre><p>Where CSS Grid uses the fr unit for fluid columns, we use unitless numbers. A column of width 2 in Susy will work similarly to a 2fr column in CSS. The default setting (susy-repeat(4)) defines a grid of 4 fluid columns, identical to a setting of 1 1 1 1.</p><p>Here are a few examples of different column settings:</p><pre>// 12-column em-based grid… (these have same result) <br>$columns: susy-repeat(12, 5em); <br>$columns: 5em 5em 5em 5em 5em 5em 5em 5em 5em 5em 5em 5em; </pre><pre>// holy grail grid from above… <br>$columns: 12em 1 200px; </pre><pre>// add more columns in the fluid area of holy grail… <br>$columns: 12em susy-repeat(4) 200px; <br>$columns: 12em 1 1 1 1 200px; </pre><pre>// repeated alternating columns… <br>$columns: susy-repeat(3, 8em 200px); <br>$columns: 8em 200px 8em 200px 8em 200px;</pre><p>This is a breaking change from Susy2, which allowed a single number 12 to represent 12 equal-and-fluid columns. That has been replaced with susy-repeat(12) for clarity and consistency with CSS.</p><p>Since Susy does not have direct access to the DOM, we generate calc() output for non-comparable and mixed fluid/static grids.</p><h4>Susy Gutters &amp; grid-column-gap</h4><p>Susy gutters haven’t changed at all since version two, although our new calc output allows you to mix units in new ways. This is similar to the CSS grid-column-gap property, accepting any gutter-length to place between columns. A unitless gutter setting will act as a fraction, on the same scale as any unitless columns. Gutters with units will remain static:</p><pre>// unitless fluid gutters… <br>$gutters: 0.25; </pre><pre>// static gutters… <br>$gutters: 10px;</pre><h3>Simplify Your Math</h3><p>If you can’t use CSS Grids yet, you might want Susy to help simplify grid-math calculations. Or you might be able to avoid that with a few tricks to simplify your math, and handle it manually.</p><h4>Box-Sizing: Border-Box</h4><p>First, fix the browser <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Introduction_to_the_CSS_box_model">box-model</a> by setting a global box-sizing:</p><pre>* { box-sizing: border-box; }</pre><p>I recommend setting this globally by default, no matter how you handle layouts. Border-box sizing means you can set a width, without worrying that padding or borders will ruin the calculation.</p><p>I’ve seen other global box-sizing snippets based on a value of inherit, and I strongly advise against it. There are good reasons that box-related properties like width, padding, and box-sizing don’t inherit the way fonts and colors do. Inheriting layout properties will only cause problems later.</p><h4>Padding for Gutters</h4><p>In reality, grid math is only complex when you add margin-gutters to the equation. Without gutters in the way, spanning 3 columns out of 12 is a simple fraction: percentage(3/12) in Sass. If you are able to drop the gutters, or even move them into padding rather than margins, you can avoid grid math entirely:</p><pre>// With Sass <br>.simple-grid { <br>  float: left; <br>  width: percentage(3/12); <br>} </pre><pre>/* Without Sass */ <br>.simple-grid { <br>  float: left; <br>  width: calc(3/12 * 100%);<br>}</pre><p>If you want to get really clever, you can build your own grid-system out of CSS <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/--*">custom properties</a> (aka variables):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hETN_tHLJW7etj7rs8cMag.png" /><figcaption>See the Pen <a href="https://codepen.io/mirisuzanne/pen/d05d2ea9339419df7070f9c393a9c080/">Calc() + Custom Properties</a> by Miriam Suzanne (<a href="https://codepen.io/mirisuzanne">@mirisuzanne</a>) on <a href="https://codepen.io/">CodePen</a>.</figcaption></figure><p>That will also work with css-tables, etc. Add any padding you like, and you have on-the-fly fluid grids without any third-party tools.</p><p>We’ve even built a nearly-complete Susy3 in pure CSS. This is a fun experiment, but I don’t recommend using it in production:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*M8jpGIxS9HTNub48OedJHw.png" /><figcaption>See the Pen <a href="https://codepen.io/mirisuzanne/pen/PboVrw/">SusyCSS Demo</a> by Miriam Suzanne (<a href="https://codepen.io/mirisuzanne">@mirisuzanne</a>) on <a href="https://codepen.io/">CodePen</a>.</figcaption></figure><p>Susy is designed to handle any layout, but if you are designing grids in pure CSS, it’s better to describe your actual needs more simply. Why solve all layout problems, when you can solve only the problems you have?</p><h4>Flexbox</h4><p>The great thing about flexbox is that it allows items to flex in specific relationship with each other, including equal-height columns and vertical centering. I often find that I don’t need Susy for a flexbox layout, because I’d rather define relationships instead of explicit grid-columns.</p><p>Here’s an example flexbox layout, without Susy:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QE4cOirV0uf-9cD_asjVJA.png" /><figcaption>See the Pen <a href="https://codepen.io/mirisuzanne/pen/657a71f05b9c044d0235bab212abdbdc/">Full-height Flexbox</a> by Miriam Suzanne (<a href="https://codepen.io/mirisuzanne">@mirisuzanne</a>) on <a href="https://codepen.io/">CodePen</a>.</figcaption></figure><p>If you do want to use Susy with flexbox to achieve more consistent grids, you only need to replace any flex-basis values with Susy’s span() function.</p><pre>.flex { <br>  flex: 1 1 span(3 of 12); <br>}</pre><p>I can’t think of any way to improve that with mixins, unless you want a few flexing defaults:</p><pre>@mixin span( <br>  $span, <br>  $config: () <br>) { <br>  flex: 1 1 span($span, $config);<br>  // split the gutter on each side of the element… <br>  padding: gutter($span, $config) / 2; <br>}</pre><h4>Calc to Mix Units</h4><p>Calc can also help you with mixed-unit grids, combining fluid and fixed columns and gutters. Because calc has access to the DOM in the browser, it can calculate the results of otherwise non-comparable units. This is a bit more fragile and manual than allowing grid or flexbox to do that work for you, but it can be a powerful fallback:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*p37Q_0XPGQRp62-LYKQlUg.png" /><figcaption>See the Pen <a href="https://codepen.io/mirisuzanne/pen/70b5a2cf411542e74d1cd42d5ddbe446/">Floats with Calc</a> by Miriam Suzanne (<a href="https://codepen.io/mirisuzanne">@mirisuzanne</a>) on <a href="https://codepen.io/">CodePen</a>.</figcaption></figure><h3>Introducing Susy3</h3><p>If you can’t simplify your math with padding-gutters and flexbox, you may still run into some difficult calculations that require complex grid math.</p><p>Susy3 is here to help calculate margin-gutters, asymmetrical grids, and mixed-unit calculations that are difficult to handle without CSS Grid. In those cases, Susy can turn this:</p><pre>$width: ($span + (($span - 1) * $gutter-width)) / ($columns + (($columns - 1) * $gutter-width));</pre><p>Into something more manageable:</p><pre>$width: span(3);</pre><h3>Grids on Demand</h3><p>One user asked if Susy3 forces you to build “an entire grid system from scratch”. While Susy certainly allows and facilitates that option, we’re really suggesting that you might not need a more complex system when you can access Susy’s math directly, on-the-fly.</p><p>The primary API of Susy3 consists of 2 functions, span and gutter, which you can use anywhere. Why build an entire system of mixins or classes when you can simply use these two functions wherever you need to align with the grid? This is more readable and more flexible than most grid systems, because no CSS properties are hidden from view:</p><pre>// class names are for demonstration only… <br>.float { <br>  width: span(3); <br>  margin-right: gutter(); <br>} </pre><pre>.flexbox { <br>  flex: 1 1 span(3); <br>  padding: 0 gutter() / 2; <br>} </pre><pre>.push-3 { <br>  margin-left: span(3 wide); <br>}</pre><p>If you find that too repetitive for your needs, you can build mixins to manage a few common patterns. Here’s a simple span mixin for floated grids, with margin-gutters on the right:</p><pre>@mixin span( <br>  $span, <br>  $config: $susy <br>) { <br>  width: span($span, $config); </pre><pre>  @if index($span, &#39;last&#39;) { <br>    float: right; <br>  } @else { <br>    float: left; <br>    margin-right: gutter();<br>   } <br>}</pre><p>You can also build a class system of your own, like you might find in other grid frameworks:</p><pre>.span { <br>  float: left; <br>  margin-right: gutter(); </pre><pre>  &amp;:last-child { <br>    margin-right: 0; <br>  } <br>} </pre><pre>@for $span from 1 through length(susy-get(&#39;columns&#39;)) { <br>  .span-#{$span} { <br>    width: span($span); <br>  } <br>}</pre><p>Only users with very specific and complicated needs may still want to “build an entire system” on top of Susy, in which case we’ll provide the syntax and math — but most use-cases should be handled by the functions we provide.</p><h3>Susy3 Configuration</h3><p>Global settings are still stored in the $susy map variable, just like Susy2, but now we only have four total settings. Here they are, with their default values:</p><pre>$susy: ( <br>  &#39;columns&#39;: susy-repeat(4), <br>  &#39;gutters&#39;: 0.25,   <br>  &#39;spread&#39;: &#39;narrow&#39;, <br>  &#39;container-spread&#39;: &#39;narrow&#39;, <br>);</pre><p>We’ve already introduced you to columns and gutters, so let’s take a look at the remaining options.</p><h4>“Spread” &amp; “Container-Spread”</h4><p>Spread isn’t new in Susy3, though it’s never been a global setting before. Susy2 managed spread for you, depending on a combination of other settings, like gutter-position. We wrote an article last week <a href="http://oddbird.net/2017/06/13/susy-spread/">explaining how spread works</a>.</p><p>To summarize, there are three spread options, and most people will only use two of them: narrow, wide, and (rarely) wider.</p><ul><li>A narrow spread has one less gutter than columns.</li><li>A wide spread has an equal number of columns and gutters.</li><li>A wider spread has one more gutter than columns.</li></ul><p>Susy needs to know how an element spreads, and also how containers spread. Note that Susy3 has no single container element. Every grid element acts as a container for its contents. When we talk about containers in Susy3, we’re referring to the parent context for a given element.</p><p>In Susy2, we would generate both spread values based on gutter-position, using roughly this logic:</p><pre>// gutter-position: before | after (margins) <br>$susy: ( <br>  &#39;spread&#39;: &#39;narrow&#39;, <br>  &#39;container-spread&#39;: &#39;narrow&#39;, <br>); </pre><pre>// gutter-position: split (margins) <br>$susy: ( <br>  &#39;spread&#39;: &#39;narrow&#39;, <br>  &#39;container-spread&#39;: &#39;wide&#39;, <br>); </pre><pre>// gutter-position: inside (padding) <br>$susy: ( <br>  &#39;spread&#39;: &#39;wide&#39;,  <br>  &#39;container-spread&#39;: &#39;wide&#39;, <br>);</pre><p>We also override those options when pushing, pulling, padding, and bleeding:</p><pre>.push-3 { <br>  margin-left: span(3 wide); <br>} </pre><pre>.pull-3 { <br>  margin-left: 0 - span(3 wide); <br>} </pre><pre>.pad-left-3 { <br>  padding-left: span(3 wide); <br>} </pre><pre>.bleed-left-3 { <br>  margin-left: 0 - span(3 wide); <br>  padding-left: span(3 wide); <br>}</pre><p>Susy3 defaults both values to narrow, which will work the same as CSS Grid and most other grid systems. If you’re not doing anything special, you can probably ignore these settings and move on.</p><p>Those are great defaults, but there are many reasons to override those settings on-the-fly to allow more flexibility where gutters are used. Learning to manage spread and container-spread in Susy3 will give you much more control over your layout experience.</p><h3>Susy3 Shorthand Syntax</h3><p>All Susy3 functions draw on the same shorthand syntax in two parts — separated by the word of. The first part describes a <strong>span</strong> width, location, and spread (in any order):</p><pre>// &lt;width&gt; &lt;location&gt; &lt;spread&gt; <br>$span: 2; <br>$spread: 3 wide; </pre><pre>// location is only needed with asymmetrical grids <br>$location: 3 at 2 narrow;</pre><p>You can also span explicit asymmetrical columns, using a column-list instead of span-count and location:</p><pre>// span 120px and one fraction of the container <br>$span: (120px 1) narrow;</pre><p>The second half of Susy’s shorthand describes the <strong>grid-context</strong> — or available space — with columns, container-spread, and gutters (in any order). None are required:</p><pre>// of &lt;columns&gt; &lt;container-spread&gt; &lt;gutters&gt; <br>$columns: of susy-repeat(6); <br>$spread: of (120px 1 1 14em) wide; <br>$gutters: of 12 set-gutters 2em;</pre><p>As you can see, the columns value here is identical to the global columns setting, with one difference. Unlike the global setting, shorthand column-context can be described as a unitless span-count rather than a list. A single unitless number for columns will be treated as a slice of the parent grid:</p><pre>// columns: susy-repeat(12, 120px) $shorthand: of 4; $meaning: of susy-repeat(4, 120px);</pre><p>If you are using asymmetrical grids, Susy can’t slice it for you. We provide a slice function with exactly the same shorthand syntax, but it returns a list of columns rather than a calculated width:</p><pre>// columns: 1 1 2 3 5 8 13 <br>$shorthand: of slice(first 4); <br>$meaning: of (1 1 2 3);</pre><h3>Primary API Functions</h3><p>Use the span() and gutter() functions to build the grid system that fits you best.</p><h4>Span</h4><p>The span() function will return the width of a span across grid-columns and any intermediate gutters. Apply the results to a width or flex-basis property to size your grid elements – or use it with padding, margin, and translateX() to move your elements around.</p><p>The span() mixin only requires a span width, but accepts the full shorthand:</p><pre>// Common Use… <br>$width: span(3); </pre><pre>// Much less common… <br>$width: span(first 3 wide of (1 1 2 3 5 8) wide set-gutters 20px);</pre><h4>Gutter</h4><p>Gutter will return the width of a single gutter, and only accepts the second half (context) of the shorthand — with or without of:</p><pre>// Common Use… <br>$padding: gutter(); </pre><pre>// With Context… <br>$padding: gutter(of 4); <br>$same-meaning: gutter(4);</pre><h3>Installation &amp; Other Options</h3><p>There are full installation instructions in the <a href="http://oddbird.net/susy/docs/">reference docs</a>, but you should note that we now provide the Susy API with or without prefixes:</p><pre>// unprefixed <br>@import &#39;&lt;path-to&gt;/susy/sass/susy&#39;; </pre><pre>// prefixed <br>@import &#39;&lt;path-to&gt;/susy/sass/susy-prefix&#39;;</pre><p>By default we assume you want Susy without any prefix, but importing susy-prefix will include susy- before all function names. You can use that if you are worried about name collisions with other functions in your project.</p><h4>SVG grids for debugging</h4><p>If you want help visualizing and debugging your grids, import the SVG Grid Plugin:</p><pre>// unprefixed <br>@import &#39;&lt;path-to&gt;/susy/sass/plugins/svg-grid&#39;; </pre><pre>// prefixed <br>@import &#39;&lt;path-to&gt;/susy/sass/plugins/svg-grid/prefix&#39;;</pre><p>The plugin adds an svg-grid-colors setting to your global defaults, which you can override in the $susy settings map. It also provides you with a new function, susy-svg-grid(), which will return an inline svg image for use on the background of an element:</p><pre>.container { <br>  background: susy-svg-grid() no-repeat scroll; <br>}</pre><p>SVG grids are much more reliable than the old background-image gradient, because background gradients have subpixel rounding issues.</p><h4>Building your own Susy system</h4><p>Once you get the basics, Susy3 also provides tools to help you build your own mixins and define your own system, if that’s something you need. See the <a href="http://oddbird.net/susy/docs/plugin-utils.html">Plugin Utilities</a> for more detail.</p><h3>Feedback is Always Welcome</h3><p>We know we’re taking some risks with this release, not providing what most people expect from a grid system. Some may prefer working with Susy2, and that’s a solid option as well. Over time, we hope the CSS Grid module will replace all third-party systems.</p><p>While we’re confident that this is a step forward for Susy, we never claim to know what’s best for you. We’d love your feedback, and real-world examples of how you make Susy work for you.</p><p>We’ll keep providing our own tutorials and demos, based on the questions we hear most, but we also love linking to your <a href="http://oddbird.net/susy/sites/">sites built with Susy</a>, and any <a href="http://oddbird.net/susy/articles/">third-party tutorials</a> that we hear about. <a href="http://oddbird.net/contact/">Contact us</a>, or <a href="https://github.com/oddbird/oddsite/tree/master/content/susy">submit a pull request</a>. You can also talk to <a href="https://twitter.com/sasssusy">SassSusy</a> or <a href="https://twitter.com/oddbird">OddBird</a> on twitter, or join our <a href="http://friends.oddbird.net/">public Slack</a> (with a #Susy channel). We’re excited to hear from you!</p><p><em>Originally published at </em><a href="http://oddbird.net/2017/06/28/susy3/"><em>oddbird.net</em></a><em> on June 28, 2017.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a0127e594b53" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/welcome-to-susy3-a0127e594b53">Welcome to Susy3!</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Understanding Spread in Susy3]]></title>
            <link>https://medium.com/oddbird-web/understanding-spread-in-susy3-228b2a36c444?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/228b2a36c444</guid>
            <category><![CDATA[susy3]]></category>
            <category><![CDATA[susy]]></category>
            <category><![CDATA[css]]></category>
            <category><![CDATA[grid]]></category>
            <category><![CDATA[sass]]></category>
            <dc:creator><![CDATA[Miriam Suzanne]]></dc:creator>
            <pubDate>Thu, 06 Jul 2017 20:47:02 GMT</pubDate>
            <atom:updated>2017-07-07T17:57:43.585Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Overview of one Susy3 core concept</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*s9WwMRsUPOPDdb9fpiv1pg.jpeg" /></figure><p>Spread isn’t new to <a href="http://oddbird.net/susy/">Susy3</a>, <a href="http://oddbird.net/susy/docs/en/latest/settings/#spread">or even to Susy generally</a>, but its full power is usually hidden behind other settings (like gutter-position in Susy2), or opinionated assumptions about your grid. We didn’t invent the idea behind spread – every grid system has to make these decisions – but we haven’t seen anyone else talking about it explicitly.</p><p>In Susy3 we’ve tried to move in the other direction — naming spread, and making it central to the API — giving you full control over the math.</p><h3>Spread on Containers</h3><p>Container-spread describes how a grid-parent (or container) handles available gutters. Most grids only put gutters between the columns. That means there will be one less gutter than there are columns. We call that a narrow container-spread, and make it the default.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*kJQWKWkHUo-Brphg.jpg" /></figure><p>Some grids use “split” gutters, with half of a gutter on either side of a column — forming full-gutters between columns, and an extra half at the edges. Mathematically, that means we have an equal number of gutters and columns. We call that a wide spread.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*1IT056F7PLpBdnfi.jpg" /></figure><p>Occasionally, a grid will have full gutters on both sides, meaning there is one more gutter than columns. We call that a wider spread.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*YfhoewuuNJwgZrMA.jpg" /></figure><h3>Spread on Spans</h3><p>Spread describes the same concept as it relates to internal grid-spanning elements. In most systems, including the new <a href="http://oddbird.net/2016/09/19/css-grid-layout/">CSS Grid module</a>, all spans are narrow – meaning they only span intermediate gutters.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*bKA-D58GHtWpyxs_.jpg" /></figure><p>Occasionally it’s useful to span as many gutters as columns — a wide spread – if you have split-padding gutters, for example, or if you want elements to touch at certain places, or if you are pushing and pulling elements in the grid.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*eNpBFZpI2L1BlaZr.jpg" /></figure><p>It’s rare that you need to span a wider spread, but we’ll let you decide if it’s useful.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*VtDa4wbwOSr8IPcm.jpg" /></figure><h3>Fluid Context</h3><p>In Susy3 there is no single grid “container” element that receives special treatment. Instead, container spans are described in the same syntax as any other span — and any element containing other grid-aligned elements is a container.</p><p>Fluid-span calculations require understanding both the container width and span-width. The Sass math looks like this:</p><pre>$fluid-width: percentage($span-width / $container-width);</pre><p>For that reason, it’s important to be explicit with Susy about the spread of both containers and spans, when you are building fluid grids. In the Susy3 syntax, that looks like:</p><pre>$width: span(3 wide of 6 narrow);</pre><p>If it comes before of, it describes the span. If it comes after of, it describes the container. In most cases, there will be a sensible default for both values, which you can set in the global settings:</p><pre>// Both default to &quot;narrow&quot;… <br>$susy: ( <br>  &#39;spread&#39;: &#39;narrow&#39;, <br>  &#39;container-spread&#39;: &#39;narrow&#39;, <br>);</pre><h3>Common Use Cases</h3><p>Commonly, all spans have a narrow spread. In fact, the CSS Grid module doesn’t provide any way to span across extra gutters. You would have to achieve a wide or wider span using negative grid-gap-sized margins.</p><p>There are times when you simply want to span across a gutter, for the sake of style. But there are other common reasons to span extra gutters. Let’s look at a few.</p><h4>Pushing, Pulling, &amp; Padding Elements</h4><p>It’s sometimes necessary to “push” and “pull” elements out of their usual flow position, or add grid-aligned padding. You can do that by using the span functions on the margin or padding of an element. Push with positive left margins, pull with negative right margins, and pad either side with the padding property.</p><p>In all those cases, you’ll probably need a wide span in order to align your content with the proper column:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*W2NmkelQshYJv8BWGeYRVQ.png" /><figcaption><em>See the Pen </em><a href="https://codepen.io/mirisuzanne/pen/BZjMXK/"><em>Susy3: Pushing &amp; Pulling</em></a><em> by Miriam Suzanne (</em><a href="https://codepen.io/mirisuzanne"><em>@mirisuzanne</em></a><em>) on </em><a href="https://codepen.io/"><em>CodePen</em></a><em>.</em></figcaption></figure><h4>Split Gutters</h4><p>Some grid systems use “split” gutters, with half a gutter on either side of an element. That will add an extra gutter to your total grid width, giving your common container a wide spread. If you are using split gutters, you likely want to set container-spread: wide in your global settings.</p><p>Here’s a wide container, with narrow spans and split gutters:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ebzTRgIejsVZDNqpoY3j0A.png" /><figcaption><em>See the Pen </em><a href="https://codepen.io/mirisuzanne/pen/bREZWW/"><em>Susy3: Split Gutters</em></a><em> by Miriam Suzanne (</em><a href="https://codepen.io/mirisuzanne"><em>@mirisuzanne</em></a><em>) on </em><a href="https://codepen.io/"><em>CodePen</em></a><em>.</em></figcaption></figure><p>If you move the gutters inside, using the padding property, both spread and container-spread may need to be wide. I say “may” because it also depends on your border-box-sizing. That’s a whole new article, and honestly: padding gutters make the math much simpler. If you use padding gutters, there’s a good chance you don’t need Susy.</p><p>More about that in my next post. Until then: Happy coding!</p><p>Keep an eye out for the <a href="http://oddbird.net/susy/">Susy3 release</a>, coming soon! Follow us on <a href="https://twitter.com/oddbird">Twitter</a>, join our <a href="http://friends.oddbird.net/">public Slack channel</a>, or <a href="http://oddbird.net/contact/">contact us</a> online. We’re excited to hear from you!</p><p><strong>We want to hear all about your software ideas.</strong> Fill out our <a href="http://oddbird.net/contact/">contact form</a>, join our <a href="http://friends.oddbird.net/">public Slack chat</a>, or tweet <a href="http://twitter.com/oddbird">@oddbird</a> to start the conversation.</p><p><em>Originally published at </em><a href="http://oddbird.net/2017/06/13/susy-spread/"><em>oddbird.net</em></a><em> on June 13, 2017.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=228b2a36c444" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/understanding-spread-in-susy3-228b2a36c444">Understanding Spread in Susy3</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Serializing Things for Celery]]></title>
            <link>https://medium.com/oddbird-web/serializing-things-for-celery-3e71ab94e28f?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/3e71ab94e28f</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[django]]></category>
            <category><![CDATA[serialization]]></category>
            <category><![CDATA[celery]]></category>
            <dc:creator><![CDATA[Kit]]></dc:creator>
            <pubDate>Tue, 16 May 2017 21:15:08 GMT</pubDate>
            <atom:updated>2017-04-07T16:53:40.381Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LsOdBp6H7XIePAL8IEKLBw.jpeg" /></figure><p>Many Django apps need some kind of out-of-band processing. Perhaps you have to make calls to a separate API server, and don’t want to nest the latency of HTTP calls. Or perhaps you need to perform a slow and complex post-processing step on user-submitted data. Whatever it is, you can’t just put everything in your web processes. Some things demand worker processes consuming tasks from a queue.</p><p>Typically we use <a href="http://docs.celeryproject.org/en/latest/index.html">Celery</a> for this, though increasingly <a href="https://channels.readthedocs.io/en/stable/">Django Channels</a> is emerging as a viable option. In either case, there are issues that arise from the use of a task queue broker; because of the indirection that the broker (be it an <a href="https://www.rabbitmq.com/">AMQP</a> server or <a href="https://redis.io/">Redis</a> or whatever) introduces, you can’t share memory. Without sharing memory, you can’t share in-memory objects. So, you somehow have to get data between the web requests and the worker processes.</p><p>If it’s just primitive data, that’s fine, you can serialize it. But what if it’s not? What if you have a Django model that you want to pass to a task? This is hardly an uncommon need, but there are a few ways to approach the problem.</p><p>First, of course, you can use the pickle Celery task serializer. This isn’t terrible, but pickle does open you up to some <a href="https://blog.nelhage.com/2011/03/exploiting-pickle/">security concerns</a>. You can mitigate them, but unless you feel confident that you know what you’re doing, it’s best to avoid exposing yourself to them in the first place. In the same way that you <em>can</em> sanitize all your database inputs and assemble DB queries through string concatenation – but would be well-advised to use prepared statements – you <em>can</em> ensure that everything that touches pickle is adequately sanitized. I, for one, prefer to avoid using it, and save myself the worry.</p><p>To ensure we don’t risk executing arbitrary code, we can tell Celery to use the JSON serializer:</p><pre>CELERY_TASK_SERIALIZER = &#39;json&#39;</pre><p>But now we can’t pass full Python objects around, only primitive data. If we try to pass something that can’t be JSON-serialized, we’ll get a runtime error.</p><p>(This has another use, incidentally: it frees us to make our worker and web processes in different languages. That’s beyond what I’ll talk about here, but it’s worth thinking about!)</p><h3>Getting a Django Model Between Processes</h3><p>But, we want to pass our models around! How can we do this?</p><p>The usual approach is to define tasks to take the model ID as a parameter, and just pass that. If I need a Foo, I’ll have a parameter foo_id that I pass to the task. Then in the task, I’ll access the DB and pull that Foo instance out.</p><p>That’s fine. It doesn’t quite cover all situations, though.</p><h3>What If I Don’t Know What Model I’m Passing?</h3><p>This is a case I’ve run into. I had a task that had to be run on three different models (specifically, Question, Answer, and Comment) that all had a body attribute. I could duck-type my way around this under most circumstances, but when it came to passing them through the task-broker barrier, I had to have some way to know just what type of model I was working with.</p><p>There are three obvious approaches:</p><p>The first, which is also the worst, is to have a version of the task for each type. You might call this “the poor man’s parametric polymorphism,” but it isn’t really polymorphism at all, and it tends to lead to code duplication. Don’t do this.</p><p>(Yes, you can avoid much of the code duplication by well-decomposed tasks and functions, and making a series of shims that make assumptions about the types of the arguments. Still don’t do this.)</p><p>Alternatively, you could add three (or however many) different arguments to the task:</p><pre>@task()<br>def some_task(foo_id=None, bar_id=None, baz_id=None):<br>    if foo_id is not None:<br>        obj = Foo.objects.get(pk=id)<br>    elif bar_id is not None:<br>        obj = Bar.objects.get(pk=id)<br>    elif baz_id is not None:<br>        obj = Baz.objects.get(pk=id)<br>    else:<br>        # Do some error logging and return.<br>        return<br>    # Operate on obj</pre><p>This is <em>tolerable</em>, but it adds a lot of boilerplate. You get a function signature that increases in length as the number of possible types increases, and you get a long if/elif/else chain that increases at the same rate. Neither of these have much to do with your task’s logic, but they take up a lot of brainshare.</p><p>Also, with both this approach and the previous approach, you have to know at the call site what sort of ID you’re passing in. This is a mixed blessing. It makes the code very legible, but it does impede managing things programmatically.</p><p>The third option — my favorite — is to simply tell the task what model you need:</p><pre>from django.apps import apps</pre><pre>@task()<br>def some_task(model_name, model_id):<br>    Model = apps.get_model(&#39;django_app_name.{}&#39;.format(model_name))<br>    obj = Model.objects.get(pk=model_id)<br>    # Operate on obj</pre><p>Note the crucial piece here: django.apps.apps.get_model. It takes a model identifier, which is django_app_name.ModelName. The django_app_name is the last dot-separated part of whatever you put in INSTALLED_APPS. The ModelName is the name of the class in the models module in that app.</p><p>For added delight here, you can even get the model name automatically in a mixin to your models:</p><pre>class SomeMixin:<br>    # Assuming that you want to trigger the task on save:<br>    def save(self, *args, **kwargs):<br>        ret = super().save(*args, **kwargs)<br>        some_task.apply_async((<br>            self.__class__.__name__,<br>            self.pk,<br>        ))<br>        return ret</pre><p>As a final word to the wise, it’s worth noting that this entire database-mediated approach opens you up to certain timing risks. Data can skew, and you expose yourself to potential race conditions. Sometimes that’s not an issue, and sometimes it’s just an acceptable cost. But in any case, it’s worth keeping in mind.</p><h3>What If I Need Something That’s Not a Model?</h3><p>Perhaps you have business-logic class instances which are never stored in the database*. If you can’t, won’t, or don’t want to use the DB as a persistent store for your data — which you then inflate into a full object — there are other ways to pass objects through the task-broker bottleneck.</p><p>They all boil down to separating the primitive data from the methods and logic. Think of it like passing the <em>record</em> or <em>struct</em> through, not the whole class.</p><p>So if that’s the goal, you could make custom JSON encoders and decoders that know how to traverse your classes. But that’s a pain. Let’s see if we can write as little code not related to our actual business logic as possible.</p><p>One approach I like is to use the <a href="https://attrs.readthedocs.io/en/stable/">attrs</a> library. It lets you define your business logic class like so:</p><pre>import attr</pre><pre>@attr.s<br>class SomeClass(object):<br>    foo = attr.ib()<br>    bar = attr.ib()</pre><pre>    def some_method(self):<br>        pass</pre><p>And then you can easily serialize an instance:</p><pre>import attr</pre><pre>inst = SomeClass(<br>    foo={&#39;hi&#39;: &#39;there&#39;},<br>    bar=SomeClass(foo=1, bar=False),<br>)<br>attr.asdict(inst)<br># {&#39;foo&#39;: {&#39;bar&#39;: False, &#39;foo&#39;: 1}, &#39;foo&#39;: {&#39;hi&#39;: &#39;there&#39;}}</pre><p>And just as importantly, you can pass that serialized data to the task, and inflate it:</p><pre>def some_task(some_class):<br>    inst = SomeClass(**some_class)</pre><p>How have you handled object serialization in your projects? We’d love to hear your thoughts on <a href="https://twitter.com/oddbird">Twitter</a>, on our <a href="http://friends.oddbird.net/">public Slack channel</a>, or through our <a href="http://oddbird.net/contact/">handy contact form</a>. Happy coding, and serialize safely!</p><p>Header image courtesy of <a href="https://www.flickr.com/photos/doodledan/5623812207/in/photolist-9yXvrr-9W139J-rPYrZp-7BkxKT-aWPwCP-pkqpEu-8iimgZ-pkpuKF-pkqpm1-nvKV6q-4mVgtJ-pzSGYY-6qjB4E-pBVzNr-8JG1Ja-6qfuMn-pBTApN-bo34GB-pBUVaK-7NVtXW-5XJRQK-dM3hhG-aWPxoT-dQD6zK-pBURD6-pBVjRH-9VXd56-5x1PMy-7NVt7U-5qMsjU-pkqPdu-pkqWKT-4vkwsh-8WvmVA-3NBhJG-pkqCzq-pBD7rv-aWPvP4-pBUNx6-dLWDRk-7NRvR6-aWPuQB-7jnkHb-8oZuCB-DPKaV-pkqtML-pdG1Hz-6qfsrZ-pBCy9e-8Zhx4A">Dan Morelle</a>.</p><p>* You are keeping in mind that your <em>data model</em> and your Django <em>Models</em> aren’t the same, right? Django models are persistence-layer mappings, that you can bolt some additional logic to. Your data model may be much more!</p><p><em>Originally published at </em><a href="http://oddbird.net/2017/03/20/serializing-things/"><em>oddbird.net</em></a><em> on March 20, 2017.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3e71ab94e28f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/serializing-things-for-celery-3e71ab94e28f">Serializing Things for Celery</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A Rebase-Centric Model of Collaborative Git Use]]></title>
            <link>https://medium.com/oddbird-web/a-rebase-centric-model-of-collaborative-git-use-e548978d964d?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/e548978d964d</guid>
            <category><![CDATA[git]]></category>
            <category><![CDATA[workflow]]></category>
            <category><![CDATA[rebase]]></category>
            <category><![CDATA[github]]></category>
            <dc:creator><![CDATA[Kit]]></dc:creator>
            <pubDate>Tue, 16 May 2017 21:15:00 GMT</pubDate>
            <atom:updated>2017-04-07T16:54:01.684Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/1*6S42ROjUUvsV1LSVrk_sGQ.jpeg" /></figure><p>There are <a href="https://grimoire.ca/git/pull-request-workflow">many</a> <a href="http://nvie.com/posts/a-successful-git-branching-model/">ways</a> <a href="https://www.atlassian.com/git/tutorials/comparing-workflows/centralized-workflow">to</a> <a href="https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows">use</a> <a href="http://blog.endpoint.com/2014/05/git-workflows-that-work.html">git</a>. It’s sometimes said that git is not actually a version control system, but rather <a href="http://marc.info/?l=linux-kernel&amp;m=111293537202443">a content-addressable filesystem, used to track directory trees</a>. So, given that it’s only a version control system inasmuch as you impose a methodology on it, it’s worth it to play with some different methodologies.</p><p>One common way to use git is with a lot of merging between branches, but if you don’t like the tangled web of history that creates, I’m going to propose a rebase-centric model. It’s a trade-off: a little harder to make, but a lot easier to understand when you need to come back to it later.</p><p>Now that you have enough links to take you away from this post for a day at least, let’s get started.</p><p>First, let’s unpack what I said above. Be prepared for some graph theory terms. You’ve seen these sorts of charts in every bit of git documentation you look at, right?</p><pre>      A---B---C topic<br>     /         \<br>D---E---F---G---H master</pre><p>(From <a href="https://git-scm.com/docs/git-merge">https://git-scm.com/docs/git-merge</a>.)</p><p>This is a simple directed acyclic graph. Each node (except for D, the root node) has one or more parents. No node is an ancestor of itself. But in git, these nodes aren’t just abstractions: they carry data. Specifically, they carry change sets and commit messages.</p><p>Because there are changesets in the nodes, that implies that a traversal from the root node to any other node will result in a description of a certain end-state for the files in the repository, and that a traversal to the terminal node marked with a particular branch will result in a description of the files in the latest state of that branch. <strong>If the nodes were re-arranged, that could change the resulting state, depending on the particular changesets involved.</strong></p><p>When you rebase, you “rewrite history” and transform, for example, this DAG:</p><pre>      A---B---C topic<br>     /<br>D---E---F---G master</pre><p>Into this DAG:</p><pre>              A&#39;--B&#39;--C&#39; topic<br>             /<br>D---E---F---G master</pre><p>(Examples from <a href="https://git-scm.com/docs/git-rebase">https://git-scm.com/docs/git-rebase</a>.)</p><p>The commits in the topic branch are labeled with prime signs after the rebase to denote that they are, in a sense, the “same” commits, but because they have a different ancestry, describe a different set of states – specifically, states that incorporate commits F and G. If there are conflicts between the rebased commits and their new ancestry, git will prompt you to resolve those before continuing the rebase.</p><p>All of this, so far, is just to explain rebasing so you can feel really comfortable with it. Rewriting your own history is fine and safe. But what we really care about is rewriting history that other people can access.</p><h3>Remotes, Upstreams, and Feature Branches</h3><p>Pretty much everything written about git warns you not to rebase any commits that are shared with other people or systems. It is presented as a cardinal sin and something that will get you shunned by all serious git users. So, let’s talk about how to do it!</p><p>The fundamental reason you’re enjoined against doing it is that it generates more work for everyone else to get their local repositories into a good state again. That is not something I mean in any way to contradict. If you are going to be pushing rewritten history to a shared remote, you <em>must</em> have everyone on-board and with a common understanding of the process you’re using and how to keep their local histories in order.</p><p>I find that the best way to avoid nasty situations with rewritten history consists of two principles:</p><ol><li>Maintain sole ownership of branches: only one person writes to a given branch, and if you need to collaborate, pull requests into the other person’s branch are the way to go.</li><li>Maintain a strong distinction between read-only upstream branches and writable feature branches.</li></ol><p>These principles won’t work for every team and every situation, so you have to decide if this approach is right for you.</p><p>Let’s see what this looks like in practice.</p><p>Let’s say Bao and Robin are collaborating on a project, through GitHub. There are many ways to manage the remotes, but we’ll take a simple approach right now: they each have a copy of the repo on their own computers, and they are sharing one repo on GitHub. When Bao runs git remote -v, they get:</p><pre>origin git@github.com:example/project.git (fetch)<br>origin git@github.com:example/project.git (push)</pre><p>And Robin would see the same. They can each push to that remote, too, but they have an understanding that they won’t push branches that don’t <em>belong</em> to them.</p><p>As they work on the project, they will end up with branches that look like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/549/0*oZnURIn4utFMqISv.png" /></figure><p>Black commits are on master, blue are by Bao, coral are by Robin. They both start their work off of the current state of master. Bao has a sort of short and straightforward branch. Robin is working on something longer and more complex, and Bao jumps in to help a little, branching off of Robin’s branch when it’s at commit G, while Robin keeps working on it. Bao will eventually pull-request their changes back in.</p><p>But what if Robin realizes that their work really depends on the work Bao did and already merged into master? They can just rebase their branch on to that work:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/949/0*5uBAUlBqBaEgdBf-.png" /></figure><p>On Bao’s machine, this looks like:</p><pre>$ git fetch<br>$ # Update local information on upstream branch.<br>$ # Because Bao *never* commits on this branch, every merge<br>$ # should be a fast-forward merge, but let&#39;s use --ff-only<br>$ # just to be sure:<br>$ git checkout robin-feature &amp;&amp; git merge --ff-only<br>$ # See what the world looks like at this moment:<br>$ git checkout bao-fix<br>$ git branch -vv<br>* bao-fix   ca1f618 [robin-feature: ahead 4, behind 9] short message<br>  robin-feature  fc58298 [origin/robin-feature] short message<br>  master    d1ef2a3 [origin/master] Merge Bao&#39;s work</pre><p>This leaves Bao’s branch attached to the old commit G, which had been in Robin’s branch before the rebase. But because Bao’s branch tracks Robin’s branch as its upstream, Bao can, with fresh remote tracking info on their local computer, just run git rebase and get this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*5egl5C807SRxtSUm.png" /></figure><p>Again, on Bao’s machine:</p><pre>$ # Because the bao-fix branch has robin-feature as an upstream:<br>$ git rebase<br>$ git branch -vv<br>* bao-fix       ca1f618 [robin-feature: ahead 2] short message<br>  robin-feature fc58298 [origin/robin-feature] short message<br>  master        d1ef2a3 [origin/master] Merge Bao&#39;s work</pre><p>Note that Bao’s work is now coming off of K’, not G (or G’). This is because it tracks Robin’s <em>branch</em> as its upstream, not a specific commit in that branch. Since branches can wholly change what commits they consist of, this is both necessary and useful.</p><p>Bao can force-push that back up to GitHub (because only Bao writes to that branch, this is safe), Robin can merge it in, and then the whole thing can be merged back into master:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*1u8aeGkA4kyh_cUV.png" /></figure><p>Note: if anyone has merge conflicts at any point, they have to resolve them, and those rebased commits (with the prime marks) can differ from their original renditions by whatever it takes to resolve that merge conflict.</p><h3>Caveats</h3><p>This approach can make your git history <em>much</em> more useful as a historical artifact, as a way to see not just what the code was like at any given point, but what the intent of that state of the code was. But unless everyone on the team is on board with this, and understands it, you risk the proverbial shooting yourself in the foot.</p><p>If you use git, you should be familiar with how to use the <a href="https://git-scm.com/docs/git-reflog">reflog</a> to back yourself out of ah-damn-what-did-I-just-do situations. That is still true here; if you are not perfectly comfortable with rebase, having a way to <em>undo</em> is crucial.</p><p>There are some git defaults you may want to set to make this pattern easier:</p><pre>git config merge.defaultToUpstream true<br>git config branch.autosetupmerge always</pre><p>Honestly, they’re useful defaults to set in any case! (Hat-tip to <a href="https://grimoire.ca/git/config">Owen</a> for these defaults, and a lot of thinking about git!)</p><p>Try it out on a small project, and see if you like it. It’s even better if you write <a href="http://alistapart.com/article/the-art-of-the-commit">good commit messages</a>. If you don’t go spelunking through your git history often to understand past choices, then let this be your excuse.</p><h3>What Do the OddBirds Do?</h3><p>We actually use a merge-centric flow, the kind you are likely more familiar with! We avoid pushing rebased branches to remotes, and don’t have strong ownership of branches. If more than one of us is working on something at a time, whoever pushed to the remote first will have their work merged in to whatever anyone else is doing, before that other person pushes the result of their merged work to the remote.</p><p>This is convenient enough for us, but it really is motivated by the shape of our team; we have specialists all along the design-frontend-backend continuum, and frequently want to rapidly intertwine our work many times in a day as we coordinate changes all along that spectrum.</p><p>Still, some of us have used this rebase model successfully before and think it’s worth trying out!</p><p><em>Originally published at </em><a href="http://oddbird.net/2017/1/5/git-rebase/"><em>oddbird.net</em></a><em> on January 5, 2017.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e548978d964d" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/a-rebase-centric-model-of-collaborative-git-use-e548978d964d">A Rebase-Centric Model of Collaborative Git Use</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Django, Background Processes, and Keeping Users in the Loop]]></title>
            <link>https://medium.com/oddbird-web/django-background-processes-and-keeping-users-in-the-loop-fb72a37e6385?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/fb72a37e6385</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[django]]></category>
            <category><![CDATA[django-channels]]></category>
            <category><![CDATA[websocket]]></category>
            <category><![CDATA[celery]]></category>
            <dc:creator><![CDATA[Kit]]></dc:creator>
            <pubDate>Tue, 16 May 2017 21:14:19 GMT</pubDate>
            <atom:updated>2017-07-06T20:34:58.360Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How to let users know about a task status change with out-of-band processing,</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UejB-0E232JN_1Dp_a8KZQ.jpeg" /></figure><p>In my <a href="http://oddbird.net/2017/03/20/serializing-things/">last post</a>, I talked about how a modern web app needs background worker processes. One way or another, you’ll have some things you need to do that are slower than you can do in a request/response cycle, and so you’ll want to handle them out of band. Have the API return a simple 202 ACCEPTED and move on with your life, right?</p><p>Well, sometimes you want to tell users about the state of those background processes. You might want to say “it’s done!”, or “it’s failed!”, or even just to acknowledge that it’s taking a long time, but still going. And just saying “they can refresh the page” isn’t always enough. (Though, sometimes it is!)</p><p>I’m going to talk about different ways you can do this.</p><p>First I’ll talk about how I would do it using Celery. But django-channels provides some cool new options for handling background processes, so I’ll cover that too.</p><h3>Celery</h3><p>Imagine we have a long-running background process, something that can take up to a minute under normal circumstances, maybe more under exceptional load. We make a Celery task to handle it, and now we want to let the user know what state it’s in.</p><p>The most simple (or simplistic) approach can be to use the database to store state. You can do this with Celery’s database result backend, or a custom task state model that you periodically update. Imagine something like this:</p><pre>@app.task<br>def my_task(some_arg):<br>    # some unique identifier, that you can recover outside the task:<br>    task_id = get_task_id_based_on_arg(some_arg)<br>    state, _ = TaskState.objects.get_or_create(task_id=task_id)<br>    total = len(some_arg)<br>    for i, elem in enumerate(some_arg):<br>        process_elem(elem)<br>        # Every 100 elements, update the percentage processed:<br>        if i % 100 == 0:<br>            state.percent_done = (i / float(total)) * 100<br>            state.save()</pre><p>Then in your views, you can retrieve the appropriate TaskState and show how much has been processed. Sometimes that’s a good approach, but usually I think that’s pretty clunky. It can thrash the database, leave records lying around if things die halfway through, and still doesn’t give you a smooth experience; your user has to refresh to see updates.</p><p>As an aside, it might be tempting to do something like this with the Django <a href="https://docs.djangoproject.com/en/1.11/ref/contrib/messages/">messages framework</a>. However, adding and retrieving messages requires the request object. Even the pickle serializer can fail to serialize the request object. I would strongly recommend saving yourself the time and trouble, and using anything but messages for this.</p><p>So what if you want real-time updates? What if that page refresh is bumming you out?</p><p>A nice option is something like <a href="https://pusher.com/">Pusher</a>. They provide a service that you can push to from inside your app (in the request/response cycle, or in a background task) using a nice Python library, and some JS to get your users talking to their realtime websocket-y servers, to get those updates. Their JS library even includes sensible fallbacks for when websockets aren’t available. The one caution is that their prices take a curve that can be a bit steep for some situations; if developer time is cheaper than ongoing service costs, then it might be worth rolling your own websocket solution. Which brings us to our next section.</p><h3>Django-Channels</h3><p>If you are using the newer Django Channels package for background tasks, this has the added benefit of making it possible for you to make and manage your own websockets connections.</p><p>For fuller explanation of Channels itself, see the <a href="https://channels.readthedocs.io/en/stable/">channels docs</a> or Jacob Kaplan-Moss’s <a href="https://blog.heroku.com/in_deep_with_django_channels_the_future_of_real_time_apps_in_django">excellent blog post</a> on the subject. I’ll give a brief overview here, though.</p><p>I find it helps to think of Channels as a generalization of Django’s view system. Instead of a urls.py with a urlpatterns attribute, you have a routing.py with a channel_routing attribute. Instead of mapping paths to views, it maps channel types to consumers. Channel types can include well-known ones like websocket events, or ad-hoc ones like custom background tasks.</p><p>(All your views and URLs can still be there in your project, untouched, too. This isn’t instead of all that, it’s in addition.)</p><p>Because Channels operate outside the usual request/response cycle, sending a reply on a channel is a little harder. It can’t operate simply through a function’s return. Instead, you have to .send on Channels, or more flexibly, Groups. (A Group just allows you to send to multiple consumers at once, if necessary.)</p><p>So, for our purposes, your channel_routing should have, at a minimum, these values:</p><pre>channel_routing = [<br>    route(&quot;websocket.connect&quot;, websocket_connect),<br>    route(&quot;websocket.receive&quot;, websocket_receive),<br>    route(&quot;websocket.disconnect&quot;, websocket_disconnect),<br>    route(&quot;my-background-task&quot;, my_background_task),<br>]</pre><p>The first three are consumers for handling basic websocket operations. The last one is whatever long-running task you want to run in the background.</p><p>You can then call the background task in a view:</p><pre>Channel(&#39;my-background-task&#39;).send(some_arguments)</pre><p>Be sure that there’s some stable way to identify the Group that you need to send to. It might be as simple as passing in the username of the logged-in user who kicked off the task, or it might be based on a process UUID that’s in the view’s path, or something else. Whatever it is, when the user’s browser makes a websocket connection on page load, you’ll want to add that reply channel to the Group:</p><pre>def websocket_connect(message):<br>    # Accept connection<br>    message.reply_channel.send({&quot;accept&quot;: True})<br>    Group(get_group_id_from(message)).add(message.reply_channel)</pre><p>On the front-end, you should have something like this:</p><pre>socket = new WebSocket(&quot;ws://&quot; + window.location.host);<br>socket.onmessage = show_some_toast_for(message);<br>// Call onopen directly if socket is already open<br>if (socket.readyState == WebSocket.OPEN) socket.onopen();</pre><p>And now you can push messages to users yourself:</p><pre>def my_background_task(message):<br>    # ...<br>    Group(get_group_id_from(message)).send({<br>        &quot;text&quot;: some_status_update,<br>    })<br>    # ...</pre><p>And the front-end JavaScript will receive it over the websocket. Display it in a toast or other style of your choosing, and you’re good to go!</p><p>Have you tried out Channels yet? Do you have better ideas for what to do with websockets? Let us know <a href="https://twitter.com/oddbird">Twitter</a>, on our <a href="http://friends.oddbird.net/">public Slack channel</a>, or through our <a href="http://oddbird.net/contact/">handy contact form</a>.</p><p>(Header image from <a href="https://www.flickr.com/photos/tekniskamuseet/6984485227/in/photolist-bDcj86-bCJAcK-kuma4q-a84vA7-m9MW4X-bpxan1-5MqJ6t-qveiAk-9HUcBY-bK7X7H-bDc9G8-H4CRif-ecoWKZ-gxg8pi-gxfwdA-gxg9yo-gxganN-gxgxhM-gxgdCL-SRK9sh-g2gW4S-eWUwc-Tj1w3G-SXLqUw-kWJsG1-5nuzrQ-o6Gn1v-dn8r3R-dn8u4y-RCNiKJ-dnp4W6-82121J-Sk9roq-dn7sPf-SiTrzM-SgfCro-TmmueP-dnpnsi-SgfEp1-dnpYB5-SRnywU-RF1mQK-JP5Pxc-SFuTr9-4BrHoH-Si5fuK-Sivnqi-KKuKjn-KjmLNW-KCAU1X">Tekniska Museet</a>.)</p><p><em>Originally published at </em><a href="http://oddbird.net/2017/04/17/async-notifications/"><em>oddbird.net</em></a><em> on April 17, 2017.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fb72a37e6385" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/django-background-processes-and-keeping-users-in-the-loop-fb72a37e6385">Django, Background Processes, and Keeping Users in the Loop</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Making Function Calls Across Sass Versions]]></title>
            <link>https://medium.com/oddbird-web/making-function-calls-across-sass-versions-d1be237c7e93?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/d1be237c7e93</guid>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[susy]]></category>
            <category><![CDATA[sass]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[code]]></category>
            <dc:creator><![CDATA[Miriam Suzanne]]></dc:creator>
            <pubDate>Fri, 28 Apr 2017 18:07:47 GMT</pubDate>
            <atom:updated>2017-04-28T17:55:57.480Z</atom:updated>
            <content:encoded><![CDATA[<p><em>You probably don’t need safe-get-function utilities</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7cxWadX4EyPyH7_0vgY4SQ.jpeg" /></figure><p>The <a href="http://sass.logdown.com/posts/809572-sass-35-release-candidate">Sass 3.5 Release Candidate</a> includes support for <a href="https://medium.com/@kaelig/sass-first-class-functions-6e718e2b5eb0">first-class functions</a> and the resulting get-function() function. I just said “function” too many times in a single sentence. Get used to it, there’s more. We’ll explain the problem, and help you call all the functions in every version of Sass!</p><h3>Calling Functions</h3><p>Normally, when we’re using functions in Sass, we know what function we need, and we can reference it directly:</p><pre>// Using Susy&#39;s &quot;span&quot; function directly, <br>// with a single argument...<br>.span { <br>  width: span(3); <br>}</pre><p>But when we build toolkits in Sass, it’s common that we don’t know for sure what function we’ll be calling. In <a href="http://oddbird.net/">OddBird’s</a> <a href="http://oddbird.net/2017/03/07/pattern-making/">Accoutrement</a> tools we let the user pass in arbitrary functions and arguments that we’ll call at the right time to manipulate CSS colors and sizes.</p><p>In order to call functions without knowing the function name in advance, we have to use the call() function. Here’s how it works on the current versions of Sass:</p><pre>// This could change! <br>$function: &#39;span&#39;; </pre><pre>// Calling an unknown function, with a single argument <br>.span { <br>  width: call($function, 3);<br>}</pre><p>Those two code samples will return the same results. The first is more direct, but the second is more flexible for use in a toolkit.</p><h3>Introducing the `get-function` function</h3><p>Sass is taking a first step towards modular namespacing — expected to land in the 4.0 release. This will allow you to include third-party tools without any concern for naming conflicts.</p><p>Functions will be namespaced locally to a given Sass file — something like susy.span(), though the syntax hasn’t been settled. The new get-function() allows us to capture a snapshot of a function into a variable, and pass that snapshot into new namespacing contexts.</p><pre>// type-of($my-function) == &#39;function&#39; <br>$my-function: get-function(&#39;susy.span&#39;);</pre><p>In Sass 3.5 and later, the call() function only accepts first-class functions, where it used to accept function names as a string. In brief, we have to start using get-function(&#39;function-name&#39;) before calling a function using call() – but only in new versions of Sass.</p><p>In demo code, people often write it like this:</p><pre>$call: call(get-function(&#39;susy.span&#39;), $arguments...);</pre><p>That code is misleading. It made me wonder why get-function isn’t simply baked into call, so we can pass a first-class function or a string depending on the context.</p><p>Since call is most often used by third-party tools, living in a different context and namespace, the user will have to capture functions themselves, before passing them to the toolkit. While call happens internally, the get-function has to happen in the user’s code.</p><p>A more accurate demonstration might be:</p><pre>// third-party-toolkit.scss <br>@mixin three-wide($function) { <br>  width: call($function, 3); <br>} </pre><pre>// your-local.scss <br>@import &#39;susy&#39;; <br>@import &#39;third-party-toolkit&#39;; <br>$span-function: get-function(&#39;susy-span&#39;); <br>@include three-wide($span-function);</pre><p>So how do we support old and new versions of Sass, while allowing users to pass in either strings or first-class functions?</p><h3>Probably Don’t Worry About It</h3><p>After a long conversation with Chris Eppstein, one of the Sass language designers, it’s clear that the change rests entirely in the hands of users. Most toolkits can continue to use call as they always have, but users upgrading to Sass 3.5+ should begin to capture functions before passing them anywhere outside the local context.</p><p>OddBird’s <a href="http://oddbird.net/open-source/accoutrement/">Sass Accoutrement</a> tools, for example, allow users to <a href="http://oddbird.net/2017/03/30/07/pattern-making/">pass in an arbitrary function</a>. Once users upgrade to Sass 3.5, they should be sure to get the function before passing it in. Meanwhile, our tools will continue to use call internally, without any changes.</p><h3>One Exception</h3><p>There is one exception, where I use call internally, with known local functions in a loop. The purpose of call in this case is not to accept arbitrary functions from the user, but to DRY our code with a loop of local functions.</p><p>To handle that, we use a few lines of code to make sure we get the function in newer versions of Sass, without breaking older versions:</p><pre>@each $key, $value in $config { $function: &#39;susy-normalize-#{$key}&#39;; @if function-exists(&#39;get-function&#39;) { $function: get-function($function); } $result: call($function, $value); }</pre><p>This is basically identical to <a href="https://medium.com/@kaelig/sass-first-class-functions-6e718e2b5eb0">Kaelig’s solution</a>, which initially inspired my post. It should work on all versions of Sass, but <strong>should only be used internally, calling local functions</strong> (e.g. known functions defined in the same partial).</p><p>Have you played with Sass 3.5 already? Did we miss anything important? Leave a note on our <a href="http://oddbird.net/contact/">contact form</a>, join our <a href="http://friends.oddbird.net/">public Slack chat</a>, or tweet <a href="http://twitter.com/oddbird">@oddbird</a> to start a conversation.</p><p><em>Originally published at </em><a href="http://oddbird.net/2017/03/30/safe-get/"><em>oddbird.net</em></a><em> on March 30, 2017.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d1be237c7e93" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/making-function-calls-across-sass-versions-d1be237c7e93">Making Function Calls Across Sass Versions</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Blocking Analytics Spam]]></title>
            <link>https://medium.com/oddbird-web/blocking-analytics-spam-e4a57f655eae?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/e4a57f655eae</guid>
            <category><![CDATA[spam]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[gulp]]></category>
            <category><![CDATA[webpack]]></category>
            <category><![CDATA[google-analytics]]></category>
            <dc:creator><![CDATA[Jonny Gerig Meyer]]></dc:creator>
            <pubDate>Thu, 06 Apr 2017 21:30:46 GMT</pubDate>
            <atom:updated>2017-04-06T21:34:54.427Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yJP4z9qyfUCZAgIBJ1UsXw.jpeg" /></figure><p>Google Analytics is great for gathering data on who uses your web application, but becomes worthless if spam sessions start infesting your data. Here’s how we’ve tried to combat the problem for <a href="http://oddbird.net/"><strong>oddbird.net</strong></a>.</p><p>Like many websites, we at <a href="http://oddbird.net/">OddBird</a> use <a href="https://analytics.google.com/">Google Analytics</a> to gather data about our users — what OS and browser they used, how they came to our site, etc. But a number of months ago we started seeing lots of this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1015/0*R-GNFdDVDAq5_VW6.jpg" /></figure><p>It’s not a new problem, but it’s particularly problematic for smaller sites that don’t receive lots of traffic. On a given day, spam hits were accounting for anywhere from ten to ninety (!) percent of our sessions.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/822/0*Jz46iMhNdrM0cnEL.jpg" /></figure><p>There are <a href="https://www.google.com/#q=how+to+block+google+analytics+spam">many solutions out there</a>; since we mostly saw spam in the “referral” field, we wanted a simple way to block spam referrals from being included in our analytics data.</p><h3>Blocking Spam Referrals</h3><p>One common approach is to blacklist any site visits where document.referrer matches a known spam domain. There are <a href="https://referrerspamblocker.com/">free services</a> that create the necessary Google Analytics “filters” for you, but they must be re-configured frequently as new spammers are added to the list.</p><p>Instead, we tried <a href="https://github.com/MohamedBassem/spam-referrals-blocker/">spam-referrals-blocker</a>, which is a script that blocks referrals found on a <a href="https://github.com/piwik/referrer-spam-blacklist">community-contributed list of referrer spammers</a>. Rather than relying on the owner of the script to update it periodically with the latest blacklist — or maintaining our own fork of the repo — we decided to fetch the latest list as part of our build/deploy process, using <a href="http://gulpjs.com/">gulp</a> and <a href="https://github.com/Metrime/gulp-download">gulp-download</a>:</p><pre>const gulp = require(&#39;gulp&#39;);<br>const download = require(&#39;gulp-download&#39;);<br><br>gulp.task(&#39;update-spammers&#39;, () =&gt; {<br>  const url = &#39;https://raw.githubusercontent.com/piwik/referrer-spam-blacklist/master/spammers.txt&#39;;<br>  return download(url).pipe(gulp.dest(&#39;path/to/js/&#39;));<br>});</pre><p>Once we have an up-to-date blacklist, we import it with the <a href="https://webpack.js.org/">webpack</a> <a href="https://github.com/webpack-contrib/raw-loader">raw-loader</a> and block any referrer found on the list:</p><pre>import spammers from &#39;raw-loader!./spammers.txt&#39;;<br><br>window.isSpamReferral = function () {<br>  const list = spammers.split(&#39;\n&#39;);<br>  const currentReferral = document.referrer;<br>  if (currentReferral) {<br>    for (const spammer of list) {<br>      if (spammer &amp;&amp; currentReferral.indexOf(spammer) !== -1) {<br>        return true;<br>      }<br>    }<br>  }<br>  return false;<br>};</pre><p>And in our HTML, after the JS file has been executed:</p><pre>&lt;script&gt;<br>  if(!window.isSpamReferral()) {<br>    <em>// ... initialize Google Analytics<br></em>  }<br>&lt;/script&gt;</pre><h4>Bonus: Excluding Internal Traffic</h4><p>Without much extra work, we can also exclude internal traffic from our analytics data:</p><pre>const devHosts = [<br>  <em>// List your local development servers<br></em>  &#39;oddsite.hexxie.com:3000&#39;,<br>  &#39;localhost:3000&#39;,<br>  &#39;127.0.0.1:3000&#39;<br>];<br><br>window.isDevelopment = () =&gt; {<br>  return devHosts.indexOf(window.location.host) !== -1;<br>}</pre><p>And our modified HTML:</p><pre>&lt;script&gt;<br>  if(!window.isSpamReferral() &amp;&amp; !window.isDevelopment()) {<br>    <em>// ... initialize Google Analytics<br></em>  }<br>&lt;/script&gt;</pre><h3>Can’t We Do Better Than That?</h3><p>This approach has worked relatively well — in the first two weeks, we only saw nine spam sessions sneak through. But we weren’t entirely thrilled with it, either.</p><p>First of all, a blacklist of domains-to-block is much more difficult to maintain than a whitelist of domains-to-allow (even if we’ve off-loaded most of the maintenance to the community). And second, there’s something less-than-ideal about fetching a raw .txt file directly from someone else’s GitHub repo, making assumptions about the format of the file contents, and then relying on it as part of our build/deploy process.</p><p>So we’ve recently also implemented many of the methods outlined in <a href="https://www.ohow.co/ultimate-guide-to-removing-irrelevant-traffic-in-google-analytics/">this guide</a>, most notably <a href="https://www.ohow.co/ultimate-guide-to-removing-irrelevant-traffic-in-google-analytics/#a-creating-a-valid-hostname-filter-for-ghost-spam">using a whitelist filter to exclude any hostnames we haven’t explicitly authorized</a>. This takes care of most of the spam, and is arguably cleaner and easier to maintain.</p><p>We haven’t been using this technique for long, but so far the results have been positive. If it continues to work well, we’ll likely remove the referral-blocking code entirely.</p><p>If you use Google Analytics, how have you tackled the problem of spam infecting your data? Let us know via <a href="https://twitter.com/oddbird">Twitter</a> or our public <a href="http://friends.oddbird.net/">Slack channel</a>!</p><p><em>Originally published at </em><a href="http://oddbird.net/2017/03/23/blocking-analytics-spam/"><em>oddbird.net</em></a><em> on March 23, 2017.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e4a57f655eae" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/blocking-analytics-spam-e4a57f655eae">Blocking Analytics Spam</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Server-Side Rendering For Client-Side Apps]]></title>
            <link>https://medium.com/oddbird-web/server-side-rendering-for-client-side-apps-4e94315f55b?source=rss----316a2595b32---4</link>
            <guid isPermaLink="false">https://medium.com/p/4e94315f55b</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[marionettejs]]></category>
            <category><![CDATA[django]]></category>
            <category><![CDATA[backbonejs]]></category>
            <dc:creator><![CDATA[Jonny Gerig Meyer]]></dc:creator>
            <pubDate>Thu, 06 Apr 2017 21:29:19 GMT</pubDate>
            <atom:updated>2017-04-07T21:14:01.469Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*41faYmXijbMCJN9lTnWMwQ.jpeg" /></figure><p>We want the convenience of a client-side single-page application using our <a href="http://backbonejs.org/"><strong>MV* framework</strong></a> <a href="http://marionettejs.com/"><strong>of choice</strong></a>, but don’t want to sacrifice the SEO and UX benefits of rendering the initial markup on the server. And while we’re not here to trash on Node.js, we’re also not ready to commit to an all-JavaScript tech stack. Here’s our attempt to have the best of both worlds, all the while keeping duplication of logic or code between the front-end and back-end worlds to a minimum.</p><p>At <a href="http://oddbird.net/">OddBird</a>, we’re lucky enough to mostly work on <a href="https://en.wikipedia.org/wiki/Greenfield_project">greenfield projects</a> — which means we choose our own tech stack. One of the first questions is how to render templates for the initial page-load. There are many reasons to prefer server-side rendering over a “pure” single-page app which always renders content in the browser — it’s better for SEO, users don’t have to wait for the JavaScript to initialize before seeing content on the page, etc. But it’s also more work to convince a client-side <a href="http://backbonejs.org/">MV* framework</a> to play nicely — and efficiently — with server-rendered markup.</p><p><a href="https://medium.com/u/83786451914b">Kit</a> has <a href="http://oddbird.net/2016/12/16/server-side-rendering-spa/">laid out</a> some of the options for sharing templates between client and server, and outlined one way we’ve tried to reduce code/logic duplication in the API layer. That’s a great start, but we still need to turn that server-rendered markup into an interactive single-page application.</p><h3>Getting the Data</h3><p>There are a few ways we could transfer data from the server to our client-side application:</p><ol><li>Request JSON from the API via an XHR</li><li>Embed JSON in a &lt;script&gt; tag (either type=&quot;text/javascript&quot; or <a href="http://stackoverflow.com/a/7956249/854407">type=&quot;application/json&quot;</a>)</li><li>Embed JSON in data-attributes on DOM elements corresponding to models or collections</li></ol><p>The first option is the “cleanest” (allowing the JS to consistently fetch data through the API), but adds an unnecessary XHR and wait-time before the page is ready for user interaction.</p><p>The second and third options are similar. Using a &lt;script&gt; tag is probably the most efficient (using only one DOM interaction to acquire the entire data set), but requires careful namespacing and patterns to know which data should be attached to which existing markup. In cases involving large collections, this is my preferred approach.</p><p>Storing JSON in data-attributes on individual DOM elements has the advantage of coupling the data and markup together for each component, but requires consistent markup patterns if the JS is to be reusable for various pieces of the app. It necessitates DOM interactions to fetch the data, which could easily cause performance issues with larger collections. In our case — with a relatively small data set for each page — this option provides both reasonable performance and a clear relationship between the data and its corresponding markup.</p><p>For example, let’s say that we want to attach models and views to a server-rendered list of comments. Using <a href="http://jinja.pocoo.org/docs/dev/">Jinja2</a>/<a href="https://mozilla.github.io/nunjucks/">Nunjucks</a>, our markup might look like this:</p><pre>&lt;div class=&quot;comment-list&quot;&gt;<br>  &lt;article class=&quot;comment&quot; data-js-model=&quot;{{ comment|json }}&quot;&gt;<br>    &lt;p&gt;{{ comment.body }}&lt;/p&gt;<br>    &lt;p&gt;{{ comment.author }}&lt;/p&gt;<br>  &lt;/article&gt;<br>&lt;/div&gt;</pre><h3>Brief &lt;aside&gt;</h3><p>You’ll note that we’re using a custom json filter to convert an object into a JSON string. One downside of sharing templates between front-end and back-end (Nunjucks written in JS on the front-end, and Jinja2 written in Python on the back-end) is that any custom filters used in shared templates must be written in both languages. So for this to work, we have a json filter added to our Nunjucks environment:</p><pre>import nunjucks from &#39;nunjucks&#39;;</pre><pre>const env = new nunjucks.Environment();<br>env.addFilter(&#39;json&#39;, (val) =&gt; JSON.stringify(val));</pre><p>And a corresponding filter added to our Jinja2 environment:</p><pre>from json import dumps<br>from jinja2 import Environment<br><br>def environment(**options):<br>    env = Environment(**options)<br>    env.filters.update({<br>        &#39;json&#39;: json,<br>    })<br>    return env<br><br>def json(val):<br>    &quot;&quot;&quot;Return given value as a JSON string.&quot;&quot;&quot;<br>    return dumps(val)</pre><p>This isn’t ideal, but seems like a reasonable trade-off since it allows us to avoid duplicating all the template files themselves.</p><p>Ok, &lt;/aside&gt;.</p><h3>Using the Data</h3><p>So we’ve made the model/collection data available in the DOM without requiring an additional XHR. Now we need to add our JS layer, turning the data into actual models or collections that are managed by views.</p><p>The details differ here from one framework to another. Since we’re using <a href="http://backbonejs.org/">Backbone.js</a> and <a href="http://marionettejs.com/">Marionette</a> (^3.0.0), let’s look at one approach with those frameworks.</p><pre>import BB from &#39;backbone&#39;;<br>import Mnt from &#39;backbone.marionette&#39;;<br><br>const ViewWithModel = Mnt.View.extend({<br>  initialize () {<br>    <em>// Only run this code if an ``el`` option is passed in, signifying<br></em>    <em>// that the view is being attached to existing markup in the DOM.<br></em>    if (this.options.el) {<br>      this.attachModel();<br>    }<br>  },<br>  <em>// Find the existing [data-js-model] element, adding a model to the view.<br></em>  attachModel () {<br>    const child = this.$(&#39;[data-js-model]&#39;);<br>    const modelData = child.data(&#39;js-model&#39;);<br>    this.model = new BB.Model(modelData);<br>    <em>// Trigger any onRender handlers attached to the view.<br></em>    this.triggerMethod(&#39;render&#39;, this);<br>  }<br>});<br><br>const myView = new ViewWithModel({ el: $(&#39;.comment&#39;) });</pre><p>Or for a view with a collection of models:</p><pre>import BB from &#39;backbone&#39;;<br>import Mnt from &#39;backbone.marionette&#39;;<br><br><em>// Create a child view (used for each individual model).<br></em>const MyChildView = Mnt.View.extend({<br>  <em>// ...<br></em>});<br><br>const ViewWithCollection = Mnt.CollectionView.extend({<br>  collection: new BB.Collection(),<br>  childView: MyChildView,<br>  initialize () {<br>    <em>// Only run this code if an ``el`` option is passed in, signifying<br></em>    <em>// that the view is being attached to existing markup in the DOM.<br></em>    if (this.options.el) {<br>      this.attachChildren();<br>    }<br>  },<br>  <em>// Look through existing child [data-js-model] elements, adding models<br></em>  <em>// to the collection, and attaching views to the models.<br></em>  attachChildren () {<br>    const view = this;<br>    const collection = view.collection;<br>    const children = this.$(&#39;[data-js-model]&#39;);<br>    children.each((idx, el) =&gt; {<br>      const $el = $(el);<br>      const modelData = $el.data(&#39;js-model&#39;);<br>      <em>// Check to see if this model already exists in the collection.<br></em>      let model = collection.get(modelData.id);<br>      if (!model) {<br>        <em>// Create the new model, and add it to the collection.<br></em>        model = collection.add(modelData, { silent: true });<br>      }<br>      const childView = new view.childView({ model, el });<br>      view.addChildView(childView, idx);<br>    });<br>    <em>// Prevent the collectionView from rendering children initially.<br></em>    view._isRendered = true;<br>    <em>// Trigger any onRender handlers attached to the view.<br></em>    view.triggerMethod(&#39;render&#39;, view);<br>  }<br>});<br><br>const myView = new ViewWithCollection({ el: $(&#39;.comment-list&#39;) });</pre><p>Now we have a model (or collection of models) instantiated with data from our server-rendered markup, all being managed by Marionette views! 🎉</p><h3>Where Do We Go From Here?</h3><p>In the end, we’re moving toward the best of both worlds: a server-rendered page (easily indexable by search engines, with content immediately visible to users), with the client-side benefits of a single-page app (live-updating components, and no page refreshes).</p><p>There are a number of improvements we could make — prioritizing the most important pieces of interactivity and lazy-loading the rest, abstracting our code into a Marionette <a href="http://marionettejs.com/docs/v3.1.0/marionette.behavior.html">behavior</a> that can be added to any view where we want to pre-load with data from the DOM — but this is a good start. Every step of the way, we strive to minimize the amount of duplicated code or logic — no need for a JavaScript process on the server, and no duplicated templates.</p><p>We have a number of other tricks for sharing canonical data — global settings, third-party API keys, minified asset mappings, and even color maps generated directly from SCSS — but those will wait for a later installment in this series.</p><p>How have you tackled the problem of wiring up a single-page application with server-side rendering? What are we missing, or where could we improve our methods? Drop us a line via <a href="https://twitter.com/oddbird">Twitter</a> or chime in on our public <a href="http://friends.oddbird.net/">Slack channel</a>!</p><p><em>Originally published at </em><a href="http://oddbird.net/2017/02/06/server-side-rendering-client-side-app/"><em>oddbird.net</em></a><em> on February 6, 2017.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4e94315f55b" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oddbird-web/server-side-rendering-for-client-side-apps-4e94315f55b">Server-Side Rendering For Client-Side Apps</a> was originally published in <a href="https://medium.com/oddbird-web">OddBird</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>