Documentation

From Peardrop CMS
Jump to: navigation, search

This documentation applies to Peardrop version 0.2.x, if you wish to view archived docs for version 0.1.x, visit Documentation (0.1.x)

Peardrop CMS User guide

Getting Started

Since version 0.2.0, Peardrop now comes with a install.php file, which will guid you through a couple of initial steps to get everything set up. see Installing for instructions on how to get Peardrop up and running.

Once you have extracted the files to the desired location on your server, you can access the admin interface by pointing your browser to <your server where peardrop is installed>/install.php and follow any on screen instructions.


The installer will eventually ask you for an email address and a password.

The email is purely for recovery process, should you forget your password some day, Peardrop can email you a new randomly generated password from the password recovery page accessible under the login box.


General Notice: While we have made every effort to store your password in a manner that is as secure as possible, there is still no way of stopping people from guessing it! Therefore it is recommended to use a password that contains a minimum of 8 characters and a combination of upper and lower-case letters, numbers and not base the password on anything contextual to the site.

Populating your website

The Admin Home Page is the main 'control panel' for site adminstration. It allows you to Add, Edit and Delete pages, Upload and Delete images and Documents.

Pages

There are two different types of pages in peardrop:

  • Listed pages - appear as direct links automatically in the site Navigation Menu.
  • Hidden pages - are made from the same template, so are exactly the same in layout and style, but these pages are not listed in the Navigation Menu.

Using a combination of Listed and Hidden pages gives you endless flexibility to create and manage a large and comprehensive website, whilst being useful to avoid cluttering or overflowing the Navigation Menu. Hidden pages are not listed automatically in the Navigation Menu, but you can link to a Hidden page from a Listed page by inserting a hypertext link within the Listed page's content text . . .

For example if you were creating an entertainment management website you could make individual, detailed Hidden pages for each of your acts and events, then link to these from Listed pages called 'Acts' and 'Events' that act as indexes where you could include summary paragraphs and thumbnail images with links to the relevant Hidden pages.

Creating Pages

To start, click on the File menu at the top left of the Admin control and select New Page and select Easy Editor or Source editor

The difference:

  • Easy editor is for making pages using the 'WYSIWYG' (What You See Is What You Get) aimed at users who are not comfortable editing raw HTML code.
  • Source Editor is if you want to edit the raw HTML source code alone, with Syntax highlighting and is aimed at users who are comfortable editing raw HTML code.

This will load the page editor.

You now assign the page a name; this is also the name that will show up on the Navigation Menu if you choose to make it a Listed Page.

You can choose between a Listed Page and a Hidden Page by selecting from the 2 radio buttons next to the page name above the content editor panel.

If you wish you can now use the editor to create some content for the new page now but this is not neccessary at this stage. Press the submit button to create the page as specified and return to the Administration Home page, where the new page will now be detailed.

Managing Pages

For each 'Listed' or 'Hidden' page detailed on the Admin Home page, a number of options are available. - Link/View, Edit, Delete

  • Link/View - opens the page as the public will see it, in a new tab or window, displaying the web address in the browser's address bar. You can copy this address from the address bar and use it to create a link in another page when editing that page
  • Edit - opens the page to modify the content using a basic editor like a simple word processor or email program.
  • Delete - places the page in the Recycle Bin and removes it from the the Navigation Menu (if the page is 'Listed').

Using Images/Docs

When inserting an image or document you wish to use on a page you are editing, you must first upload it to the website. The Admin Home page provides a method to do this . . .

Uploading Images/Docs

The admin panel helps you to manage your files, On the top left of the screen is a box containing your images, and on the right is another box for managing all other documents you wish to publish.

To upload a file, Click on the File drop-down menu at the top left, and select Upload This will open the peardrop file uploader window which allows you to upload files to your web host using the browser.

You can select one of 2 destinations; Docs and Images. When selected, you will then be presented with additional options for uploading.


Click the Choose File button, find the appropriate file on your system using the open dialogue box, then click the Upload button to transfer it to the website. while the file is uploading, a revolving icon will appear with the word Uploading... to show that the system is working, larger files may take longer to upload, also depending on your connection speed. Some web browsers (such as chrome) also give you the progress in a percentage at the bottom left of the window, to show you how far it has progressed.


Once finished the file will be listed on the Admin Home page in the appropriate box and under the main page editor.

Managing Images/Documents

For each file detailed on the Admin Home page, a number of options are available. - View, Delete

  • View - opens the file directly in the browser, in a new tab or window, displaying the web address in the browser's address bar. You can copy this address from the address bar and use it to insert the file link in page content when editing that page.

Handy tip to remember:

Images are stored in a "images" directory on your site, and documents are saved in a folder called "docs". Since peardrop does not change the file names of what you upload, if you know what the file is called and which folder it was uploaded to, you can type the url manually in the editor using its relative directory on your site. (/images/photo.jpg or /docs/document.pdf)


  • Delete - places the file in the Recycle Bin.

In the text editor on the page you are working on use the insert image or link button and follow instructions to input the web address for the image/file. See text editor documentation for more detail.

Advice on Images

Images inserted using the editor may be of any type commonly supported by web browsers. The most popular are .jpg, .png, and .gif. Ideally images should be resized using an external image programme to the size and resolution intended for display on the website. Whilst the editor in Peardrop can set display dimensions independently of the actual image size, use of files larger than neccessary will slow page loading times and hence degrade the user experience.

The default maximum allowed upload size on most server platforms supporting PHP is 2MB (megabytes). No image should be larger than this, and should serve an ideal guide size for your files.

Recycle Bin

Under the Recycle Bin Pages or files that have been deleted are listed. You may leave them there safely, as there is no automatic purging at logout. Otherwise you may Undelete or Purge each file individually.

  • Undelete - Pages return to their former status as Listed or Hidden or files return to the folder they were deleted from.
  • Purge - Pages and Images are permanently removed from the website. Once purged they cannot be recovered.

Please note: The recycle bin only works if files are deleted through the admin panel. If you delete a file though FTP access or equivalent to that effect, they Will not appear in the recycle bin.

The Editor

Peardrop features CKEditor, a fully featured and open source WYSIWYG (What You See Is What You Get) editor that allows you to create content with ease and no prior knowledge of HTML at all! (though it helps if ever you want to make tweaks that the editor does not support)

The editor has 2 modes, a 'Designer' mode and a 'Code' mode.

The Designer mode allows you to create the content and have the editor generate the code for you in the background, While the code mode allows you to see the raw HTML source code and make your own changes to it, This is useful if you want to inject your own style references or insert other code that the editor does not have built in.

Peardrop also has a more advanced editor (CodeMirror) which only supports plain-text style editing, with the added benefit of syntax hi-lighting to make it easier to follow. This is geared towards more advanced users who are comfortable using XML based mark-up languages and CSS. It may also be preferable to the code view in CKEditor, as this does not currently have any form of mark-up/Syntax hi-lighting, and may sometimes interfere with the layout structure of the code.

Customising Peardrop Look and Feel

From the start, Peardrop CMS has been designed with customisation in mind, and as development progresses, this process will be made as easy as possible.

The files explained

As opposed to using multiple static pages, Peardrop works by a series of smaller key sub-files and the use of query strings to manage what content is to be displayed to the user through a single parent page.

index.php and admin.php


These files contain the core skeleton of the HTML code your browser requires to render the page, and within the HTML are a series of PHP functions which then perform various tasks such as fetching the page identifier from the browser's address string, and displaying the appropriate content.


We wont go in to to much detail on how this works here for the sake of keeping this doctumentation short and sweet.


for more details on how the framework functions, see the Blueprint.

The index.php file calls upon style.css which can be found under the css directory. Peardrop also allows you to manage this file though the admin control panel

To do this, navigate up to Edit Global... and select CSS Styles from the drop down.

the index.php has been written using the standard
layout, and typical Div ID's such as wrapper, content and navigation have been used to simplify how the styles are managed.

Each div element can be fully manipulated through the CSS, this also helps your site to comply with more modern W3C web standards.

Another benefit is that style classes that you insert in the CSS become available through the Easy editor for use on headings, paragraphs etc..

Included in the lite package is an index.example.php file, which contains a complete structure of the index page with all php included.


Creating your own pages

If for some reason, you want to make your own index.php page, because the default doesn't work he way you need it, the CMS can be used with custom html as well. There are a few main files in php that you will want to include in your own index file, so that you can take advantage of the CMS framework.

This is a small example so you can see how the script works in whole, as allot of the PHP is nicely stored away in included files under the 'inc' directory.

Setting up your index file

The following files are to be included in your HTML template as follows:-

  • inc/header.inc.php - This file contains all your '<head>' data such as meta data and scipts
  • inc/title.inc.php - This file contains your page title (the head of the page)
  • inc/nav.inc.php - This is the dynamic Nav Bar
  • inc/content.inc.php - This is the script that calls up the content
  • inc/footer.inc.php - This is the footer

Your HTML Template should look something like this

<!DOCTYPE html>
<html>
 <head>
  <?php include('inc/header.inc.php'); ?>
 </head>
 <body>
  <div id="container">
     <?php include('inc/title.inc.php'); ?>
       <div id="navigation">
       <?php include('inc/nav.inc.php'); ?>
     </div>
     <div id="content">
       <?php include('inc/content.inc.php'); ?>
     </div>
   <?php include('inc/footer.inc.php'); ?>
  </div>
  </body>
</html>