Readme files

[scottux]

I am looking through the readme.md file and I am considering just rewriting the whole thing.

I want to merge what's in the .txt version with what is in the .md version focusing on:

Codegen

OO Querying

UI Library based on jQuery

Plugin system

A quick install guide

Copyright Info and QCodo/jQuery attribution

The most important thing I think is to be direct to the point. This is the framework, this is what it does, get started doing it yourself. The 'voice' of the current version doesn't sound professional or serious. It reads like a flippant email to a doubting ruby developer.

Looking for some thoughts as I dig in.

Also, the changelog shouldn't be in there - it could be kept up-to-date with a script but it is just overhead otherwise, we could link to the latest commits. https://github.com/qcubed/framework/commits/master

[scottux]

This is what I have so far:

---

Getting started with QCubed

Releases

Newest stable release: version 2.1.1, released on Dec 1, 2012. Changelog.

Older releases are available from the downloads archive.

What is QCubed?

QCubed (pronounced 'Q' - cubed) is a PHP5 Model-View-Controller framework. The goal of the framework is to save development time around mundane, repetitive tasks - allowing you to concentrate on things that are useful AND fun.

The Code Generator

The Code Generator creates PHP classes based on your database schema. It uses the concept of ORM, object-relational mapping, to practically create your whole model layer for you.
Codegen can take advantage of foreign key relationships and field constraints to generate ready-to-use data models complete with validation routines and powerful CRUD methods, allowing you to manipulate objects instead of constantly issuing SQL queries.

More info as well as examples are available online at http://examples.qcu.be/

Object-oriented querying

Using QQueries allows for simple yet powerful loading of models, all generated ORM classes have Query methods and QQNodes. By using these methods, getting a complex subset of data is pretty straightforward - and can be used on almost any relational database.

User Interface Library

QCubed uses the concept of a QForm to keep form state between POST transactions. A QForm serves as the controller and can contain QControls which are UI components.

All QControls (including QForm itself) can use a template which is the view layer, completing the MVC structure.

QControls can take advantage of the QForm's FormState to update themselves through Ajax callbacks as easily as synchronous server POSTs. All jQuery UI core widgets are available as QControls.

Some QControls include:

• QDialog
• QTextBox
• QListBox
• QTabs
• QAccordion

A full list and examples are available online at http://examples.qcu.be/

Plugins

Through its plugin system, QCubed makes it easy to package and deliver enhancements and additions to the core codebase. The plugin project is located at https://github.com/qcubed/plugins and contains an exhaustive list of contributed plugins.

Learn more

Interested? Check out QCubed video screencasts or text-based QCubed tutorials.

The github wiki will eventually supersede these.

---

Installation

File System

Copy the contents of wwwroot/* to the ROOT level of your web site's DOCROOT
(also known as DocumentRoot, webroot, wwwroot, etc., depending on which platform
you are using).

At a later point, you may choose to move folders around in your system,
putting them in subdirectories, etc. QCubed offers the flexibility to have
these framework files in any location.

But for now, since we're getting started, we'll provide you with the instructions
on how to finish the installation assuming that you're keeping the entire
QCubed installation together as originally released.

Modify Configuration

Inside of wwwroot/configuration/includes you'll find the configuration.inc.php.sample file. You'll need
to open it to specify the actual location of your DOCROOT then save the file without the .sample extension.

IMPORTANT NOTE FOR WINDOWS USERS:
Please note that all paths should use standard "forward" slashes instead of
"backslashes". So windows paths would look like "c:/wwwroot" instead of
"c:\wwwroot".

Also, if you are putting QCubed into a SUBDIRECTORY of DOCROOT, then be sure
to set the SUBDIRECTORY constant to whatever the subdirectory is
within DOCROOT.

If you are using QCubed inside of a Virtual Directory (also known as a Directory
Alias), be sure to specify the VIRTUAL_DIRECTORY constant, too.

Next, specify a location to put your "_devtools_cli" directory (this could be either
inside or outside of docroot), and update the DEVTOOLS_CLI constant accordingly.

Finally, be sure to update the DB_CONNECTION_1 serialized array constant with the
correct database connection information for your database.

(Information on all these constants are in configuration.inc.php, itself.)

We are working on a guided installation to ease this step.

Include prepend.inc.php

Calling require() on prepend.inc.php is necessary to include the framework in your PHP file.

Note that by default, this is already setup for you in:

• /index.php
• /sample.php
• /_devtools/codegen.php
• /form_drafts/index.php
• All the /examples/
• Any code generated form_draft page

To change this or for any new PHP scripts you want to write, simply make sure any PHP
script that wants to utilize the QCubed Framework starts withrequire('includes/prepend.inc.php'); on the very first line.

Note that the "includes/configuration/prepend.inc.php" may be different -- it depends on the relative
path to the includes/prepend.inc.php file. So if you have a docroot structure like:
docroot/
docroot/pages/foo/blah.php
docroot/includes/configuration/prepend.inc.php
then in blah.php, the require line will be require('../../includes/configuration/prepend.inc.php');

Also note that if you move your .php script to another directory level, you may need to update
the relative path to prepend.inc

If you specified the includes/ in your includes_path in your php.ini file (see optional step below), then all you need to do is have require('prepend.inc.php'); at the top of each file (no need to specify a relative path).

File Permissions

Because the code generator generates files in multiple locations, you want to be sure that the
webserver process has permissions to write to the docroot.

The simplest way to do this is just to allow full access to the docroot for everyone. While this
is obviously not recommended for production environments, if you are reading this, I think it is
safe to assume you are working in a development environment. =P

On Unix/Linux, simply run chmod -R ugo+w on your docroot directory.

On Windows, you will want to right-click on the docroot folder and select "Properties",
go to the "Security" tab, Add a "Everyone" user, and specify that "Everyone" has "Full Control".
Also, on the "general" tab, make sure that "Read-Only" is unchecked. If asked, be sure to
apply changes to this folder and all subfolders.

If this doesn't work, an additional task would be to use Start - Control Panel - Administrative Tools

• Computer Management - Local Users and Groups - Users. Look for a user with a name like
  IUSR_ComputerName (where ComputerName is your computer name). Right-click on this user then
  Properties - Member of. If it just shows Guests, make sure it's selected. And then finally
  right-click on your QCubed folder, select Properties, and add the group Guests with Full Control.

(Optional) Set up the include path

This step is optional! While this adds a very slight benefit from a
convenience standpoint, doing this will also have a slight performance cost,
and also may cause complications if trying to integrate with other PHP frameworks.

Starting with Qcodo 0.2.13, you no longer need to update the PHP include_path
to run Qcodo. However, you may still want to update the include_path for any
of the following reasons:

• All PHP scripts will only need to have require('prepend.inc.php') without needing
  to specify a relative path. This makes file management slightly easier; whenever
  you want to move your files in and out of directories/subdirectories, you can do
  so without needing to worry to update the relative paths in your "require"
  statement (see STEP THREE for more information)
• With the include_path in place, you can also easily place other include files
  (like headers, footers, other libraries, etc.) in the includes/ directory, and
  then you can include them, too, without worrying about relative paths

Again, NOTE THAT THIS STEP IS OPTIONAL.

If you wish to do this, then the preferred way of doing this is simply edit your
PHP.INI file, and set the include path to:
.;c:\path\to\DOCROOT\includes\configuration (for windows)
or
.:/path/to/DOCROOT/includes/configuration (for unix)
(If you put QCubed into a subdirectory, then you want to make sure to specify it
in include_path by specifying /path/to/DOCROOT/subdir/includes/configuration)

Note: the "current directory" marker must be present (e.g. the ".;" or the ".:" at
the beginning of the path)

Now, depending on your server configuration, ISP, webhost, etc., you may
not necessarily have access to the php.ini file on the server. SOME web servers
(e.g. Apache) will allow you to make folder-level or virtualhost directives
to the php.ini file. See the PHP documentation for more information.

Alternatively, if you like the idea of being able to simply have
"require('prepend.inc.php')" with no relative path information at the top of your
pages, but if you are unable for whatever reason to set the include_path, then you
could use one of the following set_include_path lines at the top of each
web-accessed .php file/script in your web application.

IMPORTANT NOTE: Because the Code Generator can also generate some of your
web-accessed .php files, you will need to ALSO update the codegen template files
DOCROOT/includes/qcodo/_core/codegen/templates/db_orm_edit_form_draft.tpl
DOCROOT/includes/qcodo/_core/codegen/templates/db_orm_list_form_draft.tpl
to have the same "set_include_path" line at the top.

The line to choose depends on whether you're running the PHP engine as a Plug-In/Module
or a CGI (and of course, keep in mind that if you threw QCubed within a subdirectory of
DOCROOT, be sure to specify that in the line you select).

Use this if running PHP as a Apache/IIS/Etc. Plug-in or Module
set_include_path(sprintf('.%s%s/includes', PATH_SEPARATOR, $_SERVER['DOCUMENT_ROOT']));

Use this if running PHP as a CGI executable
set_include_path(sprintf('.%s%s/includes', PATH_SEPARATOR, substr($_SERVER['SCRIPT_FILENAME'], 0, strlen($_SERVER['SCRIPT_FILENAME']) - strlen($_SERVER['SCRIPT_NAME']))));

---

Credits

QCubed was born out of QCodo, and uses jQuery UI libraries.

[var-foo]

I think that is an extremely good start. I vote we roll with this, and if we come up with something better, we can always replace it.... or more likely just constantly keep working on it.

[scottux]

I'd like to get some proper copyright info in there and trim down the installation a bit, I guess it is safe to modify this in master - but I would rather put it in a branch of it's own just to be proper about it. Also, I would like to make sure everyone has some kind of buy in.

[scottux]

I found this on our TRAC wiki:

---

Unless otherwise specified, all files in the QCubed Development Framework
are under the following copyright and licensing policies:

The QCubed Development Framework is distributed by the QCubed Project
under the terms of the MIT License. More information can be found at
http://www.opensource.org/licenses/mit-license.php

Copyright (c) 2001 - 2012, Quasidea Development, LLC, QCubed Project

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

=== HTMLPurifier License ===
HTMLPurifier Library comes bundled with QCubed and is located inside the :
includes/external_libraries/htmlpurifier directory in the project root directory.

HTMLPurifier utilizes the GNU LGPL v2.1 license. You can see the license in:
includes/external_libraries/htmlpurifier/LICENSE

[spekary]

I like the goals, but I prefer a somewhat minimalist approach for this file. We should try not to duplicate anything that could be found elsewhere, or we will have to maintain two files. For example, do we really need the license and the changelog in this file, vs. pointers to those files as separate Readmes? Also, I don't think installation instructions should go here, just a pointer to them.

The audience for this is someone who is either looking for a new framework to use, and has some experience with other frameworks, or someone who is totally new to the whole framework thing to begin with. They are trying to answer the question whether to spend the time installing QCubed and put a little more time into learning about it.

I think give a quick description of QCubed, with some selling points, and don't assume the reader knows what things like CRUD means. The README is really the place to talk about the benefits.

For me, the reasons I use QCubed are:

1. It generates PHP code straight from the SQL schema. I don't need to tell PHP that I have a VARCHAR in my table. It figures that out on its own. In fact, it can figure out all the relationships between all the tables and creates a whole PHP driven Web site to get to all of the data, automatically.

2. If I start modifying the PHP code, and later add things I forgot to the database, I don't have to redo all the things I changed. The scaffolding layers mean I can pull the changes easily into my code and just keep going. Also, the template drive code generator allows me to change the automated Web page creation process as needed.

3. I don't have to worry about POSTs and GETs and all the hassle of thinking about a web page. The state driven architecture allows me for the most part to write as if I am writing a traditional desktop application. Tell a field to have a value, and the framework figures out how to get it there, keep it there, and save it into the database.

4. QCubed has been used for many years, by many developers and is a very stable platform. It shines when creating a Web site that is driven by a large schema that is not necessarily going to be viewed by millions of people. In house Web sites and medium volume, high value public Web sites are great. In particular, if the developer anticipates that the data schema will be continually changing and growing, then QCubed is superb.

5. It is open source and community driven, built on top of other open-source projects, like PHP, SQL, jquery and jquery ui.

6. A large and growing list of UI widgets. We have committed to supporting all the jQuery UI widgets (although lagging perhaps in release dates). Contributors have created additional widgets as well.

Anyways, I think the Readme should point to most everything else.

[scottux]

There is a feat-Readme branch now. I removed the .txt version and update the markdown version with what is currently here, this way we should be able to each work on it and come to a consensus about what exactly it should contain and where it should link. If anyone is interested, jump in. We will use this issue to keep track of it and you can fork/pull request if you have an idea on how it should be.

[var-foo]

What do we want to have besides a license and install file? Are those the only 2 external README type files we need?

[olegabr]

@vaibhav-kaushal, The INSTALL.md file needs your attention. Now it is missing a section on the new qcubed installer.

[vaibhav-kaushal]

Okay. I will Correct that and revert back with a pull request.

On Tue, Jan 29, 2013 at 10:34 PM, Oleg Abrosimov
notifications@github.comwrote:

@vaibhav-kaushal https://github.com/vaibhav-kaushal, The INSTALL.mdhttps://github.com/qcubed/framework/blob/rc-2.2.0/INSTALL.mdfile needs your attention. Now it is missing a section on the new qcubed
installer.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/25#issuecomment-12845269.

Regards
Vaibhav Kaushal http://about.me/vaibhav.kaushal

[vaibhav-kaushal]

Where is this file (INSTALL.md) located?

On Wed, Jan 30, 2013 at 10:30 PM, Vaibhav Kaushal <
vaibhavkaushal123@gmail.com> wrote:

Okay. I will Correct that and revert back with a pull request.

On Tue, Jan 29, 2013 at 10:34 PM, Oleg Abrosimov <notifications@github.com

wrote:

@vaibhav-kaushal https://github.com/vaibhav-kaushal, The INSTALL.mdhttps://github.com/qcubed/framework/blob/rc-2.2.0/INSTALL.mdfile needs your attention. Now it is missing a section on the new qcubed
installer.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/25#issuecomment-12845269.

Regards
Vaibhav Kaushal http://about.me/vaibhav.kaushal

Regards
Vaibhav Kaushal http://about.me/vaibhav.kaushal

[vaibhav-kaushal]

The installer has not been brought to the master branch yet? 😕

[scottux]

The installer has been merged into the rc-2.2 branch, but yeah do pull requests to the feature branch and when we release, 2.2 will be master.

[olegabr]

@scottux rc-2.2 is broken! the jqcubed has been merged to it. The workable pre-release branch is rc-2.2.0
Do not miss that!

[vaibhav-kaushal]

I believe jCubed is not ready for showtime due to the impractical loads. I haven't checked it out recently though.

[olegabr]

jqcubed is a good goal for the 2.3 version. I've already created a milestone for this: https://github.com/qcubed/framework/issues?milestone=4&page=1&state=open

[scottux]

Why is there a new branch and can we delete the other one then?

[olegabr]

The rc-2.2 branch can be deleted safely, but it can wait till actual release. Remove it if you are confident enough.

[olegabr]

I've created the rc-2.2.0 branch because rc-2.2 is mixed with jqcubed and I've failed to find a way to clean it up.

[olegabr]

I've merged @vaibhav-kaushal's changes to the INSTALL.md file. The new Installer feature now is described here (https://github.com/qcubed/framework/blob/rc-2.2.0/INSTALL.md). I treat this issue complete for the rc-2.2.0 branch.