Publizjr 1 - Creates Web Pages ============================== A.E.Veltstra for OmegaJunior Consultancy https://omegajunior.globat.com/code/publizjr/ Release 1 ------------------------------ 0. Prerequisites; 1. Download Required Parts; 2. Unzip Parts; 3. Configure Template; 4. Configure Default Document; 5. Configure Access Privileges; 6. Test; 7. Create Content. ============================== 0. Prerequisites ------------------------------ * Access to a functioning web server that runs PHP4 or PHP5; * Programming experience with PHP4 or 5; * Knowledge about uploading and creating files and folders on the web server; * Knowledge about setting access privileges; * Knowledge about configuring Default Documents for web servers. ============================== 1. Download Required Parts ------------------------------ https://omegajunior.globat.com/code/publizjr/download/releases/1/required.parts.zip Download required parts, initial translations and the BBCode Parser. Since the templates are written in PHP and hosted from a PHP server, accessing them normally will get them to generate a web page. To avoid this and allow download instead, we have zipped them. Use your favourite tool to unpack the downloaded files. ============================== 2. Unzip Parts ------------------------------ Publizjr Generator Templates expect to live in a folder. Usually this would be the root, where the site's homepage lives. Unzip the Required Parts and place its contents into the root folder of your web server. You will find a pre-filled index page folder in the required parts download. The index page serves as the template's default page, when the visitor does not specify any other page. Its minimal contents start out equal to that of other page folders. See the chapter on creating content, below. For parsing BBCodes, Publizjr employs a simple BBCode parser adapted from "Louai Munajim" . This PHP file is part of the required parts download. To reduce the clutter inside the templates, as well as to provide a single access point to non-editorial labels and parts used by the templates, a folder named "translations" is expected to exist in the web root, containing a bunch of text files. This translations folder including default contents is provided in the required parts download. And finally, in the required parts you will also find a default CSS file for styling the generated web pages. ============================== 3. Configure Template ------------------------------ We have made two templates available in the Required Parts download. These come free of any add-ons and integrations. Choose: 1: A Basic Template. 2: A Multi-Language Aware Template. A Publizjr Generator Template reads editorial contents and translations, but also contains HTML5, which contains some non-editorial texts and references to constituent parts like translations and the BBCode parser. That is subject to configuration. By default, everything will work, and will contain (and thus output) undesirable texts. Open the chosen template in your favourite text editor and read through it. Where configuation applies, either comments will indicate to customize, or it should be apparent from the contents. You may wish to insert different HTML, depending on your site's needs. Additionally, you may wish to customize the default CSS. If you use a visit statistics service like Google Analytics or ComScore, you should instruct your statistics monitor to interpret the id query parameter and recognise different page ids as separate pages. If you use your own cache application, instruct it to recognise different page ids as separate pages. The Varnish cache application seems to do this automatically. (The OmegaJunior Consultancy is hosted on an NginX web server with Varnish.) You may wish to integrate some functionality like AddThis Social Sharing, Google Analytics, or Disqus Page Comments. ============================== 4. Configure Default Document ------------------------------ As long as you are customizing and testing, continue to use your existing home page. Once you feel happy with your results, and you decided Publizjr should generate your homepage, it is wise to configure the web server to use Publizjr as its Default Document. Before: https://omegajunior.globat.com/code/zjrjs/index.php?id=not.yet.another.library After: https://omegajunior.globat.com/code/zjrjs/?id=not.yet.another.library In .htaccess files, this can be done using the following instruction: DirectoryIndex index.php If you desire to call pages by their folder name, rather than exposing an id query parameter, you can add Rewrite Rules. Now you will have noticed that neither of the downloadble templates bear the name "index.php". It is up to you to rename one of them. You can choose not to rename them - then adjust your Default Document accordingly. However, some hosts that deny access to that setting, automatically accept "index.php" as a Default Document. So do check with your hosting provider. ============================== 5. Configure Access Privileges ------------------------------ Since each page is generated out of text files in a page folder, you can and should configure access privileges. Each content author can receive access grants inside their page folders. Since the folders live on the file system, you can use your favourite method for assigning grants. Most web hosts that allow direct FTP access and account creation, also allow grant assignments. Some allow SSH access. The host for the OmegaJunior Consultancy, Globat Web Hosting, offers a graphical user interface as a web application, to allow grants assignments. Use whichever works best for you. After having their accounts created and been granted access privileges, each content author can use their favourite FTP client to change their pages. Simply overwriting any text file should change the page contents. ============================== 6. Test ------------------------------ As long as you are in the process of (re)configuring, you may want to create a copy of the Publizjr Generator template using a different name. * Check that the template can read the bb2html.php file and the contents of the "translations" folder. Recognition is easy: the web page will stop working. If you uncomment the PHP error instructions on lines 12 and 13, you can see the error message. * Make sure the template can read the "index" page folder, for by default this will contain the home page. * See to it that the template shows the contents of the index page folder if no page id is provided in the web address. * Test whether the template shows a 404 message when you provide a page id for which no folder exists, or when the page folder does not contain a "body" file. ============================== 7. Create Content ------------------------------ The default Publizjr Generator Templates expect the following text files in any page folder: * author * body * description * intro * links * title All are optional but for the body text. In the required parts download you will find a folder named 'index' containing these text files. These text files should not have extensions. Only the body text may contain BBCodes. Use at least LF for new lines (Unix-style). CR is optional. Use UTF-8 as the charset. Other files are allowed to exist in the page folders, like images and audio or video files. Unless instucted specifically, the Publizjr Generator Templates will ignore any extra files. Then add content as you deem fit.