{"id":7221,"date":"2016-12-11T16:04:20","date_gmt":"2016-12-11T20:04:20","guid":{"rendered":"http:\/\/www.useragentman.com\/blog\/?p=7221"},"modified":"2016-12-15T14:55:07","modified_gmt":"2016-12-15T18:55:07","slug":"making-framework-agnostic-isomorphic-web-applications-with-query-strings-and-html5-pushstate","status":"publish","type":"post","link":"https:\/\/www.useragentman.com\/blog\/2016\/12\/11\/making-framework-agnostic-isomorphic-web-applications-with-query-strings-and-html5-pushstate\/","title":{"rendered":"Making Framework Agnostic Isomorphic Web Applications with Query Strings and HTML5 pushState"},"content":{"rendered":"\r\n
\r\n\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n<\/picture>\r\n\r\n<\/div>\r\n

With frameworks like React<\/a> in vogue today, there is a lot of HTML being rendered exclusively on the client instead of the server, where it has traditionally occured. While this can result in some really snappy and slick interactions, there are a few issues with doing this: <\/p>\n

    \n
  1. They do not work when the client has JavaScript turned off.<\/li>\n
  2. In low bandwidth environments, performance will be sluggish at load time if the application is JavaScript heavy, since (usually) the majority of the JavaScript needs to load before the page state can be applied to the application. This is a huge consideration with mobile wireless connections, where you cannot guarantee a great signal all the time.<\/li>\n
  3. Sharing that state of a “single page application” via social media\/email\/instant messaging platforms can be problematic unless the URL can change when the state changes<\/strong>.\n<\/ol>\n

    To handle the first two issues, the first-render of the application should be done by the server instead of the client.<\/strong> This will allow users to see the page data immediately while the page loads all the assets, increasing the performance of the page at load time. Also, as the state of the page changes, the URL should also change. If the user wants to share that change, then it’s easy as sharing that URL. And since the first-render of that page will be done by the server, you can program the server side code to have the application give appropriate Facebook Open Graph<\/a> and Twitter Card<\/a> meta tag information on first load that reflects that change to social media sites to make sharing nicer.<\/p>\n

    When HTML5 single page applications first became popular a while back, we hit a snag — we couldn’t change the URL of the application without causing a browser refresh. In order to work around this, many JavaScript routing frameworks (like Backbone) would change the URL hash<\/a> of the page in order to maintain state. This worked, but at a cost of sharing the state — social media sites would not be able to know the state of the application since the URL hash is never sent to the server via HTTP<\/a>. Furthermore, Social Media platforms like Facebook cannot use Fragment Identifiers to distinguish different states of an application<\/a>, which causes issues if you want Facebook users to be able to “Like” specific states of an application (e.g. the photo-gallery section of the application vs. other parts of the page).<\/p>\n

    Now, however, we can use HTML5 Session Management<\/a> to change the browser’s URL within a single page web application without the browser going to the server to load the page for that URL. Furthermore, when the user clicks the back button, this Session Management API can be used to ensure that state of the page for that URL can also be rendered without a full server page load. I took this a step further and wrote progressive-pushstate<\/a>, a JavaScript library which parses the data from a query string and sets this as the application’s history.state<\/code> (the JavaScript object that HTML5 Session Management uses to keep state). Links and forms on the page that change the document’s query string can be rendered by JavaScript the same way they would be rendered if that URL and query string were requested by the web server. This also allows us to change the query string if form elements are changed without hitting the submit button.<\/p>\n

    Go to the progressive-pushstate GitHub page<\/a><\/p>\n

    If you are confused about the power of this, let’s look at some simple examples.<\/p>\n

    Example 1: A Simple Mobile\/Desktop Navigation System<\/h2>\n

    Let’s say you have to build a website that uses a <select><\/code> box “hamburger” menu in the mobile breakpoint, but a traditional “list of links” menu for the larger breakpoints: <\/p>\n\r\n\r\n\r\n\r\n\r\n
    This table contains screenshots of a web page that uses a select-box hamburger menu in the mobile breakpoint, and a traditional nav bar for larger breakpoints<\/caption>\r\n
    Mobile Breakpoint<\/th>Desktop Breakpoint<\/th><\/tr>\r\n<\/thead>\r\n
    \r\n\"screenshot\r\n<\/td>\r\n\r\n\"screenshot\r\n<\/td>\r\n<\/tr>\r\n<\/tbody>\r\n<\/table>\r\n

    Look at live version of the the hybrid nav solution using progressive-pushstate<\/a><\/p>\n

    Let’s look briefly at the markup that makes this happen:<\/p>\n

    \n
    \r\n<nav class=\"fixedsticky\">\r\n    \r\n  <!-- The CSS makes this visible only when the page is wider than 768px -->\r\n  <ul>\r\n    <li><a class=\"pp-link\" href=\"?f=home\">Home<\/a><\/li>\r\n    <li><a class=\"pp-link\" href=\"?f=donkey-kong\"<\/span>>Donkey Kong<\/a><\/li>\r\n    <li><a class=\"pp-link\" href=\"?f=pac-man\">Pac-Man<\/a><\/li>\r\n    <li><a class=\"pp-link\" href=\"?f=robotron\">Robotron<\/a><\/li>\r\n    <li><a class=\"pp-link\" href=\"?f=tempest\">Tempest<\/a><\/li>\r\n  <\/ul>\r\n\r\n  <!-- The CSS makes this visible only when the page is narrower than 768px -->\r\n  <form class=\"pp-form\" data-pp-events=\"change\"<\/span>>\r\n    <select name=\"f\">\r\n      <option value=\"home\" selected>Home<\/option>\r\n      <option value=\"donkey-kong\"<\/span>>Donkey Kong<\/option>\r\n      <option value=\"pac-man\">Pac-Man<\/option>\r\n      <option value=\"robotron\">Robotron<\/option>\r\n      <option value=\"tempest\">Tempest<\/option>\r\n    <\/select>\r\n\r\n  <\/form>\r\n<\/nav>\r\n\r\n<script src=\"\/path\/to\/progressive-pushstate.js\"><\/script>  \r\n<!-- not needed for progressive-pushstate, but used in page code -->\r\n<script src=\"\/path\/to\/jquery-3.1.1.min.js\"><\/script>\r\n<script src=\"\/path\/to\/example02.js\"><\/script>\r\n\r\n<\/pre>\n<\/blockquote>\n
    If you take a look at the navigation markup, you will see that the links will submit a query string that would be identical if the form were to submit.  Since the links have a class of pp-link<\/code>, progressive-pushstate will know to override the browser’s default behaviour and handle the links. Since the form has a class of pp-form<\/code> and has data-pp-events<\/code> set to \"change\"<\/code>, progressive-pushstate knows that it must fire when any of its fields change.<\/p>\n
    So, how does progressive-pushstate handle the link behaviour?  In example02.js, you will see the following code:<\/p>\n
    \n
    \r\nvar example1 = new function () {\r\n  \r\n  \/\/ Use me to avoid using .bind() all over the place.\r\n  var me = this;\r\n  \r\n  me.init = function () {\r\n    pp.init(me.popstateEvent);\r\n  };\r\n  \r\n  me.popstateEvent = function(e) {\r\n    currentState = e.state;\r\n    \r\n    \/*\r\n     * At this point, `currentState.f` will be set to whatever value `f` is in\r\n     * the query string.\r\n     *\/\r\n    \r\n    .\r\n    .\r\n    .\r\n    \/\/ rest of the logic is here.\r\n  }\r\n}\r\n\r\nexample1.init();\r\n<\/pre>\n<\/blockquote>\n
    The init()<\/code> method calls pp.init(me.popstateEvent)<\/code>, which initializes progressive-pushstate so that pp-link<\/code> links and pp-form<\/code> forms will be handled by the script. When these links and forms are used, progressive-pushstate will convert the resultant query string  to a JavaScript object and set it as the pushState for that URL.  It will then call example01.js’s popstateEvent()<\/code>, which will change the contents of the main part of the page by grabbing an HTML fragment that corresponds to that page (for the sake of brevity, this logic is not shown in this article, but if you want, please take a look at the full source of example01.js<\/a> to understand how it works).  Note that the `popstateEvent()` method uses e.state<\/code> to find out the state of the page … this is the pushState object we mentioned earlier.<\/p>\n
    There is one thing I did gloss over here — if JavaScript is turned off (or if the browser doesn’t support progressive-pushstate) the mobile navigation will fail to do anything when the select box value changes.  Since we want things to be bullet proof, we add this to the the mobile menu:<\/p>\n
    \n
    \r\n<nav class=\"fixedsticky\">\r\n  \r\n    <!-- The CSS makes this visible only when the page is wider than 768px -->\r\n    <ul>\r\n    <li><a class=\"pp-link\" href=\"?f=home\">Home<\/a><\/li>\r\n    <li><a class=\"pp-link\" href=\"?f=donkey-kong\">Donkey Kong<\/a><\/li>\r\n    <li><a class=\"pp-link\" href=\"?f=pac-man\">Pac-Man<\/a><\/li>\r\n    <li><a class=\"pp-link\" href=\"?f=robotron\">Robotron<\/a><\/li>\r\n    <li><a class=\"pp-link\" href=\"?f=tempest\">Tempest<\/a><\/li>\r\n  <\/ul>\r\n  \r\n  <!-- The CSS makes this visible only when the page is narrower than 768px -->\r\n  <form class=\"pp-form\" data-pp-events=\"change\">\r\n    <select name=\"f\">\r\n      <option value=\"home\" selected>Home<\/option>\r\n      <option value=\"donkey-kong\">Donkey Kong<\/option>\r\n      <option value=\"pac-man\">Pac-Man<\/option>\r\n      <option value=\"robotron\">Robotron<\/option>\r\n      <option value=\"tempest\">Tempest<\/option>\r\n    <\/select>\r\n    \r\n
        <!-- \r\n      * This button only appears when the library is not supported by the\r\n      * browser, or if JavaScript is turned off\r\n    -->\r\n    <input class=\"pp-no-support-button\" type=\"submit\" \r\n      aria-label=\"Go to page selected\" value=\"Go\" \/><\/div>\r\n    \r\n  <\/form>\r\n<\/nav>\r\n<\/pre>\n<\/blockquote>\n
    Note the submit button with the className pp-no-support-button<\/code>.  We want users to press this button if the browser doesn’t support progressive-pushstate.   This will allow the page to submit the form data the old fashioned way so that the page can generate the right HTML on the server.  If you look at the code for example01.php<\/a>, you will see PHP code that does this (this PHP code also does the first render of the page).<\/p>\n
    We use the following CSS to show this button only when the browser can’t support progressive-pushstate (or when JavaScript is turned off):<\/p>\n
    \n
    \r\n.pp-no-support-button {\r\n\tdisplay: inline-block;\r\n}\r\n\r\n.pp-support .pp-no-support-button {\r\n\tdisplay: none;\r\n}\r\n<\/pre>\n<\/blockquote>\n
    The classes pp-support<\/code> is set on the <html><\/code> tag by progressive-pushstate when the page loads if the browser is supported by the library — if not, the library sets the pp-no-support<\/code> class instead. <\/p>\n
    These classes allow developers to give an alternative UI if the library is no supported.  These fallback features that give an expected (but not as sexy) user experience to older and JavaScript-disabled browsers are a great example of progressive enhancement, which is why I called this library progressive-<\/strong>pushstate.js<\/p>\n
    If you use the navigation functionality in the above example to go to several pages, try hitting the back button.  You will notice it remembers history perfectly.  This is because pressing the browser history buttons (i.e. back and forward) will also invoke the popstateEvent<\/code> as well.  History management happens for free!<\/p>\n
    Let’s take a look at another example.<\/p>\n
    Example 2: A “Search As You Type” Page<\/h2>\n
    Many Search Engines (including Google) will show results while the user types in a form.  Let’s look at an example that uses progressive-pushstate:<\/p>\n
    \"Screen
    This basic search form will go to the server while the user is typing in a search term.<\/p><\/div><\/p>\n
    Look at live version of the search example.<\/a><\/p>\n
    You will note that the form will do a search while the user types a search string into it.  This is because we instructed progressive-pushstate to do a search oninput<\/code>:<\/p>\n
    \n
    \r\n<form class=\"pp-form\" data-pp-events=\"input submit\"<\/span>>\r\n  <label for=\"country\">\r\n    Country: \r\n    <input\r\n      autofocus\r\n      type=\"text\"\r\n      id=\"country\"\r\n      name=\"country\"\r\n      placeholder=\"Please enter in a country.\"\r\n      autocomplete=\"off\" \r\n      value=\"\"\/>\r\n    <\/label>\r\n<\/form>\r\n<\/pre>\n<\/blockquote>\n
    The library automatically throttles these submissions in order to prevent really fast typers that type 200 characters a minute from killing the web server with 200 requests a minute.  Note also that history is again baked in, so if users make mistakes or want to see previous searches, they can just press the back button.  Finally, the fallback is simple for JavaScript disabled browsers or browsers that don’t support this library — users can just hit enter to do a search.  This will cause a page refresh, but that’s okay, since the page still works as intended.<\/p>\n
    Example 3: A Filtered Table<\/h2>\n
    Since I am currently working on an accessibility project with my current client, I wanted to build a page with a table that listed all the Web Content Accessibility Guidelines<\/a> with a way to filter them by principle (Perceivable, Operable, Understandable and Robust) as well as level (A, AA and AAA).<\/p>\n
    \"A
    A screen shot of the table filtering example.<\/p><\/div><\/p>\n
    Look at live version of filtered table example.<\/a><\/p>\n
    Again, with a modern browser with Javascript turned on, you will see a nice animation when new rows are added to the table.  When you refresh the page, the table with the proper filters will be generated on the server side.<\/p>\n
    \nNote the submit button at the end of the form.<\/strong> Unlike the previous examples, the content only changes when we submit.  This is to ensure that this page conforms to the WCAG 2.0 (specifically, 3.2.2 \u2013 On Input (Level A)<\/a>.  We force progressive-pushstate to only allow state changes when the form submits.  This is done by setting the form’s data-pp-events<\/code> to \"submit\"<\/code><\/p>\n
    \n
    \r\n<form class=\"pp-form\" autocomplete=\"off\" data-pp-events=\"submit\"<\/span>>\r\n  .\r\n  .\r\n  .\r\n<\/form>\r\n<\/pre>\n<\/blockquote>\n
    If you are using progressive-pushstate to create an accessible website that complies with this international standard, you must<\/strong> do this if you are providing a submit button to initiate a change of context<\/a>.  Note that change of content<\/em> is not always a change of context<\/em><\/a>.\n<\/div>\n
    Pitfalls and Solutions to Isomorphic Applications<\/h2>\n
    When coding isomorphic applications, developers should ensure that the client and the server both display the same data for each URL.  For example, the AJAX requests used in examples #1 and #2 return HTML.  This is the same HTML that would be inserted into the page by the server for that page’s state.  We do this by using PHP’s include<\/code> to call the same PHP code that the AJAX request calls.<\/p>\n
    The method was used in these examples for simplicity sake — however, most single page web applications that do AJAX requests return JSON that is parsed by the front-end JavaScript and translated to HTML.  If you want the same JSON payload to be parsed and translated to HTML on the server, you’d have to port that same code into whatever server side language you are using or run the same JavaScript you run on the client on the server as well.  Running JavaScript on the server is the preferable way to go since you only have to code your presentation logic once.<\/p>\n
    Running server-side JavaScript is possible using Node, but what if you have an existing site that runs a different server-side technology?  Don’t fret! Many of them can still run JavaScript.  For example:<\/p>\n