Purpose of Candy editor

Requirements

Installing

Try the demo

If the page being edited is http://server.com/foo.htm then the way to edit that page is http://server.com/candyedit.php?page=foo.htm. When we're editing the page there may be slight layout alterations but the idea is to keep the layout the same and simply highlight editable bits with candy stripes.

Configuring

1. This isn't a super-secure way of storing passwords but it should be invisible to browsers. Test by pointing your browser at it.

   The .htaccess file is supposed to block browsers. If not then consult your server's documentation.

   Edit ../info/pageInfo.txt on a page-by-page basis.
   • Instructions are contained in the file.
   • Each line refers to one page. In fact this file will often only have one active line something like index.htm pw=supersecret editlink=YES
   • IMPORTANT everything is case sensitive
   • pw= sets the password. (Required)
   • If editlink=YES is present then a grey square will be added to the page (as in the demo) which links to the edit page.
2. Edit candyedit.php All the configuration parameters are at the top of the code. These are documented in the code. Particular ones to note are:

   JQUERY_PATH	This is the jQuery javascript library. As supplied this points to a valid file. You are free to use a later version or different location. More details here.
   INTERNAL _PASSWORD	You may find that the .htaccess file doesn't protect pageInfo.txt which contains the password(s). If so you can delete pageInfo.txt and provide a password here. Note that this password applies to all the pages in this directory. In practice this shouldn't be much of a problem as most CE applications will be a small handful of pages edited by the same person.
   MAX_UPLOAD_SIZE_MB MAX_IMG_SIZE_MB	These are sanity checks on stupidly large files being uploaded. Think what is reasonable. Remember that users will try to upload 5MB photos for thumbmails etc. IMPORTANT PHP will have it's internal upload limits which may be as little as 4Mb. This is set in php.ini. See the discussion in the code for how to deal with this if it is a problem.
   JQ_DOC_READY	Ignore this if you don't use jQuery When hacking a page for editing CE needs to know if jQuery is already being used by the page. If this string is found in the original then that's the signal to just add in our code not build the whole thing from scratch. There are a number of ways to implement the document.ready event hook. You may have to tweak this search string to exactly match you version.
   CHANGE_NOTIFY_EMAIL	Where to send an alert to say there is some editing going on. Leave blank to disable. Multiple addresses can be separated by semi-colon. eg. secretary@users.org;support@foo.com This feature may be useful for checking that users haven't made a complete hash of things. Not all servers can send email or hosts block it.
   EMAIL_CHANGE_FROM	If you are using the notification of changes email feature then you'll need to provide a From: address. Be aware that your server or host may have strict rules about outgoing email so if it doesn't work you should check with them.
   VERSION_DELAY	This is set to 3 minutes in the demo system so you can see the backing up working. This is far too short for a real system. CE makes a backup each time editing is started more than a certain time after the previous starting of an edit. For example if this is set to 2 a user will be able to fiddle around making a number of attempts without second and third edits causing backups to be shifted onto and down the stack. On the other hand if they did some edits in the morning then came back for more edits in the afternoon (providing 2 hours had elapsed) there would be another backup made. If you are using the 'email on editing activity' feature this gets triggered at this point. (So remember if you get a notification you may want to wait a while before looking at the changes the user has made.)
   VERSION_DEPTH	How many previous versions are to be kept on the backup chain.
   EDIT_LINK_STYLE	If you are using the editlink=YES setting in pageInfo.txt then this is the css that will be used to style the <A> tag that does the trick. As supplied it appears as a 3-pixel grey square.

Making bits editable

General notes

• At the moment you should try to avoid formatting tags inside editable items. Experiment with <b> say in existing text to get an idea.
  You have no idea how horrible the inner workings of javascript selections are otherwise I'd have included ctrl+b and ctrl+i. On the otherhand your users should be sticking to content rather than formatting.
  <div class=ed>The cat <span class=foo>sat</span> on the mat</div> Bad <div class=ed>The cat sat on the mat</div> Good
• These tags cannot be cloned/deleted: span, h1, h2, h3, img and a
  • If you want to allow the user to add and delete these you'd wrap them in a DIV.
• These tags can be cloned, deleted or hidden:div, li, tr
  • The last remaining item cannot be deleted, instead it will be hidden. See below for more about hidden elements.
  • When making a copy of the item to insert before or after the normal method is to clear out all the contents and supply a text of "new". But when the element contains a child element that is editable it will be completely duplicated.
• Rows of tables are dealt with as a complete unit.
• It is possible for a user to delete all the text from an item. In this case it will be 'deleted' as a whole as if the DEL button had been clicked. This means that the 'last one' gets hidden not removed from the face of the earth.

Image tags

• All editable images are uploaded to the same directory as the page being edited. (This makes backing up and restoring a great deal simpler.) You only have to have editable images in the 'home' directory. In fact (see below) it may be a good idea to have your fixed images in a sub-directory.
• What could possibly go wrong?
  • How about you haven't specified heightheight or width and the user uploads a huge photo?
    Unfortunatly you can't specify both max-height and max-width in CSS or HTML without unpleasant stretching effects.
  • How about you have a fixed image called say new.jpg and the user uploads a different file that happens to have the same name for something else? To be on the safe side you can put your fixed images in a sub-directory. Only the editable bits will get backed-up to the version stack. This is fine.
• To protect against stupidity you can only replace images with the same extension as the original. (.jpeg and .jpg are considered the same.)

A tags

• The allowed file extensions are set in candyedit.php
  The use of the a tag should be restricted to reference material such as for example PDF. Editing these links is a way for this type of content to be uploaded.
• Sometimes you want a single link to be restricted to that content. For example there will only ever be one copy of the club's rules but it may get updated from time to time. This is the default case.

  Or you may want to allow the user to keep adding new documents then do something like this:

  <h3>Minutes of meetings</h3> <div class=ed>March 2011 <a href="minutesMar11.pdf">PDF</a></div> Or in a list <li class=ed>March minutes<a href="minutesMar11.pdf">PDF</a> Or in a table <tr class=ed><td>March minutes</td><td><a href="minutesMar11.pdf">PDF</a></td></tr>
  The outer div/li/tr is cloneable as required then the link can be edited.
• What could possibly go wrong?
  • The user uploads an old copy of a document. Here's how it happens: They edit document foo.doc then export to foo.pdf but don't know where it has been filed in their system and they eventially find an ancient copy and upload that.
  • They reuse a repetitive document which needs a new name each time it is edited but don't rename or 'save-as'. For example MinutesJan2011.doc should be renamed MinutesFeb2011.doc the next month otherwise they will overwrite last months with this month's instead of adding.

Tables

• Rows are treated as a complete unit. Only attach class=ed to the TR tag.
• Cells may contain editable items.
• Typically for a table you'd leave the headings uneditable.
• If the user tries to delete the last remaining row of a table it will be hidden.

Tell users

What users need to know

1. Editing URL and password.
2. A printout of the normal page with editable bits highlighted.
3. A reminder that changes and typing mistakes are published instantly!

Getting started

1. You can point them to the menu bar to get started.
2. Show them how to edit a div or span and save the page.
3. If that goes OK then go onto lists and tables
4. Leave image uploading to later.
5. Leave A-tags to last.
   Common mistake when creating a sequence of documents: Edit the same document without changing its name. When this is uploaded as next month's minutes it will overwrite the previous version. Users must give new names to new documents

Technical details

• Backup and restore
  • A backup of the whole home directory (excluding candy editor code) is made to home/safety/prev1 unless it has already been done recently. See VERSION_DELAY.
  • A chain of earlier backups is maintained with prev1 being shifted down to prev2 and so on. See VERSION_DEPTH.
  • A user can only look at the previous versions, but you can copy everything from one of the safety/prevn directories back to the 'home' if necessary.
• Logging
  • The log files are simple text files kept in home/info. There is one for each page.
  • The format is simple: timestamp, IP address of editor and message.
• Email notification from the server
  • The SUPPORT_EMAIL is a plain email address which appears in the browser. (ie. It is nothing to do with the server.)
    This is optional. Leave CHANGE_NOTIFY_EMAIL blank if you don't want it.
  • To be able to send enails automatically from the server you need four things
    1. Your server needs to support the PHP mail() function.
    2. The host needs to allow outgoing email. They will have strict rules.
    3. You need to supply a EMAIL_CHANGE_FROM email address. Something like myAccount@hosting.com
    4. You need to tell CE where to send the emails. CHANGE_NOTIFY_EMAIL is an address (or addresses split by semicolons) to send the notification to.
  • Remember this notification gets sent at the START of editing. So if you want to have a check that the user hasn't made a complete hash you want to wait a while before looking at the changes.
• Using jQuery Ignore this section if you don't use jQuery
  • CE uses jQuery so there is the possibility of version mis-match when working with your already installed jQuery library. CE is clever enough to be able to recognise if jQuery is already in use and adapt but there are some tricky bits you may want to check.
  • IMPORTANT CE looks to see if it can find the document.ready() function in the existing page. This tells it if jQuery is being used. This is a string search so we need to make sure that CE is looking for EXACTLY the right thing. JQ_DOC_READY is a string set in the Defines at the top of candyedit.php. It is simplest and most reliable to cut and paste your version MUST BE ALL ON ONE LINE WITHOUT NEW LINES.
  • The jQuery library is fairly stable, so providing you are not using a very old version you can, just to be tidy, point CE at your existing library by setting JQUERY_PATH to point at it.
• Linking page to editor It is an option to get CE to add an insignificant link on the original page. The default is a tiny grey block at the very top left of the page. When the mouse hovers over it you'll see cross-hairs. This is handy if users are not good at bookmarking and keep having to ask you how to start the editor.
  • To switch this on add editlink=YES to the line(s) relating to the page in question in ../info/pageInfo.txt
  • To tweak the appearance and location in the original tweak EDIT_LINK_STYLE in candyedit.php.

Development

Origins

Yes you can contribute to development

Bugs and improvements

WISYWIG

Internationalsation