SnippetEdit Documentation
Contents
contents
Introduction
SnippetEdit is a tool that makes editing pre-defined sections of a website extremely easy.
The intended audience is webmasters and developers who create websites for non-technical
customers and want the customer to be able to edit parts of the site content.
SnippetEdit is really as simple as it gets. It does not have a menu system or lots of options
to confuse your content editors. SnippetEdit does not require your users to know anything
about the website file system or how to use ftp.
"Snippets" are usually small sections of content such as a product description or a news
headline. SnippetEdit lets you define both text and images as snippets so the customer can
easily edit text, modify images, and even upload their own images. Text can be entered in
either plain text or using a rich-text editor.
Snippets can be stored inline directly within the HTML (or PHP, etc.) file.
Snippets can also be stored in a database.
Visit www.SnippetEdit.com for more details
and a demo.
contents
Technical Overview
SnippetEdit is a PHP application that must run on the same webserver as the website
you want to edit. Therefore, your webserver must allow PHP processing. Need an ASP/
ASP.NET version? Let us know at info@snippetedit.com.
SnippetEdit does not require a database. You only need a database if you choose to
store your snippets in a database.
You can use SnippetEdit regardless of whether your website is static HTML or dynamically
generated using CGI, PHP, ColdFusion, JSP, etc.
SnippetEdit has a very simple password authentication system so only authorized users
can edit the site. However, you can easily override the built-in authentication to
integrate SnippetEdit into your own authentication system.
You define which parts of the website are editable (the "snippets") by adding
<SNIPPET> elements to your HTML or to the generated HTML within your dynamic scripts.
For example, if you had the following HTML:
<h1>Latest news story</h1>
To turn this into a snippet so your customer (or you) can easily edit:
<h1><SNIPPET>Latest news story</SNIPPET></h1>
It's that simple! There are more advanced snippets such as image and rich-text, but the
above illustrates the minimum you have to do to implement SnippetEdit.
SnippetEdit does have some "limitations"--it is designed that way on purpose. SnippetEdit
is not a website design and creation tool. SnippetEdit won't allow your users to
create new pages or add entirely new sections of content to existing pages. The idea is that
you, the webmaster, pre-define the parts (snippets) of the website the user can modify.
The user simply navigates their website like any normal visitor would
and the snippets "magically" appear next to editable snippets.
The tool does not have bells and whistles that would only confuse the non-technical user.
SnippetEdit does not even have a menu system or force the user to traverse the website
directory structure. It's amazingly easy to use.
SnippetEdit was created from several years of website development and hosting.
In my experience, I had lots of customers who didn't know anything about HTML or FTP and
they didn't want to. (Why should they?!) As easy as tools such as FrontPage and a host of others are to use,
most non-technical customers do not want to learn the tools. So they would call me to change
a picture in their product catalog or to update a news item on their home page. I'd end up
hacking a "quick & dirty" admin tool to let them easily change content snippets. Out of that grew
SnippetEdit--a generic, powerful, flexible, and EASY tool that solves all those problems.
contents
How to get SnippetEdit
You can download a fully working trial version of SnippetEdit from the
SnippetEdit website at www.snippetedit.com.
The SnippetEdit website also has a live demo that allows you to see SnippetEdit
in action.
When you are satisfied that SnippetEdit is all you dreamed it could be, purchase
your license at the SnippetEdit website at
www.snippetedit.com. Once your purchase
transaction is complete, you'll be given a zip file to download that is your licensed
copy that will only run on the website domain you specified when ordering.
contents
Installation & Configuration
These instructions are the same for either the trial or the licensed version of SnippetEdit.
Once you have downloaded either the trial or licensed SnippetEdit zip file
from www.snippetedit.com, unzip
it to your local hard drive. SnippetEdit will unzip into a single folder named edit.
Basic configuration
There is only one SnippetEdit file you will ever need to open or edit -- config.php.
The configuration file is a short list of parameters that you can modify to customize each
installation of SnippetEdit. This file is full of comments explaining each parameter. Perhaps
you want to open config.php now so you can refer to it while you read the rest of this document.
Here is what the config.php file looks like:
# *****************************************************************************
# SnippetEdit - a tool that simplifies website content editing.
# Copyright 2005 SnippetEdit.com
# Visit http://www.SnippetEdit.com for more information.
#
# SnippetEdit Configuration File
# Modify these parameters specific to your website.
# Lines that begin with a pound sign (#) are comments. Blank lines are ignored.
# *****************************************************************************
# The full URL to your site's home page. Do not include a trailing slash.
# Do include the 'http://' or 'https://' part. SnippetEdit assumes SnippetEdit
# is installed one subfolder below this home page. The folder this home page
# is in becomes the top-most editable folder.
FULL_HOME_PAGE_URL = http://www.mydomain.com/homepage.html
# You can define one folder as the default image folder. Enter the relative
# path from your home page listed above.
IMAGE_FOLDER = images
# The image file types you allow to be uploaded. You probably do not need
# to change this.
ALLOWED_IMAGES = gif,jpg,jpeg,png
# You can use the built-in basic password-protection or use your own.
PASSWORD_PROTECT = true
PASSWORD = admin
# Database configuration. SnippetEdit DOES NOT require a database.
# SnippetEdit does support updating snippets stored in a database.
# if you are storing snippets in a database, then you must configure
# the parameters below.
# Uncomment the line for your database type.
DB_TYPE = mysql
#DB_TYPE = postgres
#DB_TYPE = MSSQL
# Enter your database connection information.
DB_HOSTNAME = localhost
DB_DBNAME =
DB_USER =
DB_PWD =
# Define your database snippets here.
# (Defined here rather than within the element for security.)
# You indicate that a snippet is stored in the database by giving your
# <SNIPPET> tag a dbid attribute like so:
# <SNIPPET dbid="1">
# The dbid does not have to be numeric. You could name your snippets
# if this makes it easier for you to keep things straight:
#
# array with 3 values. The three values are:
# 1. table name: Name of database table snippet is stored in.
# 2. column name: Name of column snippet is stored in.
# 3. where clause: The SQL WHERE clause to find the snippet.
# For example, if your select statement to get your snippet is:
# SELECT foo
# FROM bar
# WHERE foo_name = 'bob';
# You could enter:
# 1 = bar,foo,foo_name='bob'
# Or, you could do:
# news_header = bar,foo,foo_name='bob'
#
# SnippetEdit limits SELECTs and UPDATEs to 1 row. This prevents a mal-formed
# WHERE clause from accidentally updating every row in your table!
# YOUR DBID's MUST BE UNIQUE! They can not be named the same as any of the
# other parameter names in this file.
0 = table_name,column_name,where_clause
Notice the three highlighted lines above? Those are the only three lines you will probably
need to edit! The comments in config.php should be enough to explain what the parameters are.
Simply open config.php in Notepad or your favorite text editor and modify those three lines
for your website.
Specify your home page
Some notes about the FULL_HOME_PAGE_URL parameter: SnippetEdit makes a few assumptions based
on this value. SnippetEdit assumes that your home page is in the highest level folder you want
to be allowed to edit. This does not have to be your actual home page, but that probably makes
the most sense. Any pages this home page links to and any pages those pages link to will
be parsed by SnippetEdit unless they are either external website pages (from another domain)
or live in folders above the folder your home page is in.
SnippetEdit also assumes it is installed in the same folder as the home page you specify.
For example, if you specify:
FULL_HOME_PAGE_URL = http://www.mydomain.com/homepage.html
SnippetEdit should be installed at:
http://www.mydomain.com/edit
By the way, you can rename the SnippetEdit main folder from "edit" to anything you want.
Since this is part of the URL you or your user will have to enter to edit the website, I
recommend keeping it short. Hey, how about "edit"?
Images
SnippetEdit allows the user to edit image attributes, change an image to another image from the website images directory, and even upload images from their local hard drive to use in the website. In keeping with SnippetEdit's philosophy of KISS (Keep It Simple, Stupid), SnippetEdit assumes a single images directory. The images directory can be named anything. Set the
config.php IMAGE_FOLDER parameter equal to the relative path to your website's images directory. That is relative to the home page you set in the FULL_HOME_PAGE_URL parameter.
Password protect
The default password is admin. You should of course change this!
Simply set the PASSWORD parameter to whatever password you want.
You can disable password protection by setting PASSWORD_PROTECT to false. Why would
you want to do this? If you already have a password protected admin directory, you can put
SnippetEdit in that directory.
You can also leave SnippetEdit's password protection enabled, but integrate it into your own
authentication. This would be useful in situations where you already have a password protected customer
controlpanel and you want to allow your user to login to SnippetEdit directly from your
controlpanel. For tips on how to do this, contact SnippetEdit Support at
support@snippetedit.com.
Storing snippets in a database
Yes, you can even store website content in a database and use SnippetEdit to allow your customer
to maintain those snippets! SnippetEdit never requires a database. By default, Snippets are
simply stored inline in the web page file. A common architecture for many web developers who build
dynamic websites is to create a table to store the dynamic content sections (snippets).
If you want to use the database snippet feature, setup the parameters in the
database configuration section of config.php. Currently, only MySql is supported. However,
it is rather trivial to add other database types to the system. So let us know if you need
another database supported!
support@snippetedit.com.
There are 2 things you have to do to tell SnippetEdit about database snippets. First, in your
snippet element, you'd add the dbid attribute.
<SNIPPET dbid="1">This is some content that is stored in the database.</SNIPPET>
The dbid attribute tells SnippetEdit to retrieve and store the snippet in the database. The dbid value tells SnippetEdit to look in config.php for more information. The second thing you must do
is configure this dbid in config.php. This will tell SnippetEdit which database table, which column in that table,
and what to use as a WHERE clause to SELECT and UPDATE the Snippet.
1 = content,snippet_value,snippet_name='news_item_1'
If the above is confusing, read the comments in config.php for further explanation. If you need any help, just contact us at
support@snippetedit.com.
Place the SnippetEdit files on your website
Copy or FTP the 'edit' directory and all of its contents to your website. Place the 'edit'
directory into the website directory you want to be the editable root. This does not have
to be the actual root of your website, but it does need to be in the same folder as the
file you specified as the home page in the FULL_HOME_PAGE_URL paramater in config.php.
SnippetEdit will not allow users to edit any files
that live above this editable root. For example, if the root directory of your website is at:
http://www.mywebsite.org/
You could install SnippetEdit here:
http://www.mywebsite.org/edit
If you offer sub-directory websites to people like so:
website 1: http://www.mywebsite.org/mary/
website 2: http://www.mywebsite.org/john/
And you wanted to install SnippetEdit for both mary and john, copy the edit directory to
both sites like so:
website 1: http://www.mywebsite.org/mary/edit
website 2: http://www.mywebsite.org/john/edit
Mary will not be able to edit John's pages and John will not be able to edit Mary's pages.
You can rename the 'edit' directory to anything you want. I think 'edit' is simple, short,
and applicable, but perhaps you'd prefer to rename it 'marklar'.
By the way, in the mary and john example above, you are only required to purchase a single license
since the website domain name is the same for both.
File permissions
You must write-enable the codelock.php file. If you do not know how to do this, you may need
to have your hosting company help you. (Looking for a SnippetEdit compatible hosting company with
excellent prices? SnippetEdit is proudly hosted by
ShinySolutions Webhosting.)
With a good FTP client, you can right-click a file, choose properties, and enable write privileges.
If your server is Unix or Linux and you have shell access, issue this command:
chmod 666 codelock.php.
(chmod command tips)
You must also write-enable any files that you want to edit with SnippetEdit since SnippetEdit
will need to save your changes back to your web pages.
If you choose to store your snippets in a database, SnippetEdit will not need write access to
your web page files.
contents
Starting SnippetEdit for the first time
Ok, so you've made your changes to the config.php file. You've uploaded SnippetEdit to your
website. You've ensured that codelock.php is write-enabled. You are ready to run SnippetEdit!
Point your browser to http://www.yourdomain.com/edit. (Of course replace with your real
domain name.) If SnippetEdit detects any problems with your configuration, it will tell you
about it, and hopefully tell you how to fix it.
Once you've unlocked SnippetEdit and all configuration issues are resolved, you should see
the SnippetEdit login page unless you set PASSWORD_PROTECT = false. Login with the
password you set in config.php. (The default is admin.)
If all goes well, you'll be looking at a narrow SnippetEdit bar at the top of the page and
your home page below. CONGRATULATIONS! The next step is to add snippets to your HTML.
contents
How to add SNIPPETs to your HTML
The <SNIPPET> element
The only changes you have to make to your existing website code is define the sections
you want the user to be able to edit with SnippetEdit. To do this, you simply wrap each
section (snippet) with the SNIPPET element like so:
<h2><SNIPPET>News Headline Here</SNIPPET><h2>
This will define a "raw snippet", which is the default if you do not define a type
attribute. More on that below. When you login to SnippetEdit, these snippets will be
automatically detected as you browse your website, and you will be presented with
edit icons that you can click to edit each snippet.
Notice in the example above that the word SNIPPET is uppercase! YOU MUST MAKE YOUR
SNIPPET TAGS UPPERCASE. However, all the attribute names within your SNIPPET tags must
be lowercase.
Snippet types
There are 5 types of snippets you can define.
Raw
<SNIPPET>Some content here.</SNIPPET>
For the raw snippet, you do not need to use the type attribute.
Raw snippets allow the user to enter any text they want including
script and html tags.
Text
<SNIPPET type="text">Some content here.</SNIPPET>
Text snippets will only allow the user to enter text. If any tags or code are entered,
they will be stripped out.
Rich-Text
<SNIPPET type="richtext">Some content here.</SNIPPET>
Rich-Text snippets give the user a Word-like editor making it easy and familiar for
the user to format their content. The rich-text editor only works in Internet Explorer.
In other browsers, the snippet will default to type raw.
Code
<SNIPPET type="code">Some content here.</SNIPPET>
Code snippets are useful for allowing the user to enter code examples.
All < and > symbols will be replaced with the appropriate HTML entities.
Image
<SNIPPET type="img"><img src="images/someimage.gif"></SNIPPET>
Image snippets will present the user with a simple interface that allows them to
modify the image attributes. They will be able to browse the website images
directory to select another image or upload an image from their hard drive.
Whatever attributes you put in the <img> tag are what will be presented
to the user. So if you want the user to be able to modify the image border and the
alt text, simply do this:
<SNIPPET type="img"><img src="images/someimage.gif" border="0" alt=""></SNIPPET>
You should always enclose attributes with double-quotes. Attribute names should always
be lowercase.
contents
Licensing
SnippetEdit is licensed per domain name. When you purchase your license, the copy of
SnippetEdit that you receive will only work on the domain name you specify.
contents
User Agreement and DISCLAIMER
I'm not a lawyer, so let me say this as simple as I can:
BY USING SNIPPETEDIT, EITHER THE TRIAL OR LICENSED VERSIONS OR ANY OTHER VERSION,
YOU AGREE THAT THE DEVELOPER(S) OF SNIPPETEDIT AND/OR ANYONE ELSE ASSOCIATED WITH
SNIPPETEDIT ARE NOT IN ANY WAY RESPONSIBLE FOR ANY PROBLEMS, ISSUES, AND/OR LOSS OF DATA THAT
MAY RESULT FROM THE USE OF SNIPPETEDIT. SNIPPETEDIT IS NOT WARRANTIED FOR ANY PARTICULAR
PURPOSE AND IS PROVIDED AS IS.
YOU MAY NOT REPACKAGE OR REDISTRIBUTE SNIPPETEDIT WITHOUT PERMISSION.