{"rowid": 7, "title": "Get Started With GitHub Pages (Plus Bonus Jekyll)", "contents": "After several failed attempts at getting set up with GitHub Pages, I vowed that if I ever figured out how to do it, I\u2019d write it up. Fortunately, I did eventually figure it out, so here is my write-up.\n\nWhy I think GitHub Pages is cool\n\nNormally when you host stuff on GitHub, you\u2019re just storing your files there. If you push site files, what you\u2019re storing is the code, and when you view a file, you\u2019re viewing the code rather than the output. What GitHub Pages lets you do is store those files, and if they\u2019re HTML files, you can view them like any other website, so there\u2019s no need to host them separately yourself.\n\nGitHub Pages accepts static HTML but can\u2019t execute languages like PHP, or use a database in the way you\u2019re probably used to, so you\u2019ll need to output static HTML files. This is where templating tools such as Jekyll come in, which I\u2019ll talk about later.\n\nThe main benefit of GitHub Pages is ease of collaboration. Changes you make in the repository are automatically synced, so if your site\u2019s hosted on GitHub, it\u2019s as up-to-date as your GitHub repository. This really appeals to me because when I just want to quickly get something set up, I don\u2019t want to mess around with hosting; and when people submit a pull request, I want that change to be visible as soon as I merge it without having to set up web hooks.\n\nBefore you get started\n\nIf you\u2019ve used GitHub before, already have an account and know the basics like how to set up a repository and clone it to your computer, you\u2019re good to go. If not, I recommend getting familiar with that first. The GitHub site has extensive documentation on getting started, and if you\u2019re not a fan of using the command line, the official GitHub apps for Mac and Windows are great.\n\nI also found this tutorial about GitHub Pages by Thinkful really useful, and it contains details on how to turn an existing repository into a GitHub Pages site.\n\nAlthough this involves a bit of using the command line, it\u2019s minimal, and I\u2019ll guide you through the basics.\n\nSetting up GitHub Pages\n\nFor this demo we\u2019re going to build a Christmas recipe site \u2014 nothing complex, just a place to store recipes so we can share them with people, and they can fork or suggest changes to ones they like. My GitHub username is maban, and the project I\u2019ve set up is called christmas-recipes, so once I\u2019ve set up GitHub Pages, the site can be found here: http://maban.github.io/christmas-recipes/\n\nYou can set up a custom domain, but by default, the URL for your GitHub Pages site is your-username.github.io/your-project-name.\n\nSet up the repository\n\nThe first thing we\u2019re going to do is create a new GitHub repository, in exactly the same way as normal, and clone it to the computer. Let\u2019s give it the name christmas-recipes. There\u2019s nothing in it at the moment, but that\u2019s OK.\n\n\n\nAfter setting up the repository on the GitHub website, I cloned it to my computer in my Sites folder using the GitHub app (you can clone it somewhere else, if you want), and now I have a local repository synced with the remote one on GitHub.\n\nNavigate to the repository\n\nNow let\u2019s open up the command line and navigate to the local repository. The easiest way to do this in Terminal is by typing cd  and dragging and dropping the folder into the terminal window and pressing Return. You can refer to Chris Coyier\u2019s GIF illustrating this very same thing, from last week\u2019s 24 ways article \u201cGrunt for People Who Think Things Like Grunt are Weird and Hard\u201d (which is excellent).\n\nSo, for me, that\u2019s\u2026\n\ncd /Users/Anna/Sites/christmas-recipes \n\nCreate a special GitHub Pages branch\n\nSo far we haven\u2019t done anything different from setting up a regular repository, but here\u2019s where things change.\n\nNow we\u2019re in the right place, let\u2019s create a gh-pages branch. This tells GitHub that this is a special branch, and to treat the contents of it differently.\n\nMake sure you\u2019re still in the christmas-recipes directory, and type this command to create the gh-pages branch:\n\ngit checkout --orphan gh-pages\n\nThat --orphan option might be new to you. An orphaned branch is an empty branch that\u2019s disconnected from the branch it was created off, and it starts with no commits, making it a special standalone branch. checkout switches us from the branch we were on to that branch.\n\nIf all\u2019s gone well, we\u2019ll get a message saying Switched to a new branch \u2018gh-pages\u2019.\n\nYou may get an error message saying you don\u2019t have admin privileges, in which case you\u2019ll need to type sudo at the start of that command.\n\nMake gh-pages your default branch (optional)\n\nThe gh-pages branch is separate to the master branch, but by default, the master branch is what will show up if we go to our repository\u2019s URL on GitHub. To change this, go to the repository settings and select gh-pages as the default branch.\n\n\n\nIf, like me, you only want the one branch, you can delete the master branch by following Oli Studholme\u2019s tutorial. It\u2019s actually really easy to do, and means you only have to worry about keeping one branch up to date.\n\nIf you prefer to work from master but push updates to the gh-pages branch, Lea Verou has written up a quick tutorial on how to do this, and it basically involves working from the master branch, and using git rebase to bring one branch up to date with another.\n\nAt the moment, we\u2019ve only got that branch on the local machine, and it\u2019s empty, so to be able to see something at our special GitHub Pages URL, we\u2019ll need to create a page and push it to the remote repository.\n\nMake a page\n\nOpen up your favourite text editor, create a file called index.html in your christmas-recipes folder, and put some exciting text in it. Don\u2019t worry about the markup: all we need is text because right now we\u2019re just checking it works.\n\n\n\nNow, let\u2019s commit and push our changes. You can do that in the command line if you\u2019re comfortable with that, or you can do it via the GitHub app. Don\u2019t forget to add a useful commit message.\n\n\n\nNow we\u2019re ready to see our gorgeous new site! Go to your-username.github.io/your-project-name and, hopefully, you\u2019ll see your first GitHub Pages site. If not, don\u2019t panic, it can take up to ten minutes to publish, so you could make a quick cake in a cup while you wait.\n\nAfter a short wait, our page should be live! Hopefully that wasn\u2019t too traumatic. Now we know it works, we can add some proper markup and CSS and even some more pages.\n\nIf you\u2019re feeling brave, how about we take it to the next level\u2026\n\nSetting up Jekyll\n\nSince GitHub Pages can\u2019t execute languages like PHP, we need to give it static HTML files. This is fine if there are only a few pages, but soon we\u2019ll start to miss things like PHP includes for content that\u2019s the same on every page, like headers and footers.\n\nJekyll helps set up templates and turn them into static HTML. It separates markup from content, and makes it a lot easier for people to edit pages collaboratively. With our recipe site, we want to make it really easy for people to fix typos or add notes, without having to understand PHP. Also, there\u2019s the added benefit that static HTML pages load really fast.\n\nJekyll isn\u2019t officially supported on Windows, but it is still possible to run it if you\u2019re prepared to get your hands dirty.\n\nInstall Jekyll\n\nBack in Terminal, we\u2019re going to install Jekyll\u2026\n\ngem install jekyll\n\n\u2026and wait for the script to run. This might take a few moments. It might take so long that you get worried its broken, but resist the urge to start mashing your keyboard like I did.\n\nGet Jekyll to run on the repository\n\nFingers crossed nothing has gone wrong so far. If something did go wrong, don\u2019t give up! Check this helpful post by Andy Taylor \u2013 you probably just need to install something else first. \n\nNow we\u2019re going to tell Jekyll to set up a new project in the repository, which is in my Sites folder (yours may be in a different place). Remember, we can drag the directory into the terminal window after the command.\n\njekyll new /Users/Anna/Sites/christmas-recipes\n\nIf everything went as expected, we should get this error message: Conflict: /Users/Anna/Sites/christmas-recipes exists and is not empty.\n\nBut that\u2019s OK. It\u2019s just upset because we\u2019ve got that index.html file and possibly also a README.md in there that we made earlier. So move those onto your desktop for the moment and run the command again.\n\njekyll new /Users/Anna/Sites/christmas-recipes\n\nIt should say that the site has installed.\n\nCheck you\u2019re in the repository, and if you\u2019re not, navigate to it by typing cd , drag the christmas-recipes directory into terminal\u2026\n\njekyll cd /Users/Anna/Sites/christmas-recipes\n\n\u2026and type this command to tell Jekyll to run:\n\njekyll serve --watch\n\nBy adding --watch at the end, we\u2019re forcing Jekyll to rebuild the site every time we hit Save, so we don\u2019t have to keep telling it to update every time we want to view the changes. We\u2019ll need to run this every time we start work on the project, otherwise changes won\u2019t be applied. For now, wait while it does its thing. \n\nUpdate the config file\n\nWhen it\u2019s finished, we\u2019ll see the text press ctrl-c to stop. Don\u2019t do that, though. Instead, open up the directory. You\u2019ll notice some new files and folders in there. There\u2019s one called _site, and that\u2019s where all the site files are saved when they\u2019re turned into static HTML. Don\u2019t touch the files in here \u2014 they\u2019re the generated files and will get overwritten every time we make changes to pages and layouts.\n\nThere\u2019s a file in our directory called _config.yml. This has some settings we can change, one of them being what our base URL is. GitHub Pages will assume the base URL is above the project repository, so changing the settings here will help further down the line when setting up navigation links.\n\nReplace the contents of the _config.yml file with this:\n\nname: Christmas Recipes\nmarkdown: redcarpet\npygments: true\nbaseurl: /christmas-recipes\n\nSet up your files\n\nOverwrite the index.html file in the root with the one we made earlier (you might want to pop the README.md back in there, too). \n\nDelete the files in the css folder \u2014 we\u2019ll add our own later.\n\nView the Jekyll site\n\nOpen up your favourite browser and type http://localhost:4000/christmas-recipes in the address bar.\n\n\n\nCheck it out, that\u2019s your site! But it could do with a bit more love.\n\nSet up the _includes files\n\nIt\u2019s always useful to be able to pull in snippets of content onto pages, such as the header and footer, so they only need to be updated in one place. That\u2019s what an _includes folder is for in Jekyll. Create a folder in the root called _includes, and within it add two files: head.html and foot.html. \n\nIn head.html, paste the following:\n\n<!DOCTYPE html>\n<html>\n    <head>\n        <meta charset=\"utf-8\">\n        <title>{{ page.title }}</title>\n        <link rel=\"stylesheet\" href=\"{{ site.baseurl }}/css/main.css\" >\n    </head>\n    <body>\n\nand in foot.html:\n\n</body>\n</html>\n\nWhenever we want to pull in something from the _includes folder, we can use {% include filename.html %} in the layout file \u2014 I\u2019ll show you how to set that up in next step.\n\nMaking layouts\n\nIn our directory, there\u2019s a folder called _layouts and this lets us create a reusable template for pages. Inside that is a default.html file. \n\nDelete everything in default.html and paste in this instead:\n\n{% include head.html %}\n\n    <h1>{{ page.title }}</h1>\n\n    {{ content }}\n\n{% include foot.html %}\n\nThat\u2019s a very basic page with a header, footer, page title and some content. To apply this template to a page, go back into the index.html page and add this snippet to the very top of the file:\n\n---\nlayout: default\ntitle: Home\n---\n\nNow save the index.html file and hit Refresh in the browser. We should see a heading where {{ page.title }} was in the layout, which matches what comes after title: on the page itself (in this case, Home). So, if we wanted a subheading to appear on every page, we could add {{ page.subheading }} to where we want it to appear in our layout file, and a line that says subheading: This is a subheading in between the dashes at the top of the page itself.\n\nUsing Markdown for templates\n\nAnything on a page that sits under the closing dashes is output where {{ content }} appears in the template file. At the moment, this is being output as HTML, but we can use Markdown instead, and Jekyll will convert that into HTML. For this recipe site, we want to make it as easy as possible for people to be able to collaborate, and also have the markup separate from the content, so let\u2019s use Markdown instead of HTML for the recipes.\n\nTelling a page to use Markdown instead of HTML is incredibly simple. All we need to do is change the filename from .html to .md, so let\u2019s rename the index.html to index.md. Now we can use Markdown, and Jekyll will output that as HTML.\n\nCreate a new layout\n\nWe\u2019re going to create a new layout called recipe which is going to be the template for any recipe page we create. Let\u2019s keep it super simple.\n\nIn the _layouts folder, create a file called recipe.html and paste in this:\n\n{% include head.html %}\n\n\t<main>\n\n    \t<h1>{{ page.title }}</h1>\n\n    \t{{ content }}\n\n    \t<p>Recipe by <a href=\"{{ page.recipe-attribution-link }}\">{{ page.recipe-attribution }}</a>.</p>\n\n\t</main>\n\n\t{% include nav.html %}\n\n{% include foot.html %}\n\nThat\u2019s our template. The content that goes on the recipe layout includes a page title, the recipe content, a recipe attribution and a recipe attribution link.\n\nAdding some recipe pages\n\nCreate a new file in the root of the christmas-recipes folder and call it gingerbread.md. Paste the following into it:\n\n---\nlayout: recipe\ntitle: Gingerbread\nrecipe-attribution: HungryJenny\nrecipe-attribution-link: http://www.opensourcefood.com/people/HungryJenny/recipes/soft-christmas-gingerbread-cookies\n---\nMakes about 15 small cookies.\n\n## Ingredients\n\n* 175g plain flour\n* 90g brown sugar\n* 50g unsalted butter, diced, at room temperature\n* 2 tbsp golden syrup\n* 1 egg, beaten\n* 1 tsp ground ginger\n* 1 tsp cinnamon\n* 1 tsp bicarbonate of soda\n* Icing sugar to dust\n\n## Method\n\n1. Sift the flour, ginger, cinnamon and bicarbonate of soda into a large mixing bowl.\n2. Use your fingers to rub in the diced butter. Mix in the sugar.\n3. Mix the egg with the syrup then pour into the flour mixture. Fold in well to form a dough.\n4. Tip some flour onto the work surface and knead the dough until smooth.\n5. Preheat the oven to 180\u00b0C.\n6. Roll the dough out flat and use a shaped cutter to make as many cookies as you like.\n7. Transfer the cookies to a tray and bake in the oven for 15 minutes. Lightly dust the cookies with icing sugar.\n\nThe content is in Markdown, and when we hit Save, it\u2019ll be converted into HTML in the _site folder. Save the file, and go to http://localhost:4000/christmas-recipes/gingerbread.html in your favourite browser.\n\n \n\nAs you can see, the Markdown content has been converted into HTML, and the attribution text and link has been inserted in the right place.\n\n\nAdd some navigation\n\nIn your _includes folder, create a new file called nav.html. Here is some code that will generate your navigation:\n\n<nav class=\"nav-primary\" role=\"navigation\" >\n    <ul>\n        {% for p in site.pages %}\n        <li>\n        \t<a {% if p.url == page.url %}class=\"active\"{% endif %} href=\"{{ site.baseurl }}{{ p.url }}\">{{ p.title }}</a>\n        </li>\n        {% endfor %}\n    </ul>\n</nav>\n\nThis is going to look for all pages and generate a list of them, and give the navigation item that is currently active a class of active so we can style it differently.\n\nNow we need to include that navigation snippet in our layout. Paste {% include nav.html %} in default.html file, under {{ content }}.\n\nPush the changes to GitHub Pages\n\nNow we\u2019ve got a couple of pages, it\u2019s time to push our changes to GitHub. We can do this in exactly the same way as before. Check your special GitHub URL (your-username.github.io/your-project-name) and you should see your site up and running.\n\nIf you quit Terminal, don\u2019t forget to run jekyll serve --watch from within the directory the next time you want to work on the files.\n\nNext steps\n\nNow we know the basics of creating Jekyll templates and publishing them as GitHub Pages, we can have some fun adding more pages and styling them up.\n\n \n \n Here\u2019s one I made earlier\n\n\nI\u2019ve only been using Jekyll for a matter of weeks, mainly for prototyping. It\u2019s really good as a content management system for blogs, and a lot of people host their Jekyll blogs on GitHub, such as Harry Roberts\n\n\n\tBy hosting the code so openly it will make me take more pride in it and allow me to work on it much more easily; no excuses now!\n\n\nOverall, the documentation for Jekyll feels a little sparse and geared more towards blogs than other sites, but as more people discover the benefits of it, I\u2019m sure this will improve over time.\n\nIf you\u2019re interested in poking about with some code, all the files from this tutorial are available on GitHub.", "year": "2013", "author": "Anna Debenham", "author_slug": "annadebenham", "published": "2013-12-18T00:00:00+00:00", "url": "https://24ways.org/2013/get-started-with-github-pages/", "topic": null}
{"rowid": 96, "title": "Unwrapping the Wii U Browser", "contents": "The Wii U was released on 18 November 2012 in the US, and 30 November in the UK. It\u2019s the first eighth generation home console, the first mainstream second-screen device, and it has some really impressive browser specs.\n\nConsoles are not just for games now: they\u2019re marketed as complete entertainment solutions. Internet connectivity and browser functionality have gone from a nice-to-have feature in game consoles to a selling point. In Nintendo\u2019s case, they see it as a challenge to design an experience that\u2019s better than browsing on a desktop.\n\n\n\tLet\u2019s make a browser that users can use on a daily basis, something that can really handle everything we\u2019ve come to expect from a browser and do it more naturally.\nSasaki \u2013 Iwata Asks on Nintendo.com\n\n\nWith 11% of people using console browsers to visit websites, it\u2019s important to consider these devices right from the start of projects. Browsing the web on a TV or handheld console is a very different experience to browsing on a desktop or a mobile phone, and has many usability implications.\n\nConsole browser testing\n\nWhen I\u2019m testing a console browser, one of the first things I do is run Niels Leenheer\u2019s HTML5 test and Lea Verou\u2019s CSS3 test. I use these benchmarks as a rough comparison of the standards each browser supports.\n\nIn October, IE9 came out for the Xbox 360, scoring 120/500 in the HTML5 test and 32% in the CSS3 test. The PS Vita also had an update to its browser in recent weeks, jumping from 58/500 to 243/500 in the HTML5 test, and 32% to 55% in the CSS3 test. Manufacturers have been stepping up their game, trying to make their browsing experiences better.\n\nTo give you an idea of how the Wii U currently compares to other devices, here are the test results of the other TV consoles I\u2019ve tested. I\u2019ve written more in-depth notes on TV and portable console browsers separately.\n\n\nYear of releaseHTML5 scoreCSS3 scoreNotes\nWii U2012258/50048%Runs a Netfront browser (WebKit).\nWii200689/500Wouldn\u2019t runRuns an Opera browser.\nPS3200668/50038%Runs a Netfront browser (WebKit).\nXbox 3602005120/50032%A browser for the Xbox (IE9) was only recently released in October 2012. The Kinect provides voice and gesture support. There\u2019s also SmartGlass, a second-screen app for platforms including Android and iOS.\n\n\nThe Wii U browser is Nintendo\u2019s fifth attempt at a console browser. Based on these tests, it\u2019s already looking promising.\n\nWhy console browsers used to suck\n\nIt takes a lot of system memory to run a good browser, and the problem of older consoles is that they don\u2019t have much memory available. The original Nintendo DS needs a memory expansion pack just to run the browser, because the 4MB it has on board isn\u2019t enough. I noticed that even on newer devices, some sites fail to load because the system runs out of memory.\n\nThe Wii came out six years ago with an Opera browser. Still being used today and with such low resources available, the latest browser features can\u2019t reasonably be supported. There\u2019s also pressure to add features such as tabs, and enable gamers to use the browser while a game is paused. Nintendo\u2019s browser team have the advantage of higher specs to play with on their new console (1GB of memory dedicated to games, 1GB for the system), which makes it easier to support the latest standards. But it\u2019s still a challenge to fit everything in.\n\n\n\t\u2026even though we have more memory, the amount of memory we can use for the browser is limited compared to a PC, so we\u2019ve worked in ways that efficiently allocates the available memory per tab. To work on this, the experience working on the browser for the Nintendo 3DS system under a limited memory constraint helped us greatly.\nSasaki \u2013 Iwata Asks on Nintendo.com\n\n\nIn the box\n\nThe Wii U consists of a console unit which plugs into a TV (the first to support HD), and a wireless controller known as a gamepad. The gamepad is a lot bigger than typical TV console controllers, and it has a touchscreen on the front. The touchscreen is resistive, responding to pressure rather than electrical current. It\u2019s intended to be used with a stylus (provided) but fingers can be used.\n\nIt might look a bit like one, but the gamepad isn\u2019t a portable console designed to be taken out like the PS Vita. The gamepad can be used as a standalone screen with the TV switched off, as long as it\u2019s within range of the console unit \u2013 it basically piggybacks off it.\n\n\n\nIt\u2019s surprisingly lightweight for its size. It has a wealth of detectors including 9-axis control. Sensors wake the device from sleep when it\u2019s picked up. There\u2019s also a camera on the front, and a headphone port and speakers, with audio coming through both the TV and the gamepad giving a surround sound feel.\n\nUp to six tabs can be opened at once, and the browser can be used while games are paused. There\u2019s a really nice little feature here \u2013 the current game\u2019s name is saved as a search option, so it\u2019s really quick to look up contextual content such as walk-throughs.\n\nControls\n\nOnly one gamepad can be used to control the browser, but if there are Wiimotes connected, they can be used as pointers. This doesn\u2019t let the user do anything except point (they each get a little hand icon with a number on it displayed on the screen), but it\u2019s interesting that multiple people can be interacting with a site at once.\n\n\n\nSee a bigger version\n\nThe gamepad can also be used as a simple TV remote control, with basic functions such as bringing up the programme guide, adjusting volume and changing channel. I found the simplified interface much more usable than a full-featured remote control.\n\n\n\nI\u2019m used to scrolling being sluggish on consoles, but the Wii U feels almost as snappy as a desktop browser. Sites load considerably faster compared with others I\u2019ve tested.\n\nTilt-scroll\n\nHolding down ZL and ZR while tilting the screen activates an Instapaper-style tilt to scroll for going up and down the page quickly, useful for navigating very long pages.\n\nSecond screen\n\nThe TV mirrors most of what\u2019s on the gamepad, although the TV screen just displays the contents of the browser window, while the gamepad displays the site along with the browser toolbar.\n\nWhen the user with the gamepad is typing, the keyboard is hidden from the TV screen \u2013 there\u2019s just a bit of text at the top indicating what\u2019s happening on the gamepad.\n\nPressing X draws an on-screen curtain over the TV, hiding the content that\u2019s on the gamepad from the TV. Pressing X again opens the curtains, revealing what\u2019s on the gamepad. Holding the button down plays a drumroll before it\u2019s released and the curtains are opened. I can imagine this being used in meetings as a fun presentation tool.\n\n\n\n\n\tIn a sense, browsing is a personal activity, but you get the idea that people will be coming and going through the room. When I first saw the curtain function, it made a huge impression on me. I walked around with it all over the company saying, \u201cThey\u2019ve really come up with something amazing!\u201d\nIwata \u2013 Iwata Asks on Nintendo.com\n\n\nText\n\nWriting text\n\nUnlike the capacitive screens on smartphones, the Wii U\u2019s resistive screen needs to be pressed harder than you\u2019re probably used to for registering a touch event. The gamepad screen is big, which makes it much easier to type on this device than other handheld consoles, even without the stylus. It\u2019s still more fiddly than a full-sized keyboard though. When you\u2019re designing forms, consider the extra difficulty console users experience.\n\n\n\nAlthough TV screens are physically big, they are typically viewed from further away than desktop screens. This makes readability an issue, so Nintendo have provided not one, but four ways to zoom in and out:\n\n\n\tDouble-tapping on the screen.\n\tTapping the on-screen zoom icons in the browser toolbar.\n\tPressing the + and - buttons on the device.\n\tMoving the right analogue stick up and down.\n\n\nAs well as making it easy to zoom in and out, Nintendo have done a few other things to improve the reading experience on the TV.\n\nSystem font\n\nOne thing you\u2019ll notice pretty quickly is that the browser lacks all the fonts we\u2019re used to falling back to. Serif fonts are replaced with the system\u2019s sans-serif font. I couldn\u2019t get Typekit\u2019s font loading method to work but Fontdeck, which works slightly differently, does display custom fonts.\n\n The system font has been optimised for reading at a distance and is easy to distinguish because the lowercase e has a quirky little tilt.\n\nDon\u2019t lose :focus\n\nUsing the D-pad to navigate is similar to using a keyboard. Individual links are focused on, with a blue outline drawn around them.\n\nThe recently redesigned An Event Apart site is an example that improves the experience for keyboard and D-pad users. They\u2019ve added a yellow background colour to links on focus. It feels nicer than the default blue outline on its own.\n\n\n\nMedia\n\nThis year, television overtook PCs as the primary way to watch online video content. TV is the natural environment for video, and 42% of online TVs in the US are connected to the internet via a console. Unfortunately, the <video> tag isn\u2019t supported in most console browsers, and those that have Flash installed often have such an old version that the video won\u2019t play.\n\nI suspect this has been a big driver in getting console browsers to support web standards. The Wii U is designed with video content in mind. It doesn\u2019t support Flash but it does support the HTML5 <video> tag.\n\nSome video formats can\u2019t be played, but those that are supported bring up an optimised interface with a custom scrub bar. This is where the device switches from mirroring the TV to being a second screen. The full-screen video is displayed on the TV, and the interface on the gamepad.\n\nThe really clever bit is that while a video is playing, the gamepad user can keep the video playing on the TV screen while searching for another video or browsing the web. This is the same for images too.\n\nOn the left, the video is being shown full-screen on the TV and gamepad. Only the gamepad gets the scrub bar. Clicking the slide up/down button (circled) lets the gamepad user browse the web while the video on the TV continues to play full-screen, as shown in the image on the right.\n\nThere\u2019s support for SVG images, and they look great on a high-definition TV screen. However, there\u2019s currently no way to save or download files.\n\nPreparing for console users\n\nI wasn\u2019t expecting to be quite as impressed as I am by this browser. It\u2019s encouraging to see console makers investing time into improving the experience as well as the standards support. In the same way there was an explosion in mobile browser use as the experience got better, I\u2019m sure we\u2019ll see the same with console browsers as the experience improves.\n\nThe value of detection\n\nConsoles offer a range of inputs including gesture, voice and controller buttons. That means we have to think about more diverse methods of input than just touch and click.\n\nThis is where I could tell you to add some detection methods such as user agent string sniffing to target a different experience for console users. But the majority of the time, that really isn\u2019t necessary. TV console browsers are getting a lot better at compensating for the living room environment, and they\u2019re designed to work with websites that haven\u2019t been optimised for this context.\n\nRather than tighten our grip on optimising experiences for every device out there, we\u2019ve got to be pragmatic. There are so many new devices coming out every week, our designs need to be future-proof rather than fixed to a particular device in time.\n\nEven fuzzy device detection isn\u2019t reliable \u2013 the PS Vita declares itself to be mobile, a mobile device and a Kindle Fire tablet, while the two DS devices state they\u2019re neither mobile nor mobile phones nor tablets, but computers. They\u2019re weird outliers, but they\u2019re still important devices to consider.\n\nThinking broadly about how our designs will be interacted with and viewed on a TV screen can help improve that experience for everyone. This is about accessibility. Considering how someone uses a site with a D-pad, we can improve the experience for keyboard users. When we think about colour contrast and text legibility on TV screens, we can apply that for anyone who reads content on the web. So why just offer this to the TV users?\n\nPlaying with the browser\n\n\n\t\u2026we want to prove to them through this Wii U Internet Browser that browsing itself can be an entertainment.\nIwata \u2013 Iwata Asks on Nintendo.com\n\n\nAlthough I\u2019m cautious about designing experiences for specific devices, it\u2019s fun to experiment with the technology available. Nintendo have promised web developers access to the Wii U\u2019s buttons and sensors. There\u2019s already some JavaScript documentation, and a demo for you to try.\n\nIf you\u2019re interested in making your own games, thanks to web standards, a lot of HTML5 games work already on the device. Matt Hackett wrote up his experience of testing the game he built, and he talks about some of features the browser lacks. There\u2019s certainly an incentive there for console manufacturers to improve their HTML5 support so more games can be played in their browser.\n\nWhat excites me about consoles is that it\u2019s like looking at what might be available to us in future browsers. As well as thinking about how our sites work on small screens, we should also consider big screens. We\u2019re already figuring out how images should work at different screen widths and connection speeds, but we\u2019ve also got some interesting challenges ahead of us catering for second screen experiences and 3D-enabled devices. \n\nSo, this Christmas, if you\u2019re huddled round the game console or a smart TV, give the browser in it a try.", "year": "2012", "author": "Anna Debenham", "author_slug": "annadebenham", "published": "2012-12-22T00:00:00+00:00", "url": "https://24ways.org/2012/unwrapping-the-wii-u-browser/", "topic": "ux"}
{"rowid": 215, "title": "Teach the CLI to Talk Back", "contents": "The CLI is a daunting tool. It\u2019s quick, powerful, but it\u2019s also incredibly easy to screw things up in \u2013 either with a mistyped command, or a correctly typed command used at the wrong moment. This puts a lot of people off using it, but it doesn\u2019t have to be this way.\nIf you\u2019ve ever interacted with Slack\u2019s Slackbot to set a reminder or ask a question, you\u2019re basically using a command line interface, but it feels more like having a conversation. (My favourite Slack app is Lunch Train which helps with the thankless task of herding colleagues to a particular lunch venue on time.)\nSame goes with voice-operated assistants like Alexa, Siri and Google Home. There are even games, like Lifeline, where you interact with a stranded astronaut via pseudo SMS, and KOMRAD where you chat with a Soviet AI.\nI\u2019m not aiming to build an AI here \u2013 my aspirations are a little more down to earth. What I\u2019d like is to make the CLI a friendlier, more forgiving, and more intuitive tool for new or reluctant users. I want to teach it to talk back.\nInteractive command lines in the wild\nIf you\u2019ve used dev tools in the command line, you\u2019ve probably already used an interactive prompt \u2013 something that asks you questions and responds based on your answers. Here are some examples:\nYeoman\nIf you have Yeoman globally installed, running yo will start a command prompt.\n\nThe prompt asks you what you\u2019d like to do, and gives you options with how to proceed. Seasoned users will run specific commands for these options rather than go through this prompt, but it\u2019s a nice way to start someone off with using the tool.\nnpm\nIf you\u2019re a Node.js developer, you\u2019re probably familiar with typing npm init to initialise a project. This brings up prompts that will populate a package.json manifest file for that project.\n\nThe alternative would be to expect the user to craft their own package.json, which is more error-prone since it\u2019s in JSON format, so something as trivial as an extraneous comma can throw an error.\nSnyk\nSnyk is a dev tool that checks for known vulnerabilities in your dependencies. Running snyk wizard in the CLI brings up a list of all the known vulnerabilities, and gives you options on how to deal with it \u2013 such as patching the issue, applying a fix by upgrading the problematic dependency, or ignoring the issue (you are then prompted for a reason).\n\nThese decisions get mapped to the manifest and a .snyk file, and committed into the repo so that the settings are the same for everyone who uses that project.\nI work at Snyk, and running the wizard is what made me think about building my own personal assistant in the command line to help me with some boring, repetitive tasks.\nWriting your own\nSomething I do a lot is add bookmarks to styleguides.io \u2013 I pull down the entire repo, copy and paste a template YAML file, and edit to contents. Sometimes I get it wrong and break the site. So I\u2019ve been putting together a tool to help me add bookmarks.\nIt\u2019s called bookmarkbot \u2013 it\u2019s a personal assistant squirrel called Mark who will collect and bury your bookmarks for safekeeping.*\n\n*Fortunately, this metaphor also gives me a charming excuse for any situation where bookmarks sometimes get lost \u2013 it\u2019s not my poorly-written code, honest, it\u2019s just being realistic because sometimes squirrels forget where they buried things!\nWhen you run bookmarkbot, it will ask you for some information, and save that information as a Markdown file in YAML format.\nFor this demo, I\u2019m going to use a Node.js package called inquirer, which is a well supported tool for creating command line prompts. I like it because it has a bunch of different question types; from input, which asks for some text back, confirm which expects a yes/no response, or a list which gives you a set of options to choose from. You can even nest questions, Choose Your Own Adventure style.\nPrerequisites\n\nNode.js\nnpm\nRubyGems (Only if you want to go as far as serving a static site for your bookmarks, and you want to use Jekyll for it)\n\nDisclaimer\nBear in mind that this is a really simplified walkthrough. It doesn\u2019t have any error states, and it doesn\u2019t handle the situation where we save a file with the same name. But it gets you in a good place to start building out your tool.\nLet\u2019s go!\nCreate a new folder wherever you keep your projects, and give it an awesome name (I\u2019ve called mine bookmarks and put it in the Sites directory because I\u2019m unimaginative). Now cd to that directory. \ncd Sites/bookmarks\nLet\u2019s use that example I gave earlier, the trusty npm init.\nnpm init\nPop in the information you\u2019d like to provide, or hit ENTER to skip through and save the defaults. Your directory should now have a package.json file in it. Now let\u2019s install some of the dependencies we\u2019ll need.\nnpm install --save inquirer\nnpm install --save slugify\nNext, add the following snippet to your package.json to tell it to run this file when you run npm start.\n\"scripts\": {\n  \u2026\n  \"start\": \"node index.js\"\n}\nThat index.js file doesn\u2019t exist yet, so let\u2019s create it in the root of our folder, and add the following:\n// Packages we need\nvar fs = require('fs'); // Creates our file (part of Node.js so doesn't need installing)\nvar inquirer = require('inquirer'); // The engine for our questions prompt\nvar slugify = require('slugify'); // Will turn a string into a usable filename\n\n// The questions\nvar questions = [\n  {\n    type: 'input',\n    name: 'name',\n    message: 'What is your name?',\n  },\n];\n\n// The questions prompt\nfunction askQuestions() {\n\n  // Ask questions\n  inquirer.prompt(questions).then(answers => {\n\n    // Things we'll need to generate the output\n    var name = answers.name;\n\n    // Finished asking questions, show the output\n    console.log('Hello ' + name + '!');\n\n  });\n\n}\n\n// Kick off the questions prompt\naskQuestions();\nThis is just some barebones where we\u2019re including the inquirer package we installed earlier. I\u2019ve stored the questions in a variable, and the askQuestions function will prompt the user for their name, and then print \u201cHello <your name>\u201d in the console.\nEnough setup, let\u2019s see some magic. Save the file, go back to the command line and run npm start.\n\nExtending what we\u2019ve learnt\nAt the moment, we\u2019re just saving a name to a file, which isn\u2019t really achieving our goal of saving bookmarks. We don\u2019t want our tool to forget our information every time we talk to it \u2013 we need to save it somewhere. So I\u2019m going to add a little function to write the output to a file.\nSaving to a file\nCreate a folder in your project\u2019s directory called _bookmarks. This is where the bookmarks will be saved.\nI\u2019ve replaced my questions array, and instead of asking for a name, I\u2019ve extended out the questions, asking to be provided with a link and title (as a regular input type), a list of tags (using inquirer\u2019s checkbox type), and finally a description, again, using the input type.\nSo this is how my code looks now:\n// Packages we need\nvar fs = require('fs'); // Creates our file\nvar inquirer = require('inquirer'); // The engine for our questions prompt\nvar slugify = require('slugify'); // Will turn a string into a usable filename\n\n// The questions\nvar questions = [\n  {\n    type: 'input',\n    name: 'link',\n    message: 'What is the url?',\n  },\n  {\n    type: 'input',\n    name: 'title',\n    message: 'What is the title?',\n  },\n  {\n    type: 'checkbox',\n    name: 'tags',\n    message: 'Would you like me to add any tags?',\n    choices: [\n      { name: 'frontend' },\n      { name: 'backend' },\n      { name: 'security' },\n      { name: 'design' },\n      { name: 'process' },\n      { name: 'business' },\n    ],\n  },\n  {\n    type: 'input',\n    name: 'description',\n    message: 'How about a description?',\n  },\n];\n\n// The questions prompt\nfunction askQuestions() {\n\n  // Say hello\n  console.log('\ud83d\udc3f  Oh, hello! Found something you want me to bookmark?\\n');\n\n  // Ask questions\n  inquirer.prompt(questions).then((answers) => {\n\n    // Things we'll need to generate the output\n    var title = answers.title;\n    var link = answers.link;\n    var tags = answers.tags + '';\n    var description = answers.description;\n    var output = '---\\n' +\n                 'title: \"' + title + '\"\\n' +\n                 'link: \"' + link + '\"\\n' +\n                 'tags: [' + tags + ']\\n' +\n                 '---\\n' + description + '\\n';\n\n    // Finished asking questions, show the output\n    console.log('\\n\ud83d\udc3f  All done! Here is what I\\'ve written down:\\n');\n    console.log(output);\n\n    // Things we'll need to generate the filename\n    var slug = slugify(title);\n    var filename = '_bookmarks/' + slug + '.md';\n\n    // Write the file\n    fs.writeFile(filename, output, function () {\n      console.log('\\n\ud83d\udc3f  Great! I have saved your bookmark to ' + filename);\n    });\n\n  });\n\n}\n\n// Kick off the questions prompt\naskQuestions();\nThe output is formatted into YAML metadata as a Markdown file, which will allow us to turn it into a static HTML file using a build tool later. Run npm start again and have a look at the file it outputs.\n\nGetting confirmation\nBefore the user makes critical changes, it\u2019s good to verify those changes first. We\u2019re going to add a confirmation step to our tool, before writing the file. More seasoned CLI users may favour speed over a \u201chey, can you wait a sec and just check this is all ok\u201d step, but I always think it\u2019s worth adding one so you can occasionally save someone\u2019s butt.\nSo, underneath our questions array, let\u2019s add a confirmation array.\n// Packages we need\n\u2026\n// The questions\n\u2026\n\n// Confirmation questions\nvar confirm = [\n  {\n    type: 'confirm',\n    name: 'confirm',\n    message: 'Does this look good?',\n  },\n];\n\n// The questions prompt\n\u2026\n\nAs we\u2019re adding the confirm step before the file gets written, we\u2019ll need to add the following inside the askQuestions function:\n// The questions prompt\nfunction askQuestions() {\n  // Say hello\n  \u2026\n  // Ask questions\n  inquirer.prompt(questions).then((answers) => {\n    \u2026\n    // Things we'll need to generate the output\n    \u2026\n    // Finished asking questions, show the output\n    \u2026\n\n    // Confirm output is correct\n    inquirer.prompt(confirm).then(answers => {\n\n      // Things we'll need to generate the filename\n      var slug = slugify(title);\n      var filename = '_bookmarks/' + slug + '.md';\n\n      if (answers.confirm) {\n        // Save output into file\n        fs.writeFile(filename, output, function () {\n          console.log('\\n\ud83d\udc3f  Great! I have saved your bookmark to ' +\n          filename);\n        });\n      } else {\n        // Ask the questions again\n        console.log('\\n\ud83d\udc3f  Oops, let\\'s try again!\\n');\n        askQuestions();\n      }\n\n    });\n\n  });\n}\n\n// Kick off the questions prompt\naskQuestions();\nNow run npm start and give it a go!\n\nTyping y will write the file, and n will take you back to the start. Ideally, I\u2019d store the answers already given as defaults so the user doesn\u2019t have to start from scratch, but I want to keep this demo simple.\nServing the files\nNow that your bookmarking tool is successfully saving formatted Markdown files to a folder, the next step is to serve those files in a way that lets you share them online. The easiest way to do this is to use a static-site generator to convert your YAML files into HTML, and pop them all on one page. Now, you\u2019ve got a few options here and I don\u2019t want to force you down any particular path, as there are plenty out there \u2013 it\u2019s just a case of using the one you\u2019re most comfortable with.\nI personally favour Jekyll because of its tight integration with GitHub Pages \u2013 I don\u2019t want to mess around with hosting and deployment, so it\u2019s really handy to have my bookmarks publish themselves on my site as soon as I commit and push them using Git.\nI\u2019ll give you a very brief run-through of how I\u2019m doing this with bookmarkbot, but I recommend you read my Get Started With GitHub Pages (Plus Bonus Jekyll) guide if you\u2019re unfamiliar with them, because I\u2019ll be glossing over some bits that are already covered in there.\nSetting up a build tool\nIf you haven\u2019t already, install Jekyll and Bundler globally through RubyGems. Jekyll is our static-site generator, and Bundler is what we use to install Ruby dependencies.\ngem install jekyll bundler\nIn my project folder, I\u2019m going to run the following which will install the Jekyll files we\u2019ll need to build our listing page. I\u2019m using --force, otherwise it will complain that the directory isn\u2019t empty.\njekyll new . --force\nIf you check your project folder, you\u2019ll see a bunch of new files. Now run the following to start the server:\nbundle exec jekyll serve\nThis will build a new directory called _site. This is where your static HTML files have been generated. Don\u2019t touch anything in this folder because it will get overwritten the next time you build.\nNow that serve is running, go to http://127.0.0.1:4000/ and you\u2019ll see the default Jekyll page and know that things are set up right. Now, instead, we want to see our list of bookmarks that are saved in the _bookmarks directory (make sure you\u2019ve got a few saved). So let\u2019s get that set up next.\nOpen up the _config.yml file that Jekyll added earlier. In here, we\u2019re going to tell it about our bookmarks. Replace everything in your _config.yml file with the following:\ntitle: My Bookmarks\ndescription: These are some of my favourite articles about the web.\nmarkdown: kramdown\nbaseurl: /bookmarks # This needs to be the same name as whatever you call your repo on GitHub.\ncollections:\n  - bookmarks\nThis will make Jekyll aware of our _bookmarks folder so that we can call it later. Next, create a new directory and file at _layouts/home.html and paste in the following.\n<!doctype html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\" />\n  <title>{{site.title}}</title>\n  <meta name=\"description\" content=\"{{site.description}}\">\n</head>\n\n<body>\n\n  <h1>{{site.title}}</h1>\n  <p>{{site.description}}</p>\n\n  <ul>\n    {% for bookmark in site.bookmarks %}\n    <li>\n      <a href=\"{{bookmark.link}}\">\n        <h2>{{bookmark.title}}</h2>\n      </a>\n      {{bookmark.content}}\n      {% if bookmark.tags %}\n      <ul>\n        {% for tags in bookmark.tags %}<li>{{tags}}</li>{% endfor %}\n      </ul>\n      {% endif %}\n    </li>\n    {% endfor %}\n  </ul>\n\n</body>\n\n</html>\nRestart Jekyll for your config changes to kick in, and go to the url it provides you (probably http://127.0.0.1:4000/bookmarks, unless you gave something different as your baseurl).\n\nIt\u2019s a decent start \u2013 there\u2019s a lot more we can do in this area but now we\u2019ve got a nice list of all our bookmarks, let\u2019s get it online!\nIf you want to use GitHub Pages to host your files, your first step is to push your project to GitHub. Go to your repository and click \u201csettings\u201d. Scroll down to the section labelled \u201cGitHub Pages\u201d, and from here you can enable it. Select your master branch, and it will provide you with a url to view your published pages.\n\nWhat next?\nNow that you\u2019ve got a framework in place for publishing bookmarks, you can really go to town on your listing page and make it your own. First thing you\u2019ll probably want to do is add some CSS, then when you\u2019ve added a bunch of bookmarks, you\u2019ll probably want to have some filtering in place for the tags, perhaps extend the types of questions that you ask to include an image (if you\u2019re feeling extra-fancy, you could just ask for a url and pull in metadata from the site itself). Maybe you\u2019ve got an idea that doesn\u2019t involve bookmarks at all.\nYou could use what you\u2019ve learnt to build a place where you can share quotes, a list of your favourite restaurants, or even Christmas gift ideas.\nHere\u2019s one I made earlier\n\nMy demo, bookmarkbot, is on GitHub, and I\u2019ve reused a lot of the code from styleguides.io. Feel free to grab bits of code from there, and do share what you end up making!", "year": "2017", "author": "Anna Debenham", "author_slug": "annadebenham", "published": "2017-12-11T00:00:00+00:00", "url": "https://24ways.org/2017/teach-the-cli-to-talk-back/", "topic": "code"}
{"rowid": 244, "title": "It\u2019s Beginning to Look a Lot Like XSSmas", "contents": "I dread the office Secret Santa. I have a knack for choosing well-meaning but inappropriate presents, like a bottle of port for a teetotaller, a cheese-tasting experience for a vegan, or heaven forbid, Spurs socks for an Arsenal supporter. Ok, the last one was intentional.\nIt\u2019s the same with gifting code. Once, I made a pattern library for A List Apart which I open sourced, and a few weeks later, a glaring security vulnerability was found in it. My gift was so generous that it enabled unrestricted access to any file on any public-facing server that hosted it.\nWith platforms like GitHub and npm, giving the gift of code is so easy it\u2019s practically a no-brainer. This giant, open source yankee swap helps us do our jobs without starting from scratch with every project. But like any gift-giving, it\u2019s also risky.\nVulnerabilities and Open Source\nOpen source code is not inherently more or less vulnerable than closed-source code. What makes it higher risk is that the same piece of code gets reused in lots of places, meaning a hacker can use the same exploit mechanism on the same vulnerable code in different apps.\nGraph showing the number of open source vulnerabilities published per year, from the State of Open Source Security 2017\nIn the first 24 ways article this year, Katie referenced a few different types of vulnerability:\n\nCross-site Request Forgery (also known as CSRF)\nSQL Injection\nCross-site Scripting (also known as XSS)\n\nThere are many more types of vulnerability, and those that live under the same category share similarities. \nFor example, my favourite \u2013 is it weird to have a favourite vulnerability? \u2013 is Cross Site Scripting (XSS), which allows for the injection of scripts into web pages. This is a really common vulnerability often unwittingly added by developers. OWASP (the Open Web Application Security Project) wrote a great article about how to prevent opening the door to XSS attacks \u2013 share it generously with your colleagues.\nMost vulnerabilities like this are not added intentionally \u2013 they\u2019re doors left ajar due to the way something has been scripted, like the over-generous code in my pattern library. \nOthers, though, are added intentionally. A few months ago, a hacker, disguised as a helpful elf, offered to take over the maintenance of a popular npm package that had been unmaintained for a couple of years. The owner had moved onto other projects, and was keen to see it continue to be maintained by someone else, so transferred ownership. Fast-forward 3 months, it was discovered that the individual had quietly added a malicious package to the codebase, and the obfuscated code in it had been unwittingly installed onto thousands of apps. The code added was designed to harvest Bitcoin if it was run alongside another application. It was only spotted due to a developer\u2019s curiosity.\nAnother tactic to get developers to unwittingly install malicious packages into their codebase is \u201ctyposquatting\u201d \u2013 back in August last year, npm reported that a user had been publishing packages with very similar names to popular packages (for example, crossenv instead of cross-env). \nThis is a big wakeup call for open source maintainers. Techniques like this are likely to be used more as the maintenance of open source libraries becomes an increasing burden to their owners. After all, starting a new project often has a greater reward than maintaining an existing one, but remember, an open source library is for life, not just for Christmas.\nSanta\u2019s on his sleigh\nIf you use open source libraries, chances are that these libraries also use open source libraries. Your app may only have a handful of dependencies, but tucked in the back of that sleigh may be a whole extra sack of dependencies known as deep dependencies (ones that you didn\u2019t directly install, but are dependencies of that dependency), and these can contain vulnerabilities too.\nLet\u2019s look at the npm package santa as an example. santa has 8 direct dependencies listed on npm. That seems pretty manageable. But that\u2019s just the tip of the iceberg \u2013 have a look at the full dependency tree which contains 109 dependencies \u2013 more dependencies than there are Christmas puns in this article. Only one of these direct dependencies has a vulnerability (at the time of writing), but there are actually 13 other known vulnerabilities in santa, which have been introduced through its deeper dependencies.\nFixing vulnerabilities \u2013 the ultimate christmas gift\nIf you\u2019re a maintainer of open source libraries, taking good care of them is the ultimate gift you can give. Keep your dependencies up to date, use a security tool to monitor and alert you when new vulnerabilities are found in your code, and fix or patch them promptly. This will help keep the whole open source ecosystem healthy.\nWhen you find out about a new vulnerability, you have some options:\nFix the vulnerability via an upgrade\nYou can often fix a vulnerability by upgrading the library to the latest version. Make sure you\u2019re using software that monitors your dependencies for new security issues and lets you know when a fix is ready, otherwise you may be unwittingly using a vulnerable version.\nPatch the vulnerable code\nSometimes, a fix for a vulnerable library isn\u2019t possible. This is often the case when a library is no longer being maintained, or the version of the library being used might be so out of date that upgrading it would cause a breaking change. Patches are bits of code that will fix that particular issue, but won\u2019t change anything else.\nSwitch to a different library\nIf the library you\u2019re using has no fix or patch, you may be better of switching it out for another one, particularly if it looks like it\u2019s being unmaintained.\nResponsibly disclosing vulnerabilities\nKnowing how to responsibly disclose vulnerabilities is something I\u2019m ashamed to admit that I didn\u2019t know about before I joined a security company. But it\u2019s so important! On discovering a new vulnerability, a developer has a few options: \n\nA malicious developer will exploit that vulnerability for their own gain. \nA reckless (or inexperienced) developer will disclose that vulnerability to the world without following a responsible disclosure process. This opens the door to an unethical developer exploiting the vulnerability. At Snyk, we monitor social media for mentions of newly found vulnerabilities so we can add them to our database and share fixes before they get exploited.\nAn ethical and aware developer will follow what\u2019s known as a \u201cresponsible disclosure process\u201d. They will contact the maintainer of the code privately, allowing reasonable time for them to release a fix for the issue and to give others who use that vulnerable code a chance to fix it too.\n\nIt\u2019s important to understand this process if you\u2019re a maintainer or contributor of code. It can be daunting when a report comes in, but understanding and following the right steps will help reduce the risk to the people who use that code.\nSo what does responsible disclosure look like? I\u2019ll take Node.js\u2019s security disclosure policy as an example. They ask that all security issues that are found in Node.js are reported there. (There\u2019s a separate process for bug found in third-party npm packages). Once you\u2019ve reported a vulnerability, they promise to acknowledge it within 24 hours, and to give a more detailed response within 48 hours. If they find that the issue is indeed a security bug, they\u2019ll give you regular updates about the progress they\u2019re making towards fixing it. As part of this, they\u2019ll figure out which versions are affected, and prepare fixes for them. They\u2019ll assign the vulnerability a CVE (Common Vulnerabilities and Exposures) ID and decide on an embargo date for public disclosure. On the date of the embargo, they announce the vulnerability in their Node.js security mailing list and deploy fixes to nodejs.org.\nTim Kadlec published an in-depth article about responsible disclosures if you\u2019re interested in knowing more. It has some interesting horror stories of what happened when the disclosure process was not followed.\nEncourage responsible disclosure\nAdd a SECURITY.md file to your project so someone who wants to message you about a vulnerability can do so without having to hunt around for contact details. Last year, Snyk published a State of Open Source Security report that found 79.5% of maintainers do not have a public disclosure policy. Those that did were considerably more likely to get notified privately about a vulnerability \u2013 73% of maintainers who had one had been notified, vs 21% of maintainers who hadn\u2019t published one one.\nStats from the State of Open Source Security 2017\nBug bounties\nSome companies run bug bounties to encourage the responsible disclosure of vulnerabilities. By offering a reward for finding and safely disclosing a vulnerability, it also reduces the enticement of exploiting a vulnerability over reporting it and getting a quick cash reward. Hackerone is a community of ethical hackers who pentest apps that have signed up for the scheme and get paid when they find a new vulnerability. Wordpress is one such participant, and you can see the long list of vulnerabilities that have been disclosed as part of that program.\nIf you don\u2019t have such a bounty, be prepared to get the odd vulnerability extortion email. Scott Helme, who founded securityheaders.com and report-uri.com, wrote a post about some of the requests he gets for a report about a critical vulnerability in exchange for money. \n\nOn one hand, I want to be as responsible as possible and if my users are at risk then I need to know and patch this issue to protect them. On the other hand this is such irresponsible and unethical behaviour that interacting with this person seems out of the question.\n\nA gift worth giving\nIt\u2019s time to brush the dust off those old gifts that we shared and forgot about. Practice good hygiene and run them through your favourite security tool \u2013 I\u2019m just a little biased towards Snyk, but as Katie mentioned, there\u2019s also npm audit if you use Node.js, and most source code managers like GitHub and GitLab have basic vulnerability alert capabilities.\nStats from the State of Open Source Security 2017\nMost importantly, patch or upgrade away those vulnerabilities away, and if you want to share that Christmas spirit, open fixes for your favourite open source projects, too.", "year": "2018", "author": "Anna Debenham", "author_slug": "annadebenham", "published": "2018-12-17T00:00:00+00:00", "url": "https://24ways.org/2018/its-beginning-to-look-a-lot-like-xssmas/", "topic": "code"}
{"rowid": 282, "title": "Front-end Style Guides", "contents": "We all know that feeling: some time after we launch a site, new designers and developers come in and make adjustments. They add styles that don\u2019t fit with the content, use typefaces that make us cringe, or chuck in bloated code. But if we didn\u2019t leave behind any documentation, we can\u2019t really blame them for messing up our hard work.\n\nTo counter this problem, graphic designers are often commissioned to produce style guides as part of a rebranding project. A style guide provides details such as how much white space should surround a logo, which typefaces and colours a brand uses, along with when and where it is appropriate to use them.\n\nDesign guidelines\n\nSome design guidelines focus on visual branding and identity. The UK National Health Service (NHS) refer to theirs as \u201cbrand guidelines\u201d. They help any designer create something such as a trustworthy leaflet for an NHS doctor\u2019s surgery. Similarly, Transport for London\u2019s \u201cdesign standards\u201d ensure the correct logos and typefaces are used in communications, and that they comply with the Disability Discrimination Act.\n\nSome guidelines go further, encompassing a whole experience, from the visual branding to the messaging, and the icon sets used. The BBC calls its guidelines a \u201cGlobal Experience Language\u201d or GEL. It\u2019s essential for maintaining coherence across multiple sites under the same BBC brand.\n\n\nThe BBC\u2019s Global Experience Language.\n\nDesign guidelines may be brief and loose to promote creativity, like Mozilla\u2019s \u201cbrand toolkit\u201d, or be precise and run to many pages to encourage greater conformity, such as Apple\u2019s \u201cHuman Interface Guidelines\u201d.\n\nWhatever name or form they\u2019re given, documenting reusable styles is invaluable when maintaining a brand identity over time, particularly when more than one person (who may not be a designer) is producing material.\n\nCode standards documents\n\nWe can make a similar argument for code. For example, in open source projects, where hundreds of developers are submitting code, it makes sense to set some standards. Drupal and Wordpress have written standards that make editing code less confusing for users, and more maintainable for contributors.\n\nEach community has nuances: Drupal requests that developers indent with two spaces, while Wordpress stipulates a tab. Whatever the rules, good code standards documents also explain why they make their recommendations.\n\nThe front-end developer\u2019s style guide\n\nDesign style guides and code standards documents have been a successful way of ensuring brand and code consistency, but in between the code and the design examples, web-based style guides are emerging. These are maintained by front-end developers, and are more dynamic than visual design guidelines, documenting every component and its code on the site in one place.\n\nHere are a few examples I\u2019ve seen in the wild:\n\nNatalie Downe\u2019s pattern portfolio\n\nNatalie created the pattern portfolio system while working at Clearleft. The phrase describes a single HTML page containing all the site\u2019s components and styles that can act as a deliverable.\n\n\nPattern portfolio by Natalie Downe for St Paul\u2019s School, kept up to date when new components are added. The entire page is about four times the length shown.\n\nEach different item within a pattern portfolio is a building block or module. The components are decoupled from the layout, and linearized so they can slot into anywhere on a page.\n\n\n\tThe pattern portfolio expresses every component and layout structure in the smallest number of documents. It sets out how the markup and CSS should be, and is used to illustrate the project\u2019s shared vocabulary.\n\n\tNatalie Downe\n\n\nBy developing a system, rather than individual pages, the result is flexible when the client wants to add more pages later on.\n\nPaul Lloyd\u2019s style guide\n\nPaul Lloyd has written an extremely comprehensive style guide for his site. Not only does it feature every plausible element, but it also explains in detail when it\u2019s appropriate to use each one.\n\n\nPaul\u2019s style guide is also great educational material for people learning to write code.\n\nOli Studholme\u2019s style guide\n\nEven though Oli\u2019s style guide is specific to his site, he\u2019s written it as though it\u2019s for someone else. It\u2019s exhaustive and gives justifications for all his decisions. In some places, he links to browser bug tickets and makes recommendations for cross-browser compatibility.\n\n\nOli has released his style guide under a Creative Commons Attribution Share-alike license, and encourages others to create their own versions.\n\nJeremy Keith\u2019s pattern primer\n\nFront-end style guides may have comments written in the code, annotations that appear on the page, or they may list components alongside their code, like Jeremy\u2019s pattern primer.\n\n\nYou can watch or fork Jeremy\u2019s pattern primer on Github.\n\n\n\nLinearizing components like this resembles a kind of mobile first approach to development, which Jeremy talks about on the 5by5 podcast: The Web Ahead 3.\n\nThe benefits of maintaining a front-end style guide\n\nIf you still need convincing that producing documentation like this for every project is worth the effort, here are a few nice side-effects to working this way:\n\nEasier to test\n\nA unified style guide makes it easier to spot where your design breaks. It\u2019s simple to check how components adapt to different screen widths, test for browser bugs and develop print style sheets when everything is on the same page. When I worked with Natalie, she\u2019d resize the browser window and bump the text size up and down during development to see if anything would break.\n\nBetter workflow\n\nThe approach also forces you to think how something works in relation to the whole site, rather than just a specific page, making it easier to add more pages later on. Starting development by creating a style guide makes a lot more sense than developing on a page-by-page basis.\n\nShared vocabulary\n\nNatalie\u2019s pattern portfolio in particular creates a shared vocabulary of names for components (teaser, global navigation, carousel\u2026), so a team can refer to different regions of the site and have a shared understanding of its meaning.\n\nUseful reference\n\nA combined style guide also helps designers and writers to see the elements that will be incorporated in the site and, therefore, which need to be designed or populated. A boilerplate list of components for every project can act as a reminder of things that may get missed in the design, such as button states or error messages. \n\nCreating your front-end style guide\n\nAs you\u2019ve seen, there are plenty of variations on the web style guide. Which method is best depends on your project and workflow. Let\u2019s say you want to show your content team how blockquotes and asides look, when it\u2019s appropriate to use them, and how to create them within the CMS. In this case, a combination of Jeremy\u2019s pattern primer and Paul\u2019s descriptive style guide \u2013 with the styled component alongside a code snippet and a description of when to use it \u2013 may be ideal. \n\nStart work on your style guide as soon as you can, preferably during the design stage:\n\n\n\tSimply presenting flat image comps is by no means enough\u2009-\u2009it\u2019s only the start\u2026 As layouts become more adaptable, flexible and context-specific, so individual components will become the focus of our design. It is therefore essential to get the foundational aspects of our designs right, and style guides allow us to do that.\n\n\tPaul Lloyd on Style guides for the Web \n\n\n\n\tPrint out the designs and label the unique elements and components you\u2019ll need to add to your style guide. Make a note of the purpose of each component. While you\u2019re doing this, identify the main colours used for things like links, headings and buttons.\nI draw over the print-outs on to tracing paper so I can make more annotations. Here, I\u2019ve started annotating the widths from the designer\u2019s mockup so I can translate these into percentages.\n\tStart developing your style guide with base styles that target core elements: headings, links, tables, blockquotes, ordered lists, unordered lists and forms. For these elements, you could maintain a standard document to reuse for every project.\n\tNext, add the components that override the base styles, like search boxes, breadcrumbs, feedback messages and blog comments. Include interaction styles, such as hover, focus and visited state on links, and hover, focus and active states on buttons.\n\tNow start adding layout and begin slotting the components into place. You may want to present each layout as a separate document, or you could have them all on the same page stacked beneath one another.\n\n\nDocument code practices\n\nCode can look messy when people use different conventions, so note down a standard approach alongside your style guide. For example, Paul Stanton has documented how he writes CSS.\n\nThe gift wrapping\n\nPresenting this documentation to your client may be a little overwhelming so, to be really helpful, create a simple page that links together all your files and explains what each of them do.\n\n\nThis is an example of a contents page that Clearleft produce for their clients. They\u2019ve added date stamps, subversion revision numbers and written notes for each file.\n\nEncourage participation\n\nThere\u2019s always a risk that the person you\u2019re writing the style guide for will ignore it completely, so make your documentation as user-friendly as possible. Justify why you do things a certain way to make it more approachable and encourage similar behaviour.\n\nAs always, good communication helps. Working with the designer to put together this document will improve the site. It\u2019s often not practical for designers to provide a style for everything, so drafting a web style guide and asking for feedback gives designers a chance to make sure any default styles fit in.\n\nIf you work in a team with other developers, documenting your code and development decisions will not only be useful as a deliverable, but will also force you to think about why you do things a certain way.\n\nFuture-friendly\n\nThe roles of designer and developer are increasingly blurred, yet all too often we work in isolation. Working side-by-side with designers on web style guides can vastly improve the quality of our work, and the collaborative approach can spark discussions like \u201chow would this work on a smaller screen?\u201d\n\nSometimes we can be so focused on getting the site ready and live, that we lose sight of what happens after it\u2019s launched, and how it\u2019s going to be maintained. A simple web style guide can make all the difference.\n\nIf you make your own style guide, I\u2019d love to add it to my stash of examples so please share a link to it in the comments.", "year": "2011", "author": "Anna Debenham", "author_slug": "annadebenham", "published": "2011-12-07T00:00:00+00:00", "url": "https://24ways.org/2011/front-end-style-guides/", "topic": "process"}