Although Editor's API has been carefully designed to be as accessible as possible while retaining maximum flexibility, it can be a little daunting at first. To help get you get kick started with Editor development (or even to speed things up for veterans!) Editor's Generator is available on this site.
You provide Generator details about the table to edit and it will return everything needed to put the editable table onto your own server - it will even run the created table live on this server for you to try out before installing on your own. This can save countless hours of development time, which of course is what DataTables and Editor are all about.
The following document describes the basics of how to use Generator, and then applies these ideas to produce a simple "to-do" list example.
When you start using Generator you'll notice that the first two options are for what styling and software options the package that is created should use. DataTables, Editor and its other extensions can be used with a number of different styling libraries, for example Bootstrap and Foundation in order to ensure that it will seamlessly integrate with the look and feel of your site. Additionally, there are a number of extensions for DataTables and Editor that add extra features and capabilities. The download options include field type plug-ins for licensed users of Editor, with field types such as WYSIWYG and AutoComplete plug-ins available.
The styling options and extensions can be included through their individual files, but in order to make things easier Generator provides a point and click interface to select the options you want. To activate the selector interface, click the Customise button in the Generator form. An overlay box will be shown and you can select the software you want.
The software will be included from the DataTables CDN. Additional libraries can be included at any time by using the DataTables downloader builder should you decide to add extra features in future. At a minimum jQuery, DataTables and Editor should be included in your package options. Buttons and Select are also recommended.
For the to-do list example we'll leave the default options selected, although if you wish to try a different style, click the Customise button and select one of the styling frameworks - Bootstrap is possibly the most widely used styling framework on the web.
The next section in the Generator form details with the server-side aspect of the package that will be created. The first item to be selected is what server type you want Generator to create the package for - there are two options:
- PHP - Creates a package that will run on a PHP 5.3+ server
- .NET - Creates a Visual Studio project that will open in Visual Studio. The project is a C# Web API based project.
If you are using server-side environment other than these two options you can still use Editor and the Generator, but you will need to create the server-side script.
The second option is also important for the server-side: what database type you will be using. The three options are MySQL, PostgreSQL and SQL Server. The Editor libraries for PHP and .NET can operate with other databases (notably Oracle and SQLite), but Generator does not currently product SQL for these databases.
Also required is the database table name that will be used. You can use an existing table if you want to add web editing abilities to it, or create a new table using the SQL from Generator.
Finally in this section, a primary key column is also required for the table, which will be used so Editor can identify each row uniquely.
For our to-do example we are going to use MySQL and create a table called "todo". The following screenshot shows what the form will look like:
The Form / Table section of the Generator allows you to specify the fields that you wish to have in your table and editing form. There is typically an overlap between the items which appear in the table and those that appear in the Editor form, but this doesn't always have to be true - Generator has the option of showing information in the DataTable but not presenting it as editable in the form, and vice-versa.
Only the basic options for the field are shown on the page - the title, type and optionally values (depending on the field type selected). A more comprehensive list of options are available for each field by clicking on the red Edit text just below the field.
You can add and remove fields from the table using the + option at the bottom of the table and the Remove columns at the right of the table for each column. Also the fields can be reordered by clicking and dragging the arrows shown at the left of each field.
Each field must have a label, an SQL column name and select a field type. The field label is used for the DataTable column header and the Editor field label (this is trivial to alter in the generated code if you wish to use different values for each). The SQL column is simply the name of the SQL table column that you wish to use for the field and the field type defines what field type will be used for the Editor interface. Depending on what value is selected here you may be required to enter additional information such as valuation or optional values.
For our to-do list example set the form up to have three fields, with the values shown in the screenshot below:
With this all set up you can click the "Run now" button to see the resulting table in action. The test table will be hosted for one hour before being deleted. To run on your own server, please see the next section.
With Generator now configured for your use case you can simply click the Complete package button at the bottom of the table and have Generator produce everything you need to upload to your server. Click the button and a ZIP file will be downloaded. Unzip this file to see the files that Generator has produced. Note that the file names are based on your table name (in our example here there will be a file called
todo.html) - this makes it easy to produce multiple editable tables using Generator that uses the same media - you can put the generated HTML etc into this package.
At this point the instructions for the PHP and .NET platforms diverge.
Before uploading to your PHP server, there is one additional file that must be edited with the DB access information (this is not done using the Generator form for extra security). The file to edit can be found in
php/lib/config.php. Open this file and alter the
$sql_details parameters to include your database connection parameters. When edited your file might look like this:
<?php if (!defined('DATATABLES')) exit(); // Ensure being used in DataTables env. // Enable error reporting for debugging (remove for production) error_reporting(E_ALL); ini_set('display_errors', '1'); /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Database user / pass */ $sql_details = array( "type" => "Mysql", // Database type: "Mysql", "Postgres", etc "user" => "editor", // User name "pass" => "my_password", // Password "host" => "localhost", // Database server "port" => "", // Database port (can be left empty for default) "db" => "my_database", // Database name "dsn" => "" // PHP DSN extra information. Set as `charset=utf8` if you are using MySQL );
And that's it! To run your newly created Editor table all you need to do now upload the unzipped Editor package to your web-server. Once that is done simply load the generated HTML page in your web-browser and enjoy your work.
Once you have loaded the page and the table has been successfully created you may wish to remove the
CREATE TABLE statement in the PHP file to help improve performance.
Once you have unzip the file downloaded by Generator you will find a Visual Studio project file. Double click to open the project in Visual Studio. To configure the package to connect to your database click the drop down arrow in the Solution Explorer for Properties. This will make the Settings.settings option visible. Double click to edit. There are two options in the project:
DbType- This tells the libraries what database type to connect to (see the installing documentation. It will be prefilled by Generator
DbConnection- This is the connection string that defines the connection to your database. Use the connection string for your own database server (ConnectionsStrings.com can be useful if you don't know what connection string to use).
And that's it! To run your newly created Editor table all you need to do now is press F5 or click the Start debugging button in Visual Studio. The database table will be created for you automatically.
Once you have run the code you may wish to remove the
CREATE TABLE statement in the controller to help improve performance.
If you've been following the to-do example, regardless of the platform you are using, the page created will look like this:
Click the Create button to start adding data to your table!
Generator is intended as a quick start for Editor only - it is not designed to present every option that Editor has available to it. Once you are happy using Generator, you might wish to get to grips with the API, initialisation options and field options to further customise the interface as your requirements demand. Also don't forget that Editor has a number of plug-in options if you wish to extend its capabilities and display options further!