-
Notifications
You must be signed in to change notification settings - Fork 0
The server
When creating an application with ClojureScript One, the end goal is to produce a single JavaScript file containing our program. This program may talk to a backend service which will require a server. During development, we also need a server but for very different reasons. We need a server that helps us create our application.
ClojureScript One comes with two servers. One for development and another much smaller server which can be used to serve the service for the sample application in production.
As you work with ClojureScript One, you should feel free to modify these servers in any way. They are meant to be a helpful starting point.
The development server is implemented in the file src/app/clj/one/sample/dev_server.clj which contains the one.sample.dev-server namespace.
In serving the development environment, this server provides many helpful functions:
- Three views of the application
- The design view
- A host page for the development view
- A host page for the production view
- ClojureScript One menu
- Templating support
- Proper encoding of JavaScript files
- Code reloading for both Clojure and ClojureScript
The application which is served by the development server is a tool. It is a tool which simultaneously hosts the application that you are building and helps you build it. One of the powerful things about this tool is that it can be customized using the same skills which you use to build your application.
The first thing that you see when going to the application is the index.html page which simply confirms that you have started the application and gives you an overview of the three views of the application. This page should be customized to meet your own needs.
The three views of the application are Design, Development and Production. Every view uses the same HTML template which is located in the file templates/application.html.
The Design view allows developers and designers to view static HTML resources outside of the context of the application. To support this view the server uses the templating system built into ClojureScript One and implemented in the file src/lib/clj/one/templates.clj. For more information about how templates work, see the Design and templating page.
The server supports templating for HTML files in both the templates directory and the public directory.
The Design area allows you to view template files as static HTML. The main design page is named design.html and is located in the public directory. Any other route which begins with /design is mapped to files in the templates directory.
One convenient feature provided by the development server is that all HTML files can reference resources in the public directory in the same way no matter where the HTML files are located. For example, in both the public and templates directory, HTML files can link to the CSS file at public/css/one.css using:
<link href="css/one.css" rel="stylesheet">This is a tool for creating a ClojureScript application. That application needs to live in a host HTML page. In most projects you need to have two host pages: one for the development version of the application and the other for the production version. In ClojureScript One, these pages are generated automatically.
Support for generating host pages is implemented in the file src/lib/clj/one/host_page.clj.
The development view uses the file templates/application.html as the host page, appending JavaScript files to the body of this page. This view must include script tags for the main JavaScript file for the application and the Google base.js file. It must also explicitly require each namespace that will be used by the application (Google Closure will calculate dependencies, so only top-level namespaces need to be required).
After all of the require statements, calls must be made to the JavaScript functions which will start the application. In the development view, the following calls are made:
one.sample.core.start();
one.sample.core.repl();The call to start will start the application and the call to repl will initiate the client side of the connection to the browser-connected REPL.
The production view also uses the file templates/application.html as the host page but only needs to add the advanced compiled application JavaScript and the call to start.
As mentioned above, templating is applied to all HTML files served from the public or templates directory. Any file which is referred to in a template in a _within or _include tag must be located in the templates directory.
All JavaScript files generated by the ClojureScript compiler must be UTF-8 encoded. The development server ensures that this happens by applying the js-encoding middleware.
Both Clojure and ClojureScript have a compile step. Having to actually execute a separate compile step while working on an application is not acceptable. If a source file changes, and we reload a page which uses that file, we need to see the change.
There are at least three kinds of the source files which can cause reloading: HTML, Clojure and ClojureScript.
If a ClojureScript file changes, all ClojureScript files will be reloaded. If an HTML template changes, all ClojureScript files will be reloaded. Reloading all files when one changes is a simple way to ensure that we will actually see the change. Reloading only the file that has changed will not do this in all cases. For example, if a macro or protocol is changed, dependent code will need to be reloaded.
A list of Clojure files to watch can be configured. If any file in the list changes, all of the files in the list will be reloaded. The list of files to watch is entered in the configuration map in the file src/app/clj/one/sample/config.clj. If src/app/clj/one/sample/config.clj is not itself in the list of files to watch, then you will have to restart the application when you change the list of watched files.
The file, src/app/clj/one/sample/config.clj, provides a single place to configure many aspects of how the server works. This is where the list of Clojure files to watch is managed. It is also the place where the JavaScript which is added to the development and production views are configured.
In most cases, you will want the production view of the application to be different from the development view. At the very least, the ClojureScript One menu should be removed. The configuration map allows you to add a function under the :prod-transform key which will transform the host page in some way. In the sample application, the transformation will remove the menu items from the ClojureScript One menu.
The same transformation function is applied to the host page which is generated when building the artifacts which will be deployed.