New handling of /user files (-> *.dist files for easier updates)

I provided two separate archives until now: One for installation, one for update. The only difference between them was that the update archive did not contain the /user sub-directory to keep use-defined changes. However, this was too complicated for many users as only my templates were delivered with as two separate archives. So I changed my mind and use /user/*.dist files to provide examples and templates. These files are dummies and may be overwritten. However, the user can take and just remove the ".dist" extension to use them as starting point for own modifications.
arsava · Feb 9, 2014 · 5873deb · 5873deb
1 parent 3401234
commit 5873deb
Show file tree

Hide file tree

Showing 11 changed files with 122 additions and 90 deletions.
diff --git a/README b/README
@@ -59,17 +59,20 @@
     these hints for customizing the template:
 
     - Place your files in "mnml-blog/user"
-      The place for *all* userdefined, custom stuff is "mnml-blog/user".
-      Reason: this folder will not be touched on updates. Therefore you may
-      delete everything except "mnml-blog/user" and copy all new files into
-      "mnml-blog/" to update without loosing your changes. Do not forget to
-      empty your browser's cache afterwards.
+      The place to store *all* user-defined, custom stuff is the
+      "mnml-blog/user" directory because your files will not be touched or
+      overwritten on template updates! So you normally can copy all new files
+      into "mnml-blog/" to update the template without loosing your changes.
+      Note: There are example files helping you modifying the template.
+            The are delivered with the ".dist" extensions. Just remove the
+            ".dist" extension to use them.
 
     - Own logo
-      If you want to replace the default text showed in the headline, simply
+      If you want to replace the default logo showed in the upper left, simply
       create a "logo.[png|gif|jpg]" in "mnml-blog/user". The template recognizes
-      the file automatically and will use it instead of the default text. Do not
-      forget to empty your browser's cache afterwards.
+      the file automatically and will use it instead of the default text.
+      Note: Do not forget to empty your browser's cache if you cannot see any
+            effect.
 
     - Own favicon
       If you want to replace the default favicon, simply create a "favicon.ico"
@@ -81,16 +84,23 @@
             not supported by older MSIE versions).
 
     - Own CSS
-      To apply additional CSS rules, edit "mnml-blog/user/screen.css"
-      (influences normal layout) and/or "mnml-blog/user/print.css" (influences
-      print layout) and/or "mnml-blog/user/rtl.css" (influences "right-to-left"
-      languages like Hebrew). These files will be included automatically (as the
-      last ones for the relevant media, therefore you are able to overrule
-      existing styles). Do not forget to empty your browser's cache afterwards.
+      To apply additional CSS rules, create a
+        - "mnml-blog/user/screen.css" file to influence the normal layout. You
+          can rename the "screen.css.dist" to "screen.css" as starting point.
+        - "mnml-blog/user/print.css" file to influence the print layout. You
+          can rename the "print.css.dist" to "print.css" as starting point.
+        - "mnml-blog/user/rtl.css" file to influences "right-to-left" languages
+          like Hebrew. You can rename the "rtl.css.dist" to "rtl.css" as
+          starting point.
+      The file(s) will be included automatically (as the last ones for the
+      relevant media, therefore you are able to overrule existing styles).
+      Note: Do not forget to empty your browser's cache if you cannot see any
+            effect.
 
     - Own JavaScript
-      To load additional JavaScript, edit "mnml-blog/user/user.js". Do not
-      forget to empty your browser's cache afterwards.
+      To load additional JavaScript, create a "mnml-blog/user/user.js" file. You
+      can rename the "user.js.dist" to "user.js" as starting point (it contains
+      some examples and useful comments how to define your own JavaScript).
       ATTENTION: You have to activate the template option "mnml-blog_loaduserjs"
                  (->"Load 'mnml-blog/user/user.js'?") in the DokuWiki Config
                  Manager!
@@ -106,17 +116,19 @@
     - Web analytics software (Piwik, Google Analytics etc.)
       Tools like Piwik and Google Analytics normally provide a small code
       snippet ("tag") which you have to include at your website to make
-      everything work. If you want to use such software with this template, have
-      a look at "mnml-blog/user/tracker.php". This file exists to make it easier
-      for you. You don't have to deliberate where you have to copy and paste the
-      code, simply do it there.
+      everything work. If you want to use such software with this template,
+      create a "mnml-blog/user/tracker.php.dist". You don't have to deliberate
+      where you have to copy and  paste the code, simply do it there. You can
+      rename the "tracker.php.dist" to "tracker.php" as a good starting point
+      (it contains some examples and useful comments how to define your own
+      boxes).
 
     - Own Apple Touch Icon
       If you want to replace the default Apple Touch Icon, simply create a
       "apple-touch-icon.png" in "mnml-blog/user". The template recognizes the
-      file automatically and will use it instead of the default one. Have a
-      look at Apple's developer database (cf. "Configuring Web Applications"[2])
-      if you need more information.
+      file automatically and will use it instead of the default one. Have a look
+      at Apple's developer database (cf. "Configuring Web Applications" [2]) if
+      you need more information.
 
     [1] <http://tools.dynamicdrive.com/favicon/>
     [2] <http://j.mp/sx3NMT>

diff --git a/main.php b/main.php
@@ -177,7 +177,7 @@ function _mnmlblog_renderBoxes($arr)
 }
 
 //load userdefined js?
-if (tpl_getConf("mnmlblog_loaduserjs")){
+if (tpl_getConf("mnmlblog_loaduserjs") && file_exists(DOKU_TPL."user/user.js")){
     echo "<script type=\"text/javascript\" charset=\"utf-8\" src=\"".DOKU_TPL."user/user.js\"></script>\n";
 }
 ?>

diff --git a/user/boxes.php → user/boxes.php.dist b/user/boxes.php → user/boxes.php.dist
@@ -3,10 +3,18 @@
 /**
  * User defined box configuration of the "mnml-blog" DokuWiki template
  *
- * If you want to add/remove some boxes, have a look at the comments/examples
- * and the DocBlock of {@link _mnmlblog_renderBoxes()}, main.php
+ * Create a "/user/boxes.php" file if you want to add/remove some sidebar boxes.
+ * The template recognizes and loads the provided boxes data automatically.
+ * You may want to rename this file from "boxes.php.dist" to "boxes.php"
+ * to get a good starting point as it provides some examples. The comments of
+ * the {@link _mnml-blog_renderBoxes()} (main.php) may be useful, too.
  *
- * To change the non-box related config, use the admin webinterface of DokuWiki.
+ * Note: All example files are delivered with the ".dist" extensions to make
+ *       sure your changes do not get overwritten when updating the template.
+ *       Just remove the ".dist" extension to use them.
+ *
+ * Note: To change the non-box related config, use the admin webinterface of
+ *       DokuWiki.
  *
  *
  * LICENSE: This file is open source software (OSS) and may be copied under
@@ -32,10 +40,8 @@
 
 
 //examples: uncomment to see what is happening
-/*
 $_mnmlblog_boxes["example1"]["headline"] = "Hello World!";
 $_mnmlblog_boxes["example1"]["xhtml"] = "Blogging with DokuWiki and mnml-blog... <em>rules</em>!";
-*/
 
 
 /*

diff --git a/user/print.css b/user/print.css
diff --git a/user/print.css.dist b/user/print.css.dist
@@ -0,0 +1,9 @@
+/*
+   Place for user defined CSS rules (print media) - this file can safely be
+   preserved when updating. See README for details.
+
+   Note: All example files are delivered with the ".dist" extensions to make
+         sure your changes do not get overwritten when updating the template.
+         Just remove the ".dist" extension to use them.
+*/
+
diff --git a/user/screen.css b/user/screen.css
diff --git a/user/screen.css.dist b/user/screen.css.dist
@@ -0,0 +1,9 @@
+/*
+   Place for user defined CSS rules (screen media) - this file can safely be
+   preserved when updating. See README for details.
+
+   Note: All example files are delivered with the ".dist" extensions to make
+         sure your changes do not get overwritten when updating the template.
+         Just remove the ".dist" extension to use them.
+*/
+
diff --git a/user/tracker.php b/user/tracker.php
diff --git a/user/tracker.php.dist b/user/tracker.php.dist
@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * Place for user defined web analytics software codes/tags
+ *
+ * Tools like Piwik and Google Analytics normally provide a small HTML code
+ * snippet ("tag") which you have to include at your website to make everything
+ * work. This template tries to make this easier for you.
+ *
+ * You don't have to deliberate where you have to copy and paste the code
+ * simply create a "/user/tracker.php" file. The template recognizes and loads
+ * the provided tracker data automatically. You may want to rename this file
+ * from "tracker.php.dist" to "tracker.php" to get a good starting point. Just
+ * copy and paste the needed HTML code/tag AFTER the closing "?>"
+ *
+ * Note: All example files are delivered with the ".dist" extensions to make
+ *       sure your changes do not get overwritten when updating the template.
+ *       Just remove the ".dist" extension to use them.
+ *
+ *
+ * LICENSE: This file is open source software (OSS) and may be copied under
+ *          certain conditions. See COPYING file for details or try to contact
+ *          the author(s) of this file in doubt.
+ *
+ * @license GPLv2 (http://www.gnu.org/licenses/gpl2.html)
+ * @author ARSAVA <dokuwiki@dev.arsava.com>
+ * @link http://piwik.org/
+ * @link http://www.google.com/analytics/
+ * @link https://www.dokuwiki.org/template:mnml-blog
+ * @link https://www.dokuwiki.org/devel:configuration
+ */
+
+
+//check if we are running within the DokuWiki environment
+if (!defined("DOKU_INC")){
+    die();
+}
+
+//place the needed HTML source codes BELOW this line ?>
diff --git a/user/user.js b/user/user.js
diff --git a/user/user.js.dist b/user/user.js.dist
@@ -0,0 +1,18 @@
+/*
+   Place for user defined JavaScript - this file can safely be preserved
+   when updating. See README for details.
+
+   Note: All example files are delivered with the ".dist" extensions to make
+         sure your changes do not get overwritten when updating the template.
+         Just remove the ".dist" extension to use them.
+
+   To use own JavaScript:
+
+     1. Create a /user/user.js file. You may just want to rename this file from
+        "user.js.dist" to "user.js"
+
+     2. Do not forget to activate the template option
+        "mnml-blog_loaduserjs" (->"Load 'mnml-blog/user/user.js'?") in the
+        DokuWiki Config Manager! Otherwise, any changes to this file
+        won't have any effect!
+ */