Web developer/designer guide

This section of the help file is intended for the web designer/developer who is going to setup the system. It is assumed that they are familiar with all the various web file formats (CSS, HTML, JSON, XML and so on). It is also assumed that they will be quite happy to hack around with the files using a text editor and upload them to a web server via FTP or their own preferred tools. If this doesn't describe you - you should probably stop now and pay someone else to do it. Or expect a very long learning curve!

Installing

Installation is fairly straightforward. You will need to get a copy of the single file 'install.php' from the nixCMS web-site. Copy this to the folder on your web-server where you wish nixCMS to be installed. Then set your browser to that location. The install script will run retrieving only those files that are required from the nixCMS repository. Installation completed. (For safety now delete the install.php script? Actually, you don't need to as it is blocked by the .htaccess file.)

.htaccess and redirecting root folder

Let's assume that you have installed nixCMS into a folder /cms/. If you used a different folder that is fine - just mentally replace /cms/ with your own folder location while reading these notes.

This means that when a visitor goes to your contact page the url will be http://example.com/cms/contact.html. You may prefer to hide the actual location and make the contents of your CMS appear in the root folder. This can be done quite easily by copying the supplied file root.htaccess into your root folder, so it ends up as /.htaccess. You also need to disable the copy of .htaccess in the /cms/ folder. (Delete the file, rename it or comment out the contents).

At the same time as doing this, you might want to make a few other changes to the .htaccess file. There is an option to force a redirect if the visitor came from a different domain name. For example, you can use this to redirect all visits from www.example.com to example.com. And also redirect from example.net to example.com. This should provide better search engine recognition.

An alternative approach would be to install nixCMS into the root folder. This should work. However installing nixCMS into a folder makes for easier maintenance. In the future, you might want to setup a new version of the site - perhaps in /cms2/. Then once you are happy you can simply switch by changing the path in the /.htaccess file.

Upgrading

For reference the same style of script is used to perform upgrades. Note that when doing an upgrade, the script attempts to do a three-way merge between the previous install/upgrade, the current files and the new files. This means that only files that have changed are downloaded and upgraded. It also means that any files you have changed are left untouched.

It is possible that a conflict can occur. This happens when the upgrade script detects a file that has changed and should be upgraded that has also been changed by you since the previous install/upgrade. In this situation, the upgrade is aborted. You then have to decide whether to force through the upgrade or make changes to the modified files.

Adding users

There is no facility to add/change users within the user interface or editor. users can only be created by someone with developer access to the system. The process is as follows:

  1. Draw up list of users names and passwords
  2. Use the makehash.php script to convert these names/ passwords into a user hash table
  3. paste the generated code into the validate.php script at the place marked.

Changing or adding globals

nixCMS includes it's globals in a simple XML file, having the following format:

 
  <globals>
  <item name="brand" type="string" description="Short label appears in top nav bar next to logo." readOnly="false">nixCMS</item>
  <item name="newPage" type="memo" description="Initial text for a newly created page. Note: comments are stripped from final output." readOnly="false">
  ...
  </item>
</globals>
  

You can change the value of these. You can also add your own. You can also set whether they are read-only or not. Values that are not read-only can be changed by logged in users. Typically you might add things like phone numbers or email address to globals. The users can then update them for themselves if they change.

Globals that you define can be inserted into the all web pages via the Template (described later). They can also be incorporated into individual web pages, simply add a tag with the following format:

<nixglobal name="brand" />
  

Global params

In addition, to the globals in the previous section, nixCMS includes a number of global params. These are set automatically by the server.

param value description
platform desktop Server sniffing of platform. Returns 'mobile' or 'desktop'.
host www.dooleyspetcare.co.uk host/domain name part of the requesting URL.
path / base path to the nixCMS. Can be used when constructing URLs in web pages.
url help/developer.html URL of current page.
q Query string used in searches.
rand x Random character between 'a' & 'z'.
editing Set to 1 when editing the page.

You can embed one of these params into your own content HTML bu using the custom tag, as below:

<nixparam name="rand" />

Changing theme/stylesheet (CSS)

When first installed nixCMS uses the current version of bootstrap Available via a CDN. However as the designer, you are free to change this. One simple option is to keep this version of bootstrap but override specific individual styles in CSS. You can do this either by supplying an additional CSS file or by embedding the styles directly into the generated HTML.

Changing the Template

The template starts with a few lines of boiler-plate XSLT, soething like this:

<?xml version="1.0" encoding="iso-8859-1" ?>
<xsl:stylesheet version="1.0" 
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:html="http://www.w3.org/1999/xhtml"
    xmlns:atom="http://www.w3.org/2005/Atom">
  <xsl:output method="html" indent="yes" encoding="utf-8" omit-xml-declaration="yes" />
  <xsl:param name="host" /> 
  <xsl:param name="path" /> 
  <xsl:param name="editing" /> 
  <xsl:param name="platform" /> 
  <xsl:param name="q" />
  <xsl:param name="rand" />
  <xsl:param name="url" />
  <xsl:variable name="globals" select="document('globals.xml')/globals" />
  <xsl:include href="cms.xsl" />
  

you should not normally need to change any of this.

This is followed by the main template. This sets up the general layout of the HTML for each page. It starts like this:

 
<xsl:template match="/">
<xsl:text disable-output-escaping="yes"><!DOCTYPE html ></xsl:text>
<html ng-app="adminApp">
<head>
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  
  <xsl:apply-templates select="/html/head/title" mode="head" />
  <xsl:apply-templates select="/html/head/meta" mode="head" />
  
  <link rel="icon" type="image/png" href="{$path}images/favicon.png" />
  <link rel="icon" type="image/gif" href="{$path}images/favicon.gif" />
  <link rel="apple-touch-icon" href="{$path}images/favicon.png" />
  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css" />
  <link href="{$path}css/default.css" rel="stylesheet" /> 
  <style type="text/css">
  /* or put CSS here */ 
  </style>
  <xsl:apply-templates select="/html/head/style" mode="head" />
</head>
<body>
  <nav class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1" aria-expanded="false"><span class="sr-only">Toggle navigation</span><span class="icon-bar"></span><span class="icon-bar"></span><span class="icon-bar"></span></button>
        <a class="navbar-brand" href="{$path}index.html"><img src="{$path}images/logo.png" style="display:inline-block;height:28px;padding-right:8px" /><span class="hidden-xs"><xsl:value-of select="$globals/item[@name='brand']" /></span></a>
      </div>

      <form class="navbar-form navbar-right" role="search" method="GET" action="{$path}search/">
        <div class="input-group">
          <!--span class="input-group-addon">Find</span -->                                                                                                          
          <input type="text" class="form-control input-sm" style="min-width:240px" 
            name="q" placeholder="enter search words or phrase" />
          <span class="input-group-btn">
            <button class="btn btn-default btn-sm" type="submit">
              <span class="glyphicon glyphicon-search" aria-hidden="true"></span>
            </button>
          </span>
        </div><!-- /input-group -->
      </form>  
    
      <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
        <ul class="nav navbar-nav navbar-right">
          <li><a href="{$path}blog/"><span class="glyphicon glyphicon-question-sign" aria-hidden="true"></span> Blog</a></li>
          <li><a href="{$path}help/index.html"><span class="glyphicon glyphicon-question-sign" aria-hidden="true"></span> Help</a></li>
          <li><a href="{$path}contact.html"><span class="glyphicon glyphicon-envelope" aria-hidden="true"></span> Contact Us</a></li>
        </ul>
      </div>
    </div>
  </nav>

  <br /><br /><br />
  <div class="visible-xs-block">
    <br /><br /><br />
  </div> 
  

....

....

  

  <xsl:if test="not($editing)">
    <div class="container">
      <xsl:choose>
        <xsl:when test="$url = 'search/index.html'">
          <xsl:call-template name="searchIndex" /> 
        </xsl:when> 
        <xsl:when test="$url = 'blog/index.html'">
          <xsl:call-template name="blogIndex" /> 
        </xsl:when> 
        <xsl:when test="starts-with($url, 'blog/')">
          <xsl:apply-templates select="/html/body/*" />
        </xsl:when> 
        <xsl:otherwise>
          <xsl:apply-templates select="/html/body/*" />
        </xsl:otherwise> 
      </xsl:choose> 
    </div>
    <br /><br /><br />
  </xsl:if> 
  <xsl:if test="$editing">
    <xsl:call-template name="editor" /> 
  </xsl:if> 
  

....

....

  
  <footer class="navbar navbar-default">
    <div class="container">
      <div class="row">
        <div class="col-sm-2 hidden-xs hidden-sm">
          <a href="{$path}copyright.html"><span class="glyphicon glyphicon-copyright-mark" aria-hidden="true"></span> 2015</a>
        </div>
        <div class="col-sm-8">
          <ul class="share-buttons">
            <li><b>Share:</b></li> 
            <li><a href="https://www.facebook.com/sharer/sharer.php?u=http://{$host}{$path}{$url}&t={/html/head/title}" title="Share on Facebook" target="_blank"><img src="{$path}images/social/facebook.svg" /></a></li>
            <li><a href="https://twitter.com/intent/tweet?source=http://{$host}{$path}{$url}&text={/html/head/title}:%20{/html/head/meta[@name = 'description']/@content}" target="_blank" title="Tweet"><img src="{$path}images/social/twitter.svg" /></a></li>
            <li><a href="https://plus.google.com/share?url=http://{$host}{$path}{$url}" target="_blank" title="Share on Google+"><img src="{$path}images/social/google.png" /></a></li>
            <li><a href="http://www.tumblr.com/share?v=3&u=http://{$host}{$path}{$url}&t={/html/head/title}&s={/html/head/meta[@name = 'description']/@content}" target="_blank" title="Post to Tumblr"><img src="{$path}images/social/tumblr.svg" /></a></li>
            <li><a href="http://pinterest.com/pin/create/button/?url=http://{$host}{$path}{$url}&description={/html/head/title}:{/html/head/meta[@name = 'description']/@content}" target="_blank" title="Pin it"><img src="{$path}images/social/pinterest.svg" /></a></li>
            <!--
            <li><a href="https://getpocket.com/save?url=http://{$host}{$path}{$url}&title={/html/head/title}" target="_blank" title="Add to Pocket"><img src="{$path}images/social/pocket.png" /></a></li>
            <li><a href="http://www.reddit.com/submit?url=http://{$host}{$path}{$url}&title={/html/head/title}" target="_blank" title="Submit to Reddit"><img src="{$path}images/social/reddit.png" /></a></li>
            -->
            <li><a href="http://www.linkedin.com/shareArticle?mini=true&url=http://{$host}{$path}{$url}&title={/html/head/title}&summary={/html/head/meta[@name = 'description']/@content}&source=" target="_blank" title="Share on LinkedIn"><img src="{$path}images/social/linkedin.svg" /></a></li>
            <!--
            <li><a href="http://wordpress.com/press-this.php?u=http://{$host}{$path}{$url}&t={/html/head/title}&s={/html/head/meta[@name = 'description']/@content}" target="_blank" title="Publish on WordPress"><img src="{$path}images/social/wordpress.svg" /></a></li>
            <li><a href="https://pinboard.in/popup_login/?url=http://{$host}{$path}{$url}&title={/html/head/title}&description={/html/head/meta[@name = 'description']/@content}" target="_blank" title="Save to Pinboard"><img src="{$path}images/social/pinboard.svg" /></a></li>
            -->
            <li><a href="mailto:?subject={/html/head/title}&body={/html/head/meta[@name = 'description']/@content}:%20http://{$host}{$path}{$url}" title="Email"><img src="{$path}images/social/email.svg" /></a></li>
          </ul>        
        
          <!-- small style="font:size:4pt">[<xsl:value-of select="$path" />|<xsl:value-of select="$platform" />|<xsl:value-of select="$rand" />|<xsl:value-of select="$url" />]</small -->
        </div>
        <div class="col-sm-2" style="text-align:right">
          <xsl:if test="not($editing)">
            <a href="{$path}{$url}?e=1">edit</a> 
          </xsl:if> 
          <xsl:if test="$editing">
            <a href="{$path}{$url}">close</a> 
          </xsl:if> 
        </div>
      </div>
    </div>
  </footer>
  

....

....

  
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
  <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script>  
  
  <xsl:if test="$editing">
    <xsl:call-template name="dialogs" /> 
    <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.14/angular.min.js"></script>
    <script src="{$path}js/wysihtml-toolbar.min.js"></script>
    <script src="{$path}js/app.js"> </script>
    <script>
      url = '<xsl:value-of select="$url" />';    /* inject url and path into Javascript */
      path = '<xsl:value-of select="$path" />';
    </script> 
  </xsl:if> 
</body>
</html>
</xsl:template>

  

....

<!-- content mode -->

<xsl:template match="@*|node()">
  <xsl:copy>
    <xsl:apply-templates select="@*|node()"/>
  </xsl:copy>
</xsl:template>

</xsl:stylesheet>
  

....