adding the missing features in Joomla!
Fotis Evangelou
K2 Project Lead
21 October 2011
in Tutorials
In this short tutorial, we're going to explain how K2 templating works.
Note: If you're just starting with Joomla!, I highly recommend you first have a look here: http://docs.joomla.org/Beginners
As you may know already, Joomla! 1.5+ is an MVC content management system and provides you with the means to "override" default HTML layouts within your template's folder. All you have to do is usually copy the "tmpl" folder of a component's view within your Joomla! template's /html/com_componentName/ folder. In K2 version 1.0.x we did the same thing, but it was limiting for the potential of this component, if you wanted to use K2 for different things, like blog, magazine, catalog etc.
So we had to implement a different way to utilize sub-templates, within the templating capabilities of Joomla!. What we did is even simpler compared to current Joomla! templating: all you have to do to override K2's views is COPY THE CONTENTS of the folder /components/com_k2/templates/ and PASTE it into /templates/YOURJOOMLATEMPLATE/html/com_k2/. Judging from the first folder path, it's clear that we do not use Joomla!'s logic, but it's for the better.
After you have copied this folder over to your /templates/YOURJOOMLATEMPLATE/html/com_k2/ folder, you will notice that some "views" are right at the root of that folder (e.g. generic.php or user.php) and some other views are located within a subfolder, called "default". These are located in: /templates/YOURJOOMLATEMPLATE/html/com_k2/
The "views" that are located at the root of that folder are the ones that cannot be themed into variations and this is normal, as you won't need to have different layouts for the registration page or the user page or the page that shows search results from K2 content! If you want to override K2, just go ahead and edit these "views".
Now, the "views" that are located within the folder "default" are the ones that can be themed into variations and these "variations" can be selected from K2's backend, when editing categories or "menu items" to K2 categories. Let's try this example: We're still inside /templates/YOURJOOMLATEMPLATE/html/com_k2/. If you copy (duplicate) the folder "default" and change its name to "blog" (for example), this new folder containing views to the item and categories will then be picked up by K2, without having to exist inside /components/com_k2/. How cool is that, right? Repeat the process and you can create groups of "views" (sub-templates in K2 lingo) which can then be used for different parts of your K2 based site. To edit each sub-template just edit the files contained in each folder. If you edit the item.php view in the folder "blog", for example, then only the categories or menu items using this sub-template will pick up your changes.
So if your website had 3 major areas, say a news section, a knowledge base and a catalog of products, you create 3 copies of the "default" folder, rename them to something relative to these areas (e.g. news, kb, catalog) and then you create your create each parent category, assigning the respective sub-template each time. Then you edit each sub-template and get the desired layout for your site.
As you can imagine this opens a whole new way of skinning K2 based Joomla! websites as you only have one component yet different views per functionality. So your K2 blog is different to your K2 catalog or your K2 news/magazine section and so on.
Template developers have already grasped the potential of K2 sub-templating and many new and exciting templates are on the way from major template vendors.
More
Note: If you're just starting with Joomla!, I highly recommend you first have a look here: http://docs.joomla.org/Beginners
As you may know already, Joomla! 1.5+ is an MVC content management system and provides you with the means to "override" default HTML layouts within your template's folder. All you have to do is usually copy the "tmpl" folder of a component's view within your Joomla! template's /html/com_componentName/ folder. In K2 version 1.0.x we did the same thing, but it was limiting for the potential of this component, if you wanted to use K2 for different things, like blog, magazine, catalog etc.
So we had to implement a different way to utilize sub-templates, within the templating capabilities of Joomla!. What we did is even simpler compared to current Joomla! templating: all you have to do to override K2's views is COPY THE CONTENTS of the folder /components/com_k2/templates/ and PASTE it into /templates/YOURJOOMLATEMPLATE/html/com_k2/. Judging from the first folder path, it's clear that we do not use Joomla!'s logic, but it's for the better.
After you have copied this folder over to your /templates/YOURJOOMLATEMPLATE/html/com_k2/ folder, you will notice that some "views" are right at the root of that folder (e.g. generic.php or user.php) and some other views are located within a subfolder, called "default". These are located in: /templates/YOURJOOMLATEMPLATE/html/com_k2/
The "views" that are located at the root of that folder are the ones that cannot be themed into variations and this is normal, as you won't need to have different layouts for the registration page or the user page or the page that shows search results from K2 content! If you want to override K2, just go ahead and edit these "views".
Now, the "views" that are located within the folder "default" are the ones that can be themed into variations and these "variations" can be selected from K2's backend, when editing categories or "menu items" to K2 categories. Let's try this example: We're still inside /templates/YOURJOOMLATEMPLATE/html/com_k2/. If you copy (duplicate) the folder "default" and change its name to "blog" (for example), this new folder containing views to the item and categories will then be picked up by K2, without having to exist inside /components/com_k2/. How cool is that, right? Repeat the process and you can create groups of "views" (sub-templates in K2 lingo) which can then be used for different parts of your K2 based site. To edit each sub-template just edit the files contained in each folder. If you edit the item.php view in the folder "blog", for example, then only the categories or menu items using this sub-template will pick up your changes.
So if your website had 3 major areas, say a news section, a knowledge base and a catalog of products, you create 3 copies of the "default" folder, rename them to something relative to these areas (e.g. news, kb, catalog) and then you create your create each parent category, assigning the respective sub-template each time. Then you edit each sub-template and get the desired layout for your site.
As you can imagine this opens a whole new way of skinning K2 based Joomla! websites as you only have one component yet different views per functionality. So your K2 blog is different to your K2 catalog or your K2 news/magazine section and so on.
Template developers have already grasped the potential of K2 sub-templating and many new and exciting templates are on the way from major template vendors.
FILE & FOLDER PATH EXAMPLES IN K2 MVC TEMPLATING
| Within the component | Within our template |
| /components/com_k2/templates/ | /templates/YOURTEMPLATE/html/com_k2/ |
| /components/com_k2/templates/user.php | /templates/YOURTEMPLATE/html/com_k2/user.php |
| /components/com_k2/templates/default/item.php | /templates/YOURTEMPLATE/html/com_k2/default/item.php |
| /components/com_k2/templates/newsubtemplate/category.php | /templates/YOURTEMPLATE/html/com_k2/newsubtemplate/category.php |
| (does not have to exist) | /templates/YOURTEMPLATE/html/com_k2/differentSubTemplateNotExistingInComponent/category.php |
Tags:
21 October 2011
When we say "K2 images", we mean the image that your upload via the image tab in the item edit form.
There are various reasons why we convert "K2 images" to JPG:
From speed (low file size), to performance (no disk IO checks, no database records for filenames, less memory for GD to resize the pic), to native restrictions in the PHP conversion library (GD) which really is still crap at resizing PNG-24 images...
If you want to use "transparent" PNG images (PNG-24), don't use the "image" feature in K2, but instead upload your image via the WYSIWYG editor (TinyMCE, JCE, JCK Editor etc.). More
There are various reasons why we convert "K2 images" to JPG:
From speed (low file size), to performance (no disk IO checks, no database records for filenames, less memory for GD to resize the pic), to native restrictions in the PHP conversion library (GD) which really is still crap at resizing PNG-24 images...
If you want to use "transparent" PNG images (PNG-24), don't use the "image" feature in K2, but instead upload your image via the WYSIWYG editor (TinyMCE, JCE, JCK Editor etc.). More
Tags:
Tags:
Tags:
Tags:
Tags:
Tags:
Tags:
14 October 2011
in Extensions
Please note that this K2 plugin for Joomla is intended for Joomla extension developers only
One of the things that make K2 very powerful is the K2 plugin API, which is built on top of Joomla's plugin API.
Using a K2 plugin you can easily extend the forms used for items, categories and user profiles. That means you can write a simple plugin to add additional fields and extend K2 forms beyond "extra fields". So you can write any plugin that brings programmatic logic inside the K2 item, category and user forms, which is by definition beyond the powers of any "CCK" system.
The K2 plugin has 8 trigger events for the frontend and another 8 for the backend (so you can create additional fields in your K2 forms and then display them in your site). The naming conventions are similar to Joomla's. For the item display in the frontend we have 6 events, identical to Joomla's plugin events and named with the "onK2" prefix instead of just "on". There is 1 event for the category display and 1 more for the user profile display in the frontend. There are also 6+2 events for the backend, which are used to extend the backend forms for the item (one for each tab of the item form plus one generic), category and user profile forms.
Since we're basically adding fields in the backend for these 3 forms, we need to define these fields somewhere. We do so inside the XML of the plugin by defining additional "groups" of parameters (or fields in Joomla 2.5 or newer).
If we want to extend the item form for example, we create a new parameter group with the attribute "name" and value "item-content" or "item-video" (where the value part targets a specific tab in the item form). In a similar fashion, we create parameter groups for "category" and "user". In these groups we can now write new fields in XML format and we can also make use of Joomla content elements (or write our own). These XML fields will extend the forms in the backend. To display the output of these forms in the frontend, we just use a function to render the form values entered.
Just to wrap things up, this is the basic concept of a K2 plugin: We define XML fields in the plugin, which extend the item, category and user forms in the backend. Then we use a function in the frontend (in the main plugin php file) to render these fields.
Download the example plugin we provide and examine the code. This example plugin adds an extra field where you can input a YouTube URL and it will automatically convert it to a video in the frontend. We extend all 3 forms in the backend (item, category, user).
The plugin can be installed using Joomla extension installer.
K2 plugins are installed inside the "/plugins/K2/" folder in your Joomla site.
Use it to learn the K2 plugin API and build Joomla extensions that interface with K2.
To install this Joomla plugin, download the file in your computer and then head over to the Joomla installer and choose to upload the file you just downloaded.
An older release for Joomla 1.5 can be found here: https://github.com/joomlaworks/example-k2-plugin/releases/download/v2.1/plg_k2_example-v2.1_j1.5-1.7.zip More
One of the things that make K2 very powerful is the K2 plugin API, which is built on top of Joomla's plugin API.
Using a K2 plugin you can easily extend the forms used for items, categories and user profiles. That means you can write a simple plugin to add additional fields and extend K2 forms beyond "extra fields". So you can write any plugin that brings programmatic logic inside the K2 item, category and user forms, which is by definition beyond the powers of any "CCK" system.
The K2 plugin has 8 trigger events for the frontend and another 8 for the backend (so you can create additional fields in your K2 forms and then display them in your site). The naming conventions are similar to Joomla's. For the item display in the frontend we have 6 events, identical to Joomla's plugin events and named with the "onK2" prefix instead of just "on". There is 1 event for the category display and 1 more for the user profile display in the frontend. There are also 6+2 events for the backend, which are used to extend the backend forms for the item (one for each tab of the item form plus one generic), category and user profile forms.
Since we're basically adding fields in the backend for these 3 forms, we need to define these fields somewhere. We do so inside the XML of the plugin by defining additional "groups" of parameters (or fields in Joomla 2.5 or newer).
If we want to extend the item form for example, we create a new parameter group with the attribute "name" and value "item-content" or "item-video" (where the value part targets a specific tab in the item form). In a similar fashion, we create parameter groups for "category" and "user". In these groups we can now write new fields in XML format and we can also make use of Joomla content elements (or write our own). These XML fields will extend the forms in the backend. To display the output of these forms in the frontend, we just use a function to render the form values entered.
Just to wrap things up, this is the basic concept of a K2 plugin: We define XML fields in the plugin, which extend the item, category and user forms in the backend. Then we use a function in the frontend (in the main plugin php file) to render these fields.
Download the example plugin we provide and examine the code. This example plugin adds an extra field where you can input a YouTube URL and it will automatically convert it to a video in the frontend. We extend all 3 forms in the backend (item, category, user).
The plugin can be installed using Joomla extension installer.
K2 plugins are installed inside the "/plugins/K2/" folder in your Joomla site.
FEATURES
A example K2 plugin for Joomla intended for Joomla extension developers only. It will create a field in the K2 item form to insert a YouTube video URL, which will then be rendered in the item page (in the site frontend).Use it to learn the K2 plugin API and build Joomla extensions that interface with K2.
DEMO & SHOWCASE
There is no demo or showcase available for this extension. But all the extensions referenced here https://getk2.org/show/tag/built%20by%20joomlaworks have been developed from this plugin.REQUIREMENTS
This is a K2 plugin for Joomla and the only basic requirements to use it are:- K2 v2.5.x or newer installed
- Joomla 2.5 or 3.x installed
LICENSE
This is a Joomla extension developed by JoomlaWorks and released under the GNU/GPL v2 license.ADDITIONAL INFO
Some helpful links:- K2 - https://getk2.org
- Joomla - http://www.joomla.org
DOWNLOAD
You can grab the latest release here: http://goo.gl/WQpl1I (v2.2)To install this Joomla plugin, download the file in your computer and then head over to the Joomla installer and choose to upload the file you just downloaded.
An older release for Joomla 1.5 can be found here: https://github.com/joomlaworks/example-k2-plugin/releases/download/v2.1/plg_k2_example-v2.1_j1.5-1.7.zip More
Tags:
Advertisement