|
|
sfInstantCMSPlugin - 0.0.2The InstantCMS plugin for Symfony |
|
Some of the plugins offer one-click modules to easily add complete features to your symfony applications
 |
DescriptionThe InstantCMS plugin for Symfony. |
| Name | |
|---|---|
John L. Singleton |
moc.reltsuhdrow <<ta>> notelgnisj |
The InstantCMS plugin will enable you to quickly create a custom CMS without writing a single line of database related code. This plugin was inspired by the Zope application server and works by creating a system that can create mutable objects on the fly. You simply define the structure of a page element at runtime and manipulate it with the built in helper functions.
| Version | License | API | Released |
|---|---|---|---|
| 0.0.1beta | MIT license | 0.0.1beta | 01/05/2008 |
| Version | License | API | Released |
|---|---|---|---|
| 0.0.2beta | MIT license | 0.0.2beta | 24/08/2008 |
| 0.0.1beta | MIT license | 0.0.1beta | 01/05/2008 |
| Version | License | API | Released |
|---|---|---|---|
| 0.0.2beta | MIT license | 0.0.2beta | 24/08/2008 |
| 0.0.1beta | MIT license | 0.0.1beta | 01/05/2008 |
sfInstantCMSPlugin
(C) John L. Singleton
Co-Founder | Chief Architect
WordHustler LLC
jsingleton@wordhustler.com
http://www.wordhustler.com
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and
modification follow.
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.
c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software
interchange; or,
b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.
5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Program does not specify a
version number of this License, you may choose any version ever
published by the Free Software Foundation.
10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
php symfony plugin:install sfInstantCMSPlugin --release=0.0.2 php symfony plugin-install http://plugins.symfony-project.org/sfInstantCMSPlugin John L. Singleton
WordHustler LLC
jsingleton@wordhustler.com
The InstantCMS plugin will enable you to quickly create a custom CMS without writing a single line of database related code. This plugin was inspired by the Zope application server and works by creating a system that can create mutable objects on the fly. You simply define the structure of a page element at runtime and manipulate it with the built in helper functions.
The InstantCMS plugin introduces two primatives:
An Instant Property is a single-valued "one off" value that might appear on a web page. For example, the blurb of text on the "about us" page.
An Instant Object is a mutable type that may contain any number of fields and may contain children. For example, you might use an Instant Object to represent a catalog listing's description, image, and title.
Simply defining either of these primitives creates an editable region in the page that a user can update. You can render the following types of elements with InstantCMS:
Note that all regions rendered with an InstantObject support CRUD via the sfInstantCMS helper functions. InstantProperty regions only support updating. See below for details.
InstantCMS makes this and many more scenarios a snap. Using InstantCMS alongside an existing application you will be able to completely isolate your content layer from your application, avoiding painful integration with 3rd party CMSs.
Note that InstantCMS is SELECT-heavy. To allow objects to be mutable, I have opted for a SELECT, rather than JOIN strategy. This is smart for smaller sites with lighter traffic, since CPU time will likely be more available than RAM. InstantCMS is geared toward smaller sites that will not manage thousands of objects. InstantCMS works best for the site that has certain regions that must be updated dynamically. Bio pages, document archives, media managers, newletters, and small product catalogs are examples of applications that InstantCMS was designed for.
Note that the newest version of this plugin requires sfAssetsLibraryPlugin, not sfMediaLibrary.
Instant CMS Requires:
The wonderful sfAssetsLibraryPlugin plugin for image/file management.
A Database. InstantCMS has been tested with MySQL, but should work with any symfony-compatible datasource.
To install sfInstantCMS:
Listing 1 - Installing sfInstantCMS
symfony plugin-install http://plugins.symfony-project.com/sfInstantCMSPlugin
symfony propel-build-model
symfony cc
If you are upgrading, you should probably also do a "symfony propel-build-all," which will delete the current schema and reinitialize.
You must now enable the module. Do so by editing your application's settings.yml.
Listing 2 - Activating sfInstantCMS, in myapp/config/settings.yml
all:
.settings:
enabled_modules: [sfInstantCMS](default,)
Optionally, have a look at the plugin's security.yml file, located in plugins/sfInstantCMSPlugin/modules/sfInstantCMS/config. After development is complete you will want to secure these actions.
The sfInstantCMS "PageEdit" Helper gives you access to two types of helper functions: functions that operate on InstantProperty objects and functions that operate on InstantObjects.
The following PageEdit helper functions will enable you to create editable properties on a page. There are functions for text areas, url fields, images and more.
function editable_text_tag($name, $defaultValue, $editActive=false, $rows = 50, $cols=60)
Displays an editable region on a page named $name, with a default value of $defaultValue. If the property named $name does not exist it is created and initialized with value $defaultValue. $rows and $cols dictate how large the AJAX edit-in-place editor should be. The $editActive parameter controls the state of the control. If true, the area is enabled for editing. If false, the area renders as text.
function editable_image_tag($name, $defaultValue, $editActive=false)
Displays an editable image area on the page named $name. When editing is active, you can select an image from the sfMediaLibrary asset picker.
function editable_filedownload_tag($name, $defaultValue, $editActive=false, $linkText=null)
Displays a "file download" link on the page named $name. The optional parameter $linkText overrides the default text for the link, which is the basename() of the file. In edit mode you can set the file to download using the sfMediaLibrary chooser.
function editable_url_tag($name, $defaultValue, $editActive=false, $rows = 1, $cols=30)
Creates a clickable URL field on a page. In edit mode you can set the URL.
function editable_mailto_tag($name, $defaultValue, $editActive=false, $rows = 1, $cols=30)
Creates a clickable MAILTO tag on a page. In edit mode you can configure the email address that the link should point to.
function editable_page_tag($editBegin, $editEnd, $isEditing=false)
A convenience function that displays a small lock icon on the page. By creating two actions (or one, with different request parameters) you can create a "locked" version of the page or an unlocked version of the page. The $editBegin parameter specifies the URL that directs the user to an editable version of this page. (When the click to "unlock" the page.) The $editEnd parameter specifies a URL to send the user to when they click the lock again, thusly ending the editing process.
function get_editable_value($name, $defaultValue)
Gets a InstantProperty by name. This function is rarely used in end user code but is provided for convenience. The return type of this object is a string representing the value stored in $name.
*Listing 3 - An updatable Bio Page, in myapp/modules/mymodule/indexSuccess.php
<div align="center">
<?php editable_image_tag("AboutUS:MainImage", "", ($sf_request->getParameter('edit', 0)==0) ? false : true) ?>
</div>
<?php editable_text_tag("AboutUS:Main", "Default Text", ($sf_request->getParameter('edit', 0)==0) ? false : true) ?>
<?php echo editable_page_tag("/mymodule/index?edit=1", "/mymodule/index", ($sf_request->getParameter('edit', 0)==0) ? false : true) ?>
Note that in the above example we toggle editing on and off by passing an "edit" parameter in the request. Indeed this is the simplest and easiest to manage way to use sfInstantCMS.
The following PageEdit helper functions will enable you to create editable objects on a page. There are functions for text areas, url fields, images and more. Unlike properties, InstantObjects are for storing multiple types of the same object. For example, a product in a catalog might have the properties price, name, and description. Your catalog will likely have many of these objects. Objects can have an unlimited number of properties and may even be nested within other objects.
Many of the following functions work identically to their InstantProperty counterparts. Please read the previous section for a detailed overview of those functions.
function editable_text_object_tag($object, $name, $editActive=false, $rows=50, $cols=60)
Creates an editable region of text belonging to object $object, bound to the property $name.
function editable_url_object_tag($object, $name, $editActive=false, $rows=1, $cols=30)
Creates an editable url field that is bound to the $name property of $object.
function editable_mailto_object_tag($object, $name, $editActive=false, $rows=1, $cols=30)
Creates an editable mailto field that is bound to the $name property of $object.
function editable_object_image_tag($object, $name, $editActive=false)
Creates an editable image field that is bound to the $name property of $object.
function editable_object_filedownload_tag($object, $name, $editActive=false, $linkText=null)
Creates an editable file download link that is bound to the $name property of $object.
The following functions will assist you in managing collections of InstantObjects. The interface to the InstantObject persistent store is presented as a series of familiar CRUD-like functions. The main difference is that InstantCMS does not provide you will functions to operate directly on objects. Rather these functions typically produce controls that allow an end user to manipulate the object visually. Such support is redundant, as InstantObjects (InstantMutableObjects) are simply Propel objects that can be manipulated with the standard propel functions like save() and delete(). See get_editable and {get_editables}}}, below for more information on how to get a direct reference to an InstantObject.
function add_instant_object_tag($name, $text, $defaults, $returnURL, $withParent=null)
Creates a button on the current page that, when clicked, will add a new instance of object $name to the persistent store. The value will be initialized with the values from $defaults. The $text parameter sets the text the button should display. The $returnURL parameter indicates the URL the user should be directed to after the object is added. This is typically just the URL of the current page. The optional $withParent parameter sets the parent id of the newly created object. InstantCMS expects $defaults to be an associative array, populated with the schema and default values of your object. For example, to describe an item in a catalog, you could initialize your object as follows:
*Listing 4 - Initializing an InstantObject with the add_instant_object_tag function.
"New Product",
"description" => "My Great Product",
"image" => "",
));
* `function get_editable($id)`
Gets the InstantObject with the numeric id, $id. The return type is InstantMutableObject. The InstantMutableObject may be used with the other helper functions in this section but you can also access properties directly. You can get any named property by calling `$object->getProperty('PROPERTY_NAME')` on an instance of InstantMutableObject. The function `$object->getId()` will return the numeric id of the InstantMutableObject. **Note** that $id should exist before this function is called.
* `function get_editables($type, $defaultValues, $withParent=null)`
Gets an array of InstantObjects of type $type. The $default values parameters array works identically to the description in `add_instant_object_tag`. Calling this function will implicitly create an InstantObject of type "$type." If used with $withParent==null, this function will never return an array with less than 1 element of type $type. If used with $withParent!=null, this function will return an empty array if there are no objects that are children of $withParent.
* `function move_instant_object_up_tag($object, $returnURL) `
Displays a "move up" control that, when clicked, changes the position of $object in the output of the get_editables() function to be one position higher than its current position. **Note** that you should wrap this function in a block of code to check if editing is active before displaying.
* `function move_instant_object_down_tag($object, $returnURL) `
Displays a "move down" control that, when clicked, changes the position of $object in the output of the get_editables() function to be one position lower than its current position. **Note** that you should wrap this function in a block of code to check if editing is active before displaying.
* `function delete_instant_object_tag($object, $text, $returnURL) `
Displays a "delete" control that, when clicked, deletes $object from the persistent store. The $text parameter is obsolete. **Note** that you should wrap this function in a block of code to check if editing is active before displaying.
### Page Object Examples
The following example demonstrates a typical usage of InstantObjects. In the example below we create a simple editable product listing.
*Listing 5 - An editable, repeating page region for a product catalog in myapp/modules/publications/templates/indexSuccess.php*
getParameter('edit', 0)!=0)): ?>
<?php endif ?>
<!-- gets all of our books -->
<?php $books = get_editables("DigitalMedia",
array(
"title" => "New Title",
"author" => "New Author",
"price" => "$0.00"
)) ?>
<table width="90%" border="0" cellspacing="0" cellpadding="0">
<tr>
<td colspan="2"><h3>Digital Media</h3></td>
</tr>
<?php foreach($books as $theBook): ?>
<tr>
<td colspan="2">
<?php editable_text_object_tag($theBook, "title", ($sf_request->getParameter('edit', 0)==0) ? false : true, 1, 30); ?><br>
<?php editable_text_object_tag($theBook, "author", ($sf_request->getParameter('edit', 0)==0) ? false : true, 1, 30); ?>
</td>
</tr>
<tr>
<td align="right" colspan="2">
Price: <?php editable_text_object_tag($theBook, "price", ($sf_request->getParameter('edit', 0)==0) ? false : true, 1, 30); ?>
</td>
</tr>
<tr><td colspan="2"> </td></tr>
<!-- if editing is active, display our CRUD controls -->
<?php if( ($sf_request->getParameter('edit', 0)!=0)): ?>
<tr>
<td colspan="2" align="left">
<?php delete_instant_object_tag($theBook, "Delete", "/publications/index?edit=1"); ?>
<?php move_instant_object_up_tag($theBook, "/publications/index?edit=1")?>
<?php move_instant_object_down_tag($theBook, "/publications/index?edit=1")?>
</td>
</tr>
<!-- a visual indicator so the user knows where records start and stop -->
<tr>
<td colspan="2" ><hr width="100%"/></td>
</tr>
<?php endif; ?>
<?php endforeach; ?>
</table>
Listing 6 Displaying Nested properties. -- TODO
As a standard Symfony module, sfInstantCMS can easily be secured using standard symfony methods. One approach would be to create two actions for each editable page. For example, for an about page you might create the following actions: about and editAbout. Then in your security.yml file you can restrict access to these actions as your business logic dictates.
You should also have a look at sfInstantCMS's own security.yml file. By default sfInstantCMS performs no security checks. This is left as an exercise for the reader. :)
For the full copyright and license information, please view the LICENSE file that was distributed with this source code.
5/01/08 -- Initial Release.
