YourFirstPlugin
From e107 Wiki
Contents |
YourFirstPlugin
a plugin by nlstart.
YourFirstPlugin v1.4 is out since June 27, 2009.
(initial version published January 25, 2007)
YourFirstPlugin is a simple plugin for starting developers to create quickly a new plugin from scratch.
Purpose of the YourFirstPlugin plugin
- GOAL: Make an easy start on developing a e107 Plugin.
- NOTE: Technically this is not a real plugin, but a skeleton that can be used as a framework to quickly start building your plugin.
- The YourFirstPlugin is also meant as an example. Actually, you could see it as an complex way of saying 'Hello World' in e107! Even if you wouldn't change the code it will still work and can be installed as any regular plugin.
Better and more examples can be found e.g. in Bugrain's e107 Helper Developer or in the e107 Core modules themselves.
- NOTE: There is also another plugin called 'YourPlugin'; this plugin is -on purpose- less sophisticated than that one.
Latest version
version v1.4
Prerequisites
E107 core v0.7.7 (or newer) installed. Preferably a proper developer editor installed (e.g. Notepad++)
Support
Download: YourFirstPlugin download
Download mirror: YourFirstPlugin download mirror on plugins@e107.org
Forum: YourFirstPlugin forum
Bugs: YourFirstPlugin bug reports
Requests: YourFirstPlugin requests
Installation
Install option 1. Flying Kick Start
For those who really can't wait; here's the quickest method to get started:
- a. Upload YourFirstPlugin files into your 'e107_plugins' folder. Although 'Upload plugin' from the Admin section might work, uploading your files by using an FTP client program is recommended.
- b. When working on Linux or Unix based server set the CHMOD settings of directories to 755 and set CHMOD of all .php files to 644.
- c. Login as an administrator into e107, go to Plugin Manager, install YourFirstPlugin and happy hacking!
Install option 2. Prepared start of Plugin development
For a more prepared start of your Plugin development, I would recommend this approach. Think before you act. Make a brief outline of what your goals are. Try to make it simple; your plugin enhancements can be created in further versions. Sketch the structure of your module on a paper first. Start listing what you come to think of and constantly weigh those remarks versus your initial goals. Try to work on one specific section until it's finished; you may end up with all kinds of unfinished parts of your plugin otherwise. Keep developing with a generic approach in mind, preferably in such a way that your plugin can be used widely by different groups of admins and/or users. Collect your logo images beforehand; pick out easy to recognise images. While building, choose for as less possible graphical details; each theme designer will take care of this. In order to give ultimate freedom to your plugin customers; use preferably templates (which is beyond the scope of the YourFirstPlugin).
- a. Unzip the files, rename the YourFirstPlugin directory in what you would like to call your Plugin.
- b. Replace the images of the \images folder with appropriate logo's for your plugin (respectively 32 by 32 pixels and 16 by 16 pixels)
- c. Edit file admin_config.php: change the language folder names
- d. Edit file admin_config_edit.php: change the language folder names
- e. admin_menu.php: change the language folder names
- f. help.php: change the language folder names
- g. admin_readme.php: change the language folder names
- h. rename YourFirstPlugin.php to your liking
- i. plugin.php: change the appropriate settings
- j. Upload YourFirstPlugin files into your 'e107_plugins' folder. Although 'Upload plugin' from the Admin section might work, uploading your files by using an FTP client program is recommended.
- k. When working on Linux or Unix based server set the CHMOD settings of all .php files to 644.
- l. Login as an administrator into e107, go to Plugin Manager, install YourFirstPlugin and you can start coding!
Updates
Not applicable; no database updates since v1.0!
Important background information
General Preferences are saved in the MySQL database in file 'e107_core' (file names my vary depending on your database preference), in field 'Siteprefs'. The fields are stored in an array (as all e107 preferences are in here) starting with 'yourfirstplugin_'.
The categories are saved in the MySQL database in file 'e107_yourfirstplugin_categories').
General advice: if you copy this plugin into your own development plugin folder, do not forget to apply the following:
- 1. change $eplug_folder = "yourfirstplugin"; in plugin.php
- 2. change $eplug_menu_name = "yourfirstplugin"; in plugin.php
- 3. search and replace for all language files yourfirstplugin/languages/ in all files
If you want a specific readme file you can just copy the readme.txt; the file that is read by admin_readme.php is defined by the setting YOURFIRSTPLUGIN_ADMIN_HELP_99 from the language file.
You can even use BBcodes in the readme.txt. It will be displayed by the admin_readme.php as default BBcode text styles in e107.
Troubleshooting
If you've changed the Plugin code and/or directory structure(s) and/or (file)names and it does not work... Please uninstall and use the 'Flying Kickstart' method. If the module is not working without modifications something else might be wrong.
If you changed or added a line to your program; try to test the program immediately. It is better to do things step by step than to insert a big new part and trying to puzzle afterwards.
When you receive a HTTP 500 error after you changed or added something; look if you forgot a closing ";" character. Otherwise, Undo, Save and test just until your code is working again.
Sometimes when programming your own module it might be handy to have some debug information. Once activated, you'll see SQL Traffic counters, SQL query analysis and PHP errors all at the bottom of your page. Here's how:
Activate debug option in Admin area > Preferences > Advanced Features > Developer Mode: On
Switch debug on with yourfirstplugin.php?[debug=all+]
Switch debug off with yourfirstplugin.php?[debug=all-]
De-activate debug option in Admin area > Preferences > Advanced Features > Developer Mode: Off
NOTE: developer mode should only switched to 'On' in a test environment!
Demonstration
The back end program to create categories is all ready for you to use. You can see an example how to present active categories to your audience in the example of yourfirstplugin.php
Changelog
Version 1.4 (June 27, 2009)
* Sub-goals for release 1.4:
- improvements
* New/Added Features:
- admin_categories_edit.php: introduced sanitizing hints at top
* Altered Features:
- placed check for admin users above require_once auth.php; thanks marj
- admin_categories_edit; code optimization to prevent double count; thanks marj
- admin_categories; order same leveled categories on id number
- plugin.php: introduced yourfirstplugin_upgrade function to perform only at upgrade moment
* Bugs Fixed:
- plugin.php: removed DEFAULT CHARSET=latin1 AUTO_INCREMENT=1; thanks marj
- plugin.php: changed ENGINE=MyISAM into TYPE=MyISAM
- general: exit; changed to exit(); thanks marj
- general: XHTML compliancy: (a giant thank you to marj)
- proper escaping of br-tag and input-tag
- lower cased POST in form-tag
- col attribute in input-tag changed to size
- name attribute in form-tag changed to id
- alt attribute in a-tag
- center is not valid in XHTML 1.1 replaced by proper class or div
- colspan=2 must be colspan="2"
* Minor Changes:
- plugin.php: changed for 1.4 version
- a few comment lines extra
* Known bugs:
- none
* Alerts:
- ATTENTION: help.php is obsolete as from e107 version 0.8
Version 1.3 (June 16, 2009)
* Sub-goals for release 1.3: - improvements * New/Added Features: - yourfirstplugin.php: demonstration on how to present categories * Altered Features: - includes/config.php: made obsolete - plugin.php: used e_PLUGIN_ABS instead of making a global variable * Minor Changes: - general: improved code readability - general: changed/added comments - languages/English.php: added YOURFIRSTPLUGIN_CORE_03 to YOURFIRSTPLUGIN_CORE_05 - plugin.php: changed to delete obsolete config.php
Version 1.2:
* Sub-goals for release 1.2: - improvements * New/Added Features: - admin_programs ensured to be loaded in admin theme by setting $eplug_admin = true before calling class2 * Altered Features: - admin_categories.php: replaced & sign in url for XHTML compliancy - admin_categories_edit.php: replaced & sign in url for XHTML compliancy * Bugs Fixed: - admin_categories.php: security improvements - admin_categories_edit.php: security improvements - yourfirstplugin.php: activated protect from direct access * Minor Changes: - readme.txt: advice for writing safe plugins * Wishlist: - * Known bugs: -
Version 1.1:
* Sub-goals for release 1.1:
- improvements
* New/Added Features:
* Altered Features:
- adjusted active checkbox to new category and change category
* Bugs Fixed:
- admin_categories_edit: adjusted storage of category interval into intval($tp->toDB($_POST['yourfirstplugin_test_integer'])).
It's good practice to do something like this when the value must be an integer and is coming from 'user input' to
prevent possible SQL injection problems.
- admin_categories.php: changed language file approach from require_once into include_lan
- admin_config.php: changed language file approach from require_once into include_lan
- admin_config.php: changed storage of variables with right database parsers
- admin_menu.php: changed language file approach from require_once into include_lan
- admin_readme.php: changed language file approach from require_once into include_lan
- help.php: changed language file approach from require_once into include_lan
- plugin.php: changed language file approach from require_once into include_lan
- yourfirstplugin.php: added correct php tag on top of file
* Minor Changes:
- comment text change in plugin.php
- made some small textual changes to the readme.txt
* Wishlist:
-
* Known bugs:
-
Version 1.0:
* Sub-goals for release 1.0: * make plugin fully e107 compliant * make plugin language independent * initial version
Future roadmap
- actually monitor the buglist
- monitor what features end users want
Technical aspects
Directory Structure
After a straight installation of YourFirstPlugin the directory structure in the e107_plugins folder should be as follows:
e107_plugins
|- YourFirstPlugin
|- images
|- languages
- The images folder contains the images 'logo_16.png' and 'logo_32.png' which are called by plugin.php
- The includes folder is obsolete since v1.3
- The languages folder contains default language file English.php with all terms used by all modules of this plugin
Plugin Modules
The plugin consists of nine different files forming one integrated module. Each .php file contains a standard set of instructions to run properly under e107. The plugin files are heavily commented in order to show starting plugin developers why certain things are done.
admin_categories.php
Task is to maintain current plugin category tables. It shows either a maintenance screen for updating existing records (in case edit_category = 1) or a list of current categories with an Add category screen (in case edit_category <> 1). A possibility exists to change the display order and an active status. When the button 'Apply Changes' is clicked the display order and active status will be saved. Per existing category there is an edit and delete icon shown. Underneath the current categories a screen is displayed to add a new category. For educational purpose, the record id number is displayed in both the overview as well as in the edit function.
admin_categories_edit.php
Task is to update current plugin category tables as called by admin_categories.php This module does the real work for the admin_categories program. It updates existing records, adds new records, deletes existing records and can change the order/active status. Functionality is built in to ask a user for confirmation before actual delete.
admin_config.php
Task is to display current plugin settings.
admin_menu.php
Task is to show the administator menu.
admin_readme.php
Task is to show the readme.txt from the menu.
e_help.php
Task is to display help text on the left side column of the administrator menu. NOTE: help.php has become obsolete since v1.4
plugin.php
General set-up of e107 plugin to tell e107 Plugin Manager where files reside, which logo to use, etc.
readme.txt
Not really a module but called by admin_readme.php to display all relevant plugin background info, installation instructions etc.
yourplugin.php
The main plugin; just calling a single line of text to display how the output can be expected and an example on how to display the categories to the front end.
