<\/span><\/h3>\n\n\n\nTo create a new plugin named Foo, just type<\/p>\n\n\n\n
.\/dliHelper.php --method=\"createPlugin\" --pluginName=\"myFoo\" --description=\"Foo is a plugin built using dliCore\" --author=\"Daniel Liljeberg\" --supportEmailAddress=\"support@foo.com\"<\/pre>\n\n\n\nYou will now have a new plugin in you oc-contents\/plugins<\/strong> folder named myFoo<\/strong>. It will contain a few folders and files. Your plugin will live under the namespace myFoo<\/strong>, or whatever name you gave your plugin.<\/p>\n\n\n\nindex.php<\/strong> is created for you and handles registering your plugin with the dliCore PluginManager. This does not have to be touched except for editing Osclass specific plugin information found in the information block at the top.<\/p>\n\n\n\nYour actual plugin is found in myFooPlugin.php<\/strong> and is an instance of a Plugin class called myFooPlugin<\/strong>.<\/p>\n\n\n\nThe plugin will also be configured to allow users to click on the question mark saying “Problems with this plugin? Ask for support.” in the plugins list in the admin area. That will take them to a form where they can request support which will be sent to the mail you provided as the –supportEmailAddress<\/strong> argument.<\/p>\n\n\n\nYou can choose to remove this by altering the “Support URI” string in the index.php<\/strong> file information block.<\/p>\n\n\n\nAlso, the plugin’s “configure” link will point to the indexAction of the AdminController. The view associated with the controller can be found under views\/Admin.<\/p>\n\n\n\n
To change which controller the configure link points to you alter the $_configAction<\/strong> variable of your plugin. If no configuration should be visible you can delete this variable and you are then also free to delete the
views\/Admin folder and the Controllers\/AdminController.php file.<\/p>\n\n\n\n<\/span>Packaging a plugin<\/span><\/h3>\n\n\n\nPackaging a plugin helps you get it ready for distribution. It’s completely optional to use but it aids you with several things.<\/p>\n\n\n\n
.\/dliHelper.php --method=\"packagePlugin\" --pluginName=\"fooBar\" --location=\"\/opt\/osclass-production\/oc-content\/plugins\"<\/pre>\n\n\n\nThe above command is used to package the plugin fooBar <\/strong>located in osclassroot\/oc-contens\/plugins\/fooBar<\/strong> and deploy it to
“\/opt\/osclass-production\/oc-content\/plugins”<\/strong><\/p>\n\n\n\nDuring packaging several things will be checked for you.<\/p>\n\n\n\n
- If your plugin has dependencies to other dliCore based plugins you will be given the option to package these to.
This helps make sure you don’t rely on functionality in a dependency that has not been released.<\/li> - If your plugin has dependencies to other dliCore based plugins their versions will be checked and if they differ
from your dependency you will be notified and given the option to update your dependency.<\/li> - If your plugin is under SVN control and local modifications exist you will be notified and given the option to
“diff”<\/strong> the modifications
“commit”<\/strong> the modifications
“ignore”<\/strong> the modifications<\/li><\/ul>\n\n\n\nOnce everything is in a clean state and all checks out your plugin is deployed to your given folder. This can be a folder where you just collect the plugins to zip and upload or another clean OsClass installation used to
test your plugin from a clean state. If your plugin was under SVN control a “checkout” will be made to the destination and the .svn folder removed. If your plugin is not under SVN control a normal copy will occur.<\/p>\n\n\n\n
After this is done you will be given the option to generate a class map file for you plugin. This speeds up auto loading and is recommended for production environments.<\/p>\n\n\n\n
Lastly, a file containing information regarding the plugin such as dependencies on other plugins etc is created to assist you when writing information about your plugin.<\/p>\n\n\n\n
Note that you should have the following php extensions enabled in order to use this tool<\/p>\n\n\n\n
- php-mysqli<\/li>
- php-simplexml<\/li>
- php-tokenizer<\/li>
- php-pdo_sqlite<\/li>
- php-zlib<\/li>
- php-json<\/li>
- php-phar<\/li>
- php-iconv<\/li>
- php-mbstring<\/li><\/ul>\n\n\n\n
The packager presents the option to minify js and css files so you can work with unminified version during development and have the the packager minify them for your release. Optionally you can also have the packager go through a lot of different file types using Leanify and try to compress them. These include documents, base64 encoded image data in html files, images etc.<\/p>\n\n\n\n
APK file (.apk)\n\n It is based on ZIP.\n Note that modifying files inside APK will break digital signature.\n To install it, you'll have to sign it again.\n If you don't want to modify any files inside APK, use -d 1 option.\n\n\nComic book archive (.cbt, .cbz)\n\n cbt is based on tar. cbz is based on ZIP.\n\n\nMicrosoft Office document 2007-2013 (.docx, .xlsx, .pptx)\n\n It is based on XML and ZIP.\n Office document 1997-2003 (.doc, .xls, .ppt) is not supported.\n\n\nData URI (.html .htm .js .css)\n\n Looks for data:image\/*;base64 and leanify base64 encoded embedded image.\n\n\nDesign Web Format (.dwf, dwfx)\n\n It is based on ZIP.\n\n\nEPUB file (.epub)\n\n It is based on ZIP.\n\n\nFictionBook (.fb2, .fb2.zip)\n\n It is based on XML.\n Leanify embedded images.\n\n\nGFT file (.gft)\n\n It's an image container format found in Tencent QQ.\n Leanify the image inside.\n\n\ngzip file (.gz, .tgz)\n\n Leanify file inside and recompress deflate stream.\n Remove all optional section: FEXTRA, FNAME, FCOMMENT, FHCRC.\n\n\nIcon file (.ico)\n\n Convert 256x256 BMP to PNG.\n Leanify PNG inside, if any.\n\n\nJava archive (.jar)\n\n It is based on ZIP.\n\n\nJPEG image (.jpeg, .jpg, .jpe, .jif, .jfif, .jfi, .thm)\n\n Remove all application markers (e.g. Exif (use --keep-exif to keep it), \n ICC profile, XMP) and comments.\n Optimize with mozjpeg.\n\n\nLua object file (.lua, .luac)\n\n Remove all debugging information:\n\n Source name\n Line defined and last line defined\n Source line position list\n Local list\n Upvalue list\n\n\nOpenDocument (.odt, .ods, .odp, .odb, .odg, .odf)\n\n It is based on XML and ZIP.\n\n\nPE file (.exe, .dll, .ocx, .scr, .cpl)\n\n Leanify embedded resource.\n Remove Relocation Table in executable file.\n Remove undocumented Rich Header.\n Overlap PE Header and DOS Header.\n\n\nPNG image (.png, .apng)\n\n Remove all ancillary chunks except for:\n\n tRNS: transparent information\n fdAT, fcTL, acTL: These chunks are used by APNG\n npTc: Android 9Patch images (*.9.png)\n Optimize with ZopfliPNG.\n\n\nRDB archive (.rdb)\n\n It is an archive format found in Tencent QQ.\n Leanify all files inside.\n\n\nFlash file (.swf)\n\n Leanify embedded images.\n Recompress it with LZMA.\n Remove Metadata Tag.\n\n\nSVG image (.svg, .svgz)\n\n It is based on XML.\n Remove metadata.\n Shrink spaces in attributes.\n Remove empty attributes.\n Remove empty text element and container element.\n\n\ntar archive (.tar)\n\n Leanify all files inside.\n\n\nXML document (.xml, .xsl, .xslt)\n\n Remove all comments, unnecessary spaces, tabs, line breaks.\n\n\nXPInstall (.xpi)\n\n It is based on ZIP.\n Note that modifying files inside xpi will break digital signature. \n To install it, you'll have to sign it again.\n\n\nXPS document (.xps, .oxps)\n\n It is based on XML and ZIP.\n\n\nZIP archive (.zip)\n\n Leanify all files inside and recompress deflate stream using Zopfli.\n Use STORE method if DEFLATE makes file larger.\n Remove extra field in Local file header.\n Remove Data descriptor structure, write those information to Local file header.\n Remove extra field and file comment in Central directory file header.\n Remove comment in End of central directory record.<\/pre>\n\n\n\nTo have the packager handle pdf conversions it’s recommended to be running Windows and having Microsoft Word installed since that creates the best conversions. On Linux Libre Office is used if found otherwise Pdf Gearbox. But I have noticed that layout and missing fonts often are an issue on Linux.<\/p>\n\n\n\n
<\/span>dliCore Quick Reference<\/span><\/h2>\n\n\n\nHere are some quick references to components and ideas used in dliCore to help you get your plugins done faster.<\/p>\n\n\n\n
<\/span>Hooks<\/span><\/h3>\n\n\n\ndliCore plugins support all hooks in Osclass and third party plugins. To have your plugin handle the “header” hook add the following function
to your myFooPlugin class.<\/p>\n\n\n\n
public function headerHook() {\n \/\/ Code to run\n}<\/pre>\n\n\n\nIn the same way you can add a hook to “user_register_form” by adding the following function.<\/p>\n\n\n\n
public function userRegisterFormHook() {\n \/\/ Code to run\n}<\/pre>\n\n\n\nNote that you do not have to do anything more than to create the function to make it work. dliCore will handle the wiring to make sure your function is called when the hook is run.<\/p>\n\n\n\n
<\/span>DocBlock Hook definitions<\/span><\/h4>\n\n\n\nAlternative ways of defining hooks using a DocBlock for a function in your Plugin also exists to provide flexibility. You can make your function hook the header hook by adding<\/p>\n\n\n\n
\/**\n * My function description\n *\n * @hook header\n *\/<\/pre>\n\n\n\nYou can set the priority of the hook<\/p>\n\n\n\n
\/**\n * My function description\n *\n * @hook header\n * @priority 5\n *\/<\/pre>\n\n\n\nYou can run your function under multiple hooks<\/p>\n\n\n\n
\/**\n * My function description\n *\n * @hook header\n * @hook footer\n * @priority 5\n *\/<\/pre>\n\n\n\nYou can make each hook have its own priority<\/p>\n\n\n\n
\/**\n * My function description\n *\n * @hook header:6\n * @hook footer:2\n *\/<\/pre>\n\n\n\nYou can also write this on a single line by using comma to separate the hooks<\/p>\n\n\n\n
\/**\n * My function description\n *\n * @hook header:6, footer:2\n *\/<\/pre>\n\n\n\nYou can set restrictions so that your hook only run under certain situations. Restrictions are the Rewrite objects location or location-section, or a dliCore based Plugins route like PluginName-Controller-Action. Since the homepage contains an empty location and section a special case name of ‘index’ is used to refer to that page.<\/p>\n\n\n\n
\/**\n * My function description\n *\n * @hook header\n * @restriction login\n * @priority 5\n *\/<\/pre>\n\n\n\nYou can add multiple restrictions either as separate tags or by using comma to separate them<\/p>\n\n\n\n
\/**\n * My function description\n *\n * @hook header\n * @restriction login, item, FooBar-User-edit\n * @priority 5\n *\/<\/pre>\n\n\n\nAs you can see you can create quite elaborate hook rules for you functions.
You can also do all of this in a single tag. To make your function run in the header hook on the login and register-register pages with a priority of 8 and under the footer hook at the item page with a priority of 6 you can write<\/p>\n\n\n\n
\/**\n * My function description\n *\n * @restrictedHook header : login, register-register : 8\n * footer : item : 6\n *\/<\/pre>\n\n\n\nEach entry should be on a new line. Note that if this is used, any @hook or @restriction tags are ignored. You can also combine things like using the fooBarHook naming convention along with setting the priority in the DocBlock.<\/p>\n\n\n\n
If your function is static your Plugin is not instantiated by the hook being called. This can be used for instance if you have some small script or style that should be included on every page load but the entire Plugin is not needed for every page.<\/p>\n\n\n\n
\/**\n * My function description\n *\n * @hook header\n *\/\npublic static function enqueuStyles() {\n osc_enqueue_style('foobar', $this->getPluginUrl() . 'assets\/css\/foobar.css');\n}<\/pre>\n\n\n\n<\/span>Registering Plugins own hooks<\/span><\/h4>\n\n\n\nOptionally, you can register hooks your own plugin will call to have them for instance automatically written to the info file during Plugin packaging of the dliDevTools Helper.<\/p>\n\n\n\n
To register a hook your Plugin will provide you add the following in your Plugins _init function<\/p>\n\n\n\n
$this->_registerHook(new Hook('AfterMessageSent', 'Called after a message has been sent', ['recipientId' => 'id of receiving user']));<\/pre>\n\n\n\nTo trigger the hook within your plugin you can then use<\/p>\n\n\n\n
$this->runHook('AfterMessageSent', 10);<\/pre>\n\n\n\nIf your Plugin is called myFoo the hook that is actually called will be<\/p>\n\n\n\n
myfoo_after_message_sent<\/pre>\n\n\n\nIn the info file the above hook would add the following entry<\/p>\n\n\n\n
myfoo_after_message_sent\n\n Arguments:\n recipientId\n id of receiving user<\/pre>\n\n\n\nThis helps users of your plugin identify which hooks you provide and how they function.<\/p>\n\n\n\n
<\/span>Controllers<\/span><\/h3>\n\n\n\nControllers are used to separate your logic from your presentation.
Controllers are placed under the Controllers folder and should end in Controller.php. Action functions in your controller will be wired to respond to specific routes and are where you write your logic for a specific action. Their name should end in Action. Let’s say you have a user profile part in your plugin myFoo. If you create the following function<\/p>\n\n\n\n
class UserController extends WebSecBaseController\n{\n public function profileAction() {\n\n }\n}<\/pre>\n\n\n\nthis will auto map the function to respond to the route “myFoo-User-profile”. By creating a link using<\/p>\n\n\n\n
<a href=\"<?php echo osc_route_url('myFoo-User-profile')?>\">User Profile<\/a><\/pre>\n\n\n\nyou would have a link that would automatically trigger the profileAction function in your UserController. You do not have to manually create new routes etc. dliCore handle all the wiring for you.<\/p>\n\n\n\n
For a given plugin you can get a registered route by calling<\/p>\n\n\n\n
$fooPlugin->getRoute('User', 'profile');<\/pre>\n\n\n\nThe returned route then presents a function getName() which would return “myFoo-USer-profile”. Besides this the route also presents additional functions such as getUrl, getAjaxUrl etc.<\/p>\n\n\n\n
There are three base controllers you can extend your Controllers from<\/p>\n\n\n\n
BaseController\n Can be run by anyone. Should be used for public pages.\n\nWebSecController\n Can only be run by logged in users. Should be used functionality that requires a user to be logged in.\n\nAdminSecBaseController\n Can only be run by logged in administrators. Should be used for handling the administrative back end.<\/pre>\n\n\n\nTo make sure your Plugin knows about your controllers you specify them in a protected member variable of your Plugin class called _controllers<\/code><\/p>\n\n\n\nclass FooBarPlugin extends Plugin\n{\n protected $_controllers = [ 'FooBar\\Controllers\\UserController',\n 'FooBar\\Controllers\\AuthenticatedUserController',\n 'FooBar\\Controllers\\AdminController'];<\/pre>\n\n\n\nThis enables the PluginManager <\/code>to know about and register routes to Controllers <\/code>without having to instantiate the Plugin<\/code>.<\/p>\n\n\n\n<\/span>Views<\/span><\/h3>\n\n\n\nViews are where you write your presentation and should basically contain your HTML code that goes with any given Action in your Controller. Your view files should be placed under views\/{ControllerName}\/{ActionName}.php<\/code> So your view file fo the profileAction of your UserController would reside in<\/p>\n\n\n\nviews\/User\/profile.php<\/pre>\n\n\n\nSupport for theme specific views exist. If you would like to have a specific view file for the FooBar theme you would place your view file in<\/p>\n\n\n\n
themes\/FooBar\/views\/User\/profile.php<\/pre>\n\n\n\nIf a special view file for the active theme is found that will be used. Otherwise the default view located under views\/User\/profile.php
will be used as a fallback.<\/p>\n\n\n\n
<\/span>Fragments<\/span><\/h3>\n\n\n\nFragments are like a special type of view one might say. I could have used this approach for the entire view model, but since Osclass has it’s own way of rendering custom files I didn’t want to break that and instead jack into that for the views. But what if you don’t have a Controller? Perhaps you don’t want to or perhaps you wan’t some piece of HTML to be rendered as part of some hook being run.<\/p>\n\n\n\n
This is where Fragments come into play. They allow you to take a file to be rendered and pass data to it.<\/p>\n\n\n\n
Let’s say you have a function to add some form element to the item form when a new item is added using the “item_form” hook.<\/p>\n\n\n\n
We add the following to our Plugin class.<\/p>\n\n\n\n
public function itemFormHook($catId) {\n if(!$this->isActiveForCategory($catId)) {\n return;\n }\n $fragment = new Fragment($this, 'itemForm.php');\n $fragment->checked = false;\n $fragment->render();\n}<\/pre>\n\n\n\nThis will now run when the item_form<\/code> hook is run and will create a Fragment. The fragment will use the file itemForm.php<\/code> The contents of itemForm.php<\/code> could look like this.<\/p>\n\n\n\n<div class=\"box myFoo_item_form\">\n <h2><?php _e(\"My important option\", \"myFoo\")?><\/h2>\n <div class=\"control-group\">\n <div class=\"controls\">\n <input id=\"myImportantOptionStatus\" type=\"checkbox\" name=\"myImportantOptionStatus\" <?php echo ($this->checked ? 'checked' : '')?>> <label for=\"myImportantOptionStatus\">THis is my important label<\/label>\n <\/div>\n <\/div>\n<\/div><\/pre>\n\n\n\nAs you can see it’s pretty much just HTML code. There is one check to see if $fragment->checked<\/code> is true or false. If it’s true then we make sure that the checkbox is checked. This allows us to use the same fragment when editing
an item. Fragments can easily be used inside view files etc.<\/p>\n\n\n\nWhen you create a Fragment you tell it what base path it should use. You can give either a path or an instance of a Plugin. The Fragment will look for files in the base path+\"\/fragments\"<\/code> folder. To create a Fragment inside your Plugin that should look for its files in the fragments folder of the plugin you just pass it a reference to $this like we did in the example
above.<\/p>\n\n\n\nSupport for theme specific fragments exist. If you would like to have a specific fragment file for the FooBar theme you would place
your fragment file in<\/p>\n\n\n\n
themes\/FooBar\/fragments\/itemForm.php<\/pre>\n\n\n\nIf a special fragment file for the active theme is found that will be used. Otherwise the default fragment located under fragments\/itemForm.php<\/code> will be used as a fallback.<\/p>\n\n\n\n<\/span>Tables<\/span><\/h3>\n\n\n\nMost plugins saves stuff to tables in the database. To create a table for your plugin you create a class that extends dliLib\\Db\\AbstractTable<\/code>. As a convention you can place the class in a sub folder named Tables. This is not a requirement, but I’m considering adding functionality to auto load tables in the same manner as Controllers and will most likely look for them in this folder if that is the case.<\/p>\n\n\n\nLet’s say our plugin stores some extended profile information about a user that we would like to store in the database. To create a table to handle this the class could look like this.<\/p>\n\n\n\n
namespace myFoo\\Tables;\n\nuse dliLib\\Db\\AbstractTable;\n\nclass ExtendedUserProfileTable extends AbstractTable {\n protected $_tableName = 't_myfoo_extended_user_profiles';\n\n protected function _init() {\n $this->_struct = \"CREATE TABLE IF NOT EXISTS \/*TABLE_NAME*\/ (\n fk_i_user_id INT UNSIGNED NOT NULL,\n 's_favourite_movie' VARCHAR(128) DEFAULT NULL\n PRIMARY KEY (fk_i_user_id),\n FOREIGN KEY (fk_i_user_id) REFERENCES \/*TABLE_PREFIX*\/t_user (pk_i_id) ON DELETE CASCADE\n ) ENGINE=InnoDB DEFAULT CHARACTER SET 'UTF8' COLLATE 'UTF8_GENERAL_CI';\";\n }\n}<\/pre>\n\n\n\nWe set the table name, excluding the OC prefix, in the $_tableName<\/code> member variable. Then we set the $_struct member variable to hold the create table struct. This should be done in the _init()<\/code> function so that the new key word \/*TABLE_NAME<\/em>*\/<\/code> is known.<\/p>\n\n\n\nTo have the plugin create and drop the table when installed and uninstalled, all you have to do is to register the Table with the Plugin.<\/p>\n\n\n\n
If we assume you save the table under the Tables folder in the Plugin directory you do the following in the Plugin’s _init()<\/code> function.<\/p>\n\n\n\nprotected function _init() {\n \/\/ Register Tables\n $this->_registerTable('myFoo\\Tables\\ExtendedUserProfileTable', 'ExtendedProfileTable');\n}<\/pre>\n\n\n\nThe first parameter points to the class of your Table, including the namespace for it. The second parameter is a friendly name that you give your Table.<\/p>\n\n\n\n
Now, when you plugin is installed the Table will be created and when your Plugin is uninstalled the Table will be removed.<\/p>\n\n\n\n
Using this functionality is optional in dliCore and you can create your own DAO if wanted.<\/p>\n\n\n\n
<\/span>Models<\/span><\/h3>\n\n\n\nTo work against your Tables you also have the option to create Database Models. They are essentially objects that you can work with and save etc without manually writing the data of it to the database.<\/p>\n\n\n\n
To create a model for our ExtendedUserProfileTable<\/code> above we would write the following class extending dliLib\\Model\\DbModel<\/code>.<\/p>\n\n\n\nnamespace myFoo\\Models\\Google;\n\nuse dliLib\\Model\\DbModel;\nclass ExtendedUserProfile extends DbModel\n{\n\/\/ Tell the model which table it is connected to\nprotected static $_dbTableClass = 'myFoo\\Tables\\ExtendedUserProfileTable';\n\n\/\/ Member variables to represent each column name. Note that prefixes such as fk_, s_, i_ etc are removed and\n\/\/ the column name converted to camelCase with a prefixing _.\nprotected $_userId = null;\nprotected $_favouriteMovie = null;\nprotected $_favouriteQuote = null;\n\n\/**\n* @return the user id\n*\/\npublic function getUserId()\n{\n return $this->_userId;\n}\n\n\/**\n* @param int $userId\n*\/\npublic function setUserId($userId)\n{\n $this->_userId = (int)$userId;\n}\n\n\/**\n* @return the favourite movie\n*\/\npublic function getFavouriteMovie()\n{\n return $this->_favouriteMovie;\n}\n\n\/**\n* @param string $favouriteMovie\n*\/\npublic function setFavouriteMovie($favouriteMovie)\n{\n $this->_favouriteMovie = $favouriteMovie;\n}\n}<\/pre>\n\n\n\nAs you can see we just supply simple getter and setter functions for our internal variables. In some instances setting a variable could involve more logic and bounds checking for instance. dliLib\\Model\\DbModel<\/code> handles the wiring for you and your model is now ready to be used.<\/p>\n\n\n\n\/\/ Get current users ExtendedUserProfile\n\/\/ find() works on the primary key which in this case was the foreign key to the user.\n$extendedUserProfile = ExtendedUserProfile::find(osc_current_logged_user_id());\n\n\/\/ Make sure this user actually had an extended profile\nif($extendedUserProfile) {\n echo \"Favourite Movie is \" . $extendedUserProfile->getFavouriteMovie() . \"<br\/>\";\n\n \/\/ Update and save data in the model\n $extendedUserProfile->setFavouriteMovie(\"Robin Hood\");\n $extendedUserProfile->save();\n}<\/pre>\n\n\n\nTo delete a model you call the static function delete and pass the instance of the model to delete. After the model has been deleted the model object will be null<\/code>.<\/p>\n\n\n\nExtendedUserProfile::delete($extendedUserProfile);\n\n\/\/ $extendedUserProfile is now null<\/pre>\n\n\n\nUsing this functionality, like almost every single mechanism, is optional in dliCore and you can create your own DAO if wanted.<\/p>\n\n\n\n
<\/span>Automatic caching of model objects<\/span><\/h4>\n\n\n\ndliCore offers a sophisticated automatic caching mechanism (if enabled by the site operator) when models are used. This system automatically keeps track of changes in an object to invalidate the cached object and also invalidates any cache of multiple models that the object was part of.<\/p>\n\n\n\n
For instance, say you select a given object with<\/p>\n\n\n\n
$foo = FooModel::find(1);<\/pre>\n\n\n\nThis fetches the FooModel<\/code> with id 1<\/code> into $foo<\/code>.<\/p>\n\n\n\nThen you might also retreive this object as part of a collection like<\/p>\n\n\n\n
$foos = FooModel::findAll();<\/pre>\n\n\n\nNow, the instance of $foo<\/code> with id = 1<\/code> within $foo<\/code> and $foos<\/code> will be the same. And if you run<\/p>\n\n\n\n$foo->setName('Bar');\n$foo->save();<\/pre>\n\n\n\nThe cache containing the individual FooModel<\/code> object as well as the collection created when finding all are both invalidated
since an object that is part of the caches has changed.<\/p>\n\n\n\n<\/span>Avoiding caching of certain properties of an object<\/span><\/h4>\n\n\n\nSometimes you might not want every property of an object to be cached. One such time can be when you fetch a collection of other model objects that might “belong” to the main object. But you would not like these objects to be cached inside the main object but instead cached as their own entities to avoid out of sync data between the main object containing the “child” objects and the actual child objects caches. Since the data cached in the main object is cached when the main object is cached and as part of that object. Changing the child object does not invalidate the main objects cache and thus the main object will contain out of sync data.<\/p>\n\n\n\n
To avoid this you could easily not store the objects in the main object at all but instead fetch them when needed. For example in FooModel <\/code>we could have a function<\/p>\n\n\n\npublic function getChildObjects() {\n return BarModel::_fetchAll(BarModel::getDbTable()->selectConditions()->where('fk_i_parent_id', $this->_id));\n}<\/pre>\n\n\n\nNow, the objects are retrieved using the model system, cached and invalidated as normal and will be “correct”. Because of the way models are handled and cached it will also not actually be fetched each time from the database but instead already fetched data will be returned if it exists.<\/p>\n\n\n\n
But sometimes you might want to keep an array of the child objects within the parent object. Thankfully dliCore provides a way to achieve this and not run into the above mentioned caching inconsistency issue.<\/p>\n\n\n\n
Let’s say you have the following functions in you FooModel<\/p>\n\n\n\n
\/\/ After load we load all the child objects abd place them into an array within the parent\nprotected function _afterLoad() {\n $this->_children = BarModel::_fetchAll(BarModel::getDbTable()->selectConditions()->where('fk_i_parent_id', $this->_id));\n}\n\n\/\/ Before we delete the parent we delete all the children of this parent\nprotected function _beforeDelete() {\n BarModel::deleteWhere(['fk_i_pranet_id' => $this->_id]);\n}\n\n\/\/ After we save the parent we set a field in the child referensing this parent and save all the children\nprotected function _afterSave() {\n \/\/ Save all the recipients\n foreach($this->_children as $child) {\n $child->setParent($this);\n }\n BarModel::saveBatch($this->_children);\n}<\/pre>\n\n\n\nNow, to avoid this array we are working with to be part of a FooModel <\/code>object that is cached we simply add the following tag to the array in the class.<\/p>\n\n\n\n \/**\n * @var FooModel[]\n * @nocache\n *\/\n protected $_children;<\/pre>\n\n\n\nThis @nocache tag will tell the CacheSystem <\/code>to ignore this specific member of the class when caching the data. So all of the data of the FooModel <\/code>will be cached, except the children we hold in $_children<\/code>. They will be cached by their own model when loaded in the BarModel::_fetchAll<\/code> call instead.<\/p>\n\n\n\nThe next time our FooModel <\/code>is fetched from cache _afterLoad<\/code> will be called, the BarModel <\/code>children fetched, which actually
means they will be fetched from cache and then they will once again exist within our FooModel <\/code>object now fetched from the
cache.<\/p>\n\n\n\n<\/span>Emails<\/span><\/h3>\n\n\n\nCreating emails to send in Osclass usually involves adding them to the pages table in the database etc so that they are available for translation. This to is simplified using dliCore. Emails <\/code>work much like Tables<\/code>. You create a class that extends dliLib\\Email\\AbstractEmail<\/code>. Let’s say we wanted to be able to notify a user if someone thought his\/her selected favorite move was boring.<\/p>\n\n\n\n<?php\nnamespace myFoo\\Emails;\n\nuse dliLib\\Email\\AbstractEmail;\nclass BoringFavouriteMovie extends AbstractEmail\n{\n \/**\n * Should return the internal Osclass description of the email.\n * This helps you identify it when editing and translating emails.\n *\n * @return string\n *\/\n protected function _getDescription()\n {\n return 'myFoo - Boring Movie';\n }\n\n \/**\n * Should return the default title\/subject of the email\n *\n * @return string\n *\/\n protected function _getDefaultTitle()\n {\n return '{WEB_TITLE} - Your selected favourite movie is boring';\n }\n\n \/**\n * Should return the default content\/body of the email\n *\n * @return string\n *\/\n protected function _getDefaultContent()\n {\n return \"<p>Hi {USER_NAME}!<\/p>\\r\\n<p> <\/p>\\r\\n<p>A fellow user has indicated that your selected favourite movie {MOVIE_TITLE} is very boring. Consider watching better movies.<\/p>\\r\\n<p>This is an automatic email, Please do not respond to this email.<\/p>\\r\\n<p> <\/p>\\r\\n<p>Thanks<\/p>\\r\\n<p>{WEB_TITLE}<\/p>\";\n }\n}<\/pre>\n\n\n\nNote that you can add any number of dynamic tags here enclosed in {}<\/code> such as {MOVIE_TITLE}<\/code>. Then we register the email with the plugin we add it to the Plugins<\/code> _init()<\/code> function.<\/p>\n\n\n\nprotected function _init() {\n \/\/ Register tables\n $this->_registerTable('myFoo\\Tables\\ExtendedUserProfileTable', 'ExtendedProfileTable');\n\n \/\/ Register emails\n $this->_registerEmail('myFoo\\Emails\\BoringFavouriteMovie', 'BoringFavouriteMovie');\n}<\/pre>\n\n\n\nThe email will now be added to the database when you install your plugin and removed once your plugin is uninstalled. It can be edited like normal in the Osclass admin under Settings\/Email templates<\/code>.<\/p>\n\n\n\nTo send a