ContentBuilder for Joomla!

- Documentation
1. Introduction
ContentBuilder is a professional content construction extension for Joomla! . It enables the site owner to preserve the content structure by using layout templates. You may also use it to implement catalogs, image galleries, communities, downloads and much more. This reduces the amount of site maintainment and prevents hassle on Joomla! updates, as there is no need to handle multiple extensions no more. Of course, you still could use content template engines offered by editors like JCE, but they still don't organize the data behind your content. Only ContentBuilder is able to organize and re-use the data behind your content and helping you to do much more with it. ContentBuilder does not try to mimic Drupal's CCK implementation (including complexity) but follows a more natural way to organize, display and edit content. In ContentBuilder, everything is a view. One view serves the name and the personal information, the other view serves hard facts like age and gender. For example, you collect user profile data like name, age, gender and personal information in one form, you may create unlimited amounts of views on this data. ContentBuilder helps to collect data, stores it as records and provides functionality and interfaces to do something useful for instance creating well structured content. Every view is organized as a list and a details page for each record. The details page is not meant to be the content itself, but a view can create a content item based on a record. Each content item that has been created within a view is tied to it, while many views may share the same records. You may either use the lists and details as administrative panels in front- and backend to manage your content, or use them for public access, with or without creating content items (articles). Of course the content items (articles) created by a view are native. So things like content plugins and search will work like you would create regular content. The content plugins will also work in the details views of a list. A view can serve: Content Templates: what data to display in content? Editable Templates: what data may be edited? Email Templates: what data to send to users and site maintainers on submission? Permissions: what permissions to grant to a user or a group of users? Data Source: what data source the view should be connected to?

2. How does it work?

The base of all activity is the data source. You may use the built-in Data Storage, BreezingForms (as of version 1.7.5 pre-release) or implement a custom data source using the types interface (PHP programming required).

First, you add all possible fields in your desired source, then defining all of your required views, where each view communicates with the source and manages its outcome (displaying data, serving forms, sending email and observing permissions). In the following, we will first introduce all available items. 2.1 Data Storage The built-in Data Storage is a simple way to define fields that you can use later in your views. You basically add a name and title for the storage and then adding the fields one by one. Each field consists of a name, title and group information. If the field is a group, then you need to define the structure of that group. Later, in your view, a group might be a field of type checkbox, radio or multiple select list. By clicking on a field's name or title, you may edit its value. Click on edit will open a textbox with the group definition, if required. The group definition follows the pattern: Label 1; value1 Label 2; value2 Label 3; value3 Where Label 1 is what you see on the screen and value1 is what will be transferred as value into the data source. The order of the fields has an impact on the order in the content-, editable- and email templates, as they will appear in the same order (excluding the list definition, more later in Views). Once a Data Storage has been created, it will be avaible to serve the views. Don't forget to publish the Data Storage in order to select it in the view! A Data Storage may be edited at any time but be aware that if you delete a field, the data behind that field will get lost. Internally, the Data Storage is represented as database table (database table with the Joomla! DB prefix + name of Data Storage). The interesting part is, that you may transform each field type across your views. In one view, a group might be of type radio group while in another view it may be of type checkbox group. You can even lead out fields to update records but use them in different views.

1)

The built-in Data Storage with some fields for profile data

2.2 Views A view in ContentBuilder is a functional representation of the data source (in our case the Data Storage). It is divided into 9 tabs: View: The command central for the whole view setup. Here you may setup things like: What fields to show in the list and details? What fields should be searchable from the list? What fields should be editable? What type for each editable field? (for example text, textarea, select lists, uploads, etc.) Where to display the view? (backend/frontend/both) What administrative columns to show in the list? (for example record id, article id, actions, publish state, etc.) Overriding the titles of each field. List Intro Text: A descriptive text that shows on top of the list. Html is allowed. List States: Up to 10 positions to make custom states possible. You may either add a title

for each state, select a color and choose a list action plugin to perform an action on the records selected in the list. List action plugins can be either offered by crosstec.de or from the community and are regular Joomla! Plugins. Content Template: The content template should provide the layout for the content of this view. Content can be either a details page from the list or a Joomla! content item (article). The content template setup provides the following settings Create Articles: using no will not generate content items (articles) based on the records from your data source but use the template only for details of a list Delete Articles: if selected, all articles associated with the deleted record(s) will be deleted as well. Title Field: what field out of your view should act as title? Default Category: if there are new records, the selected Joomla! category will be used for the generated article (the category can later be changed in the settings of an article from within the list view). If you assign a list with a Joomla! Menu item, you may also specify different default categories for each menu item. Default Language Code: Select the language the record and article should be associated with on record/article creation. Choose Any to display in all languages. Ignore default and use active language: If selected, the record/article will be associated with the current language of the submitter. Default Publish Up (Days): The amount of days a record/article is allowed to be published. Default Publish Down (Days): The amount of days AFTER publish up, the record/article should be unpublished. Default Access: The default Joomla! Access group under wich the record/article should be created with. Default Featured: Should the associated article be featured (frontpage in J! 1.5)? Auto Publish: Should the record/article be published right away? Create Sample: Will create sample code just once - with all field tags (labels and items). The sample code is provided by the selected theme plugin, defined in the view tab. By default it will use the khepri based theme for content and forms. So it should be installed and enabled, otherwise no sample would be created. Content Prepare: Here you may enter php code to override the output of each field. The structure is: $items["ITEMNAME"]["value"] = "<b>".$items["ITEMNAME"]["value"]."</b>"; $items["ITEMNAME"]["label"] = "<i>".$items["ITEMNAME"]["label"]."</i>";

 Note that this code will be only executed once for articles, so you shouldn't use php code here that pulls data from url requests (if you are using article creation). For list details, the code will be executed every time on accessing the details page. Editable Template: Here you have only one option - to create an editable sample. On sample creation, it will generate all necessary html code to display a form. You may adjust the code to create custom layouts, while the selected theme plugin serves the stylesheets. The sample code is provided by the selected theme plugin, defined in the view tab. This option is not available when edit by type is enabled (for example is BreezingForms is in use). Editable Prepare: Same as Content Prepare, except that it will be applied on the values and labels of the editable form. This option is not available when edit by type is enabled (for example is BreezingForms is in use). Email Templates: Here you may define define settings for emails that are sent on record/content submission one for the user and one for administrative purposes. The available options for each email setup are: Subject: a subject for the email to be sent. You may use values from the submission if you add variables in the form {FIELDNAME} into the subject. For example Hallo administrator, {firstname} {lastname} sent you a message, would show the subject with the first- and lastname from the submission. From Email (alt): an alternative reply-to address From Name (alt): an alternative sender name Recipient(s): all addresses that should reveive a copy of the email, seperated by semicolon. Just like in Subject, you may use variables. For example, if you have a field called email, this recipients setup would send it to the address from the submission + to the specified fixed email address: {email};info@crosstec.de Attach Uploads: specify all upload fields as variable here if you want them to be attached with the email. Example: {picture1};{picture2} would attache uploads from these 2 fields into the email. Is HTML: send the email as html? Create Sample: check and save if you want to create an example based on the settings above. The sample may be edited at any time to fit your needs. Permissions: Set user and group based permissions for this view. The permissions are divided into 3 tabs: Users: this tab gives you the ability to limit certain activities to users / user groups or altering the behaviour of the view. Act As Profile: if enabled, then your view, will act as user profile, including

registration. Means, if no profile exists for the current user, it will start a registration process, else it will display the data and offers editing. If enabled, the registration form will be provided by the built-in form editor. This feature won't (yet) be available for 3rd party form builders like BreezingForms. You will have to choose fields that should act as name, username, email and password (including repeat) and assign it to the profile setup. All fields have to be assigned, otherwise the profiling won't work. Force Login After Submission: if enabled, the form will redirect to login after submission. If the user is already logged in, it will redirect to user area of Joomla!. Force URL After Submission: if a url is given and force login is not enabled then it will redirect to this url, right after submission. Verify Registration Plugin (optional): here you may choose a verification plugin that connects between registration and user activation by email. Means, when the user gets his registration email and clicking on the activation link, the selected verification plugin will take over the verification. For instance, the paypal plugin would redirect to a payment first and once the payment has been done, it will activate the user account but not before. The passtrough plugin won't do anything but will allow you to use the registration from this view, having the Joomla! registration turned off. Combined with the Captcha, this will help to keep bots from your site. Verification Name (optional): a descriptive name for the verification. If not given, it will use the view's name. The name will appear for instance in the paypal item name on payment if using the paypal plugin. Verify View (optional): the id of a view you want to verify (may be the same that you are working on or some other view). Since you can set certain view actions like view, new and edit to require a verification, this would set the verification state of the choosen view to true. What actions should then be verified have to be defined in the plugin params. Plugin Params: some selected plugins may accept parameters to define how they should behave. Please read the documentation of the plugin you choose in order to use its parameters here. Though there are parameters to address the selected plugin, you additionally may use ContentBuilder parameters that will tell the verification how to behave. They are meta-parameters and don't interfere with the plugin itself but helping the verification to know what to do before or after a successfull verification. Available parameters are: verification-msg verify-levels require-view return-admin return-site

Here is an example for the usage of plugin params for verifications (non-plugin specific): require-view: 18; verify-levels: view, new, edit; verification-msg: Your account has been successfully verified; return-admin: index.php; return-site: index.php; more plugin specific params (plugin specific), for example paypal: locale: en; currency-code: USD; tax: 0; use-ipn: true; item-number: 1; cancel-url: http://domain.com/payment-cancelled.html This example would force the user to fill in a form from the view with ID 18, then verifying the actions view, new and edit for the current view, display a message after verification and returning to the selected url one for admin and one for the site users after the registration has been verified. The other sample parameters are plugin specific and will come into action before the verification doess. If you leave out the return option, the verification will try to redirect to the record list of that view. If you set the permissions to disallow list views for unregistered users, leaving out the return urls, might lead to a 403 forbidden error. So always keep the permissions in mind when doing the verification setup. Submission Limit: the total maximum amount of submissions a user is allowed for this view. Edit Limit Per Submission: total maximum amount of edit attempts for a record in this view. View, New, Edit: here you may define what level requires a verification. The verifications can be done manually under Users or using a verification plugin as described above. With Days you specifiy the absolute amount of days a verification will be valid. A zero means unlimited. By Url you may specify an alternative URL if a user is entering a restricted area that requires verification. You may use this to point to a page that should describe why entering is restricted and how to gain permission (for example through payment). Users: by clicking on edit you are able to browse through the site's userlist and set verification levels for certain users in this view (verified and date of verification).

There you also may override the submission and edit limit for each user. The published option will immediately block the user for this view. No matter what permissions you will set, the user will be restricted from anything. Backend: by this tab you control the permissions for this view if it is accessed from the backend (and if defined as backend view, of course). List Own Only: if checked, only records of the current user will be shown in the list. Limited Article Options: if changing the article options is granted, unchecking this will provide even more options to adjust the article behind a record (just like in the Joomla! Backend) Force permissions on owner: as soon as at least one of the options is checked, the user may only access and edit his very own records under the given permissions, ignoring the ones that are defined for user groups. User group based permissions: if permissions are not forced on owner, the permission matrix will be used instead. Here you may grant access to all available site's user groups for the following actions: List Access: grant access to view the list provided by the view. View: allow to view a record. The same rule will apply to generated articles not just the details from a list. New: allow to add new records. Edit: allow to edit records. Delete: allow record deletion. Edit State: allow to trigger a state change. Here we don't mean publish/unpublish! (see List Actions above) Publish: allow to publish/unpublish records. Article Settings: allow to edit the settings of the article behind this record. Change Language: allow to edit the language for the record.

Note that the permissions are not based on inheritance. If you allow a certain group to add and edit new records, it doesn't automatically allow the same for higher groups. Instead, choose exactly the groups you want the permissions to be applied to. This gives you a clear overview about your settings, preventing unnecessary inheritance confusion. The permission settings may have an impact on the list. For example, if you add a publish state column to the list and disable Publish permissions, the publish/unpublish action will disappear from the list.

The default permissions on view creation are List Access and View across all groups. Please keep that in mind if you create a new view.

2) The view setup

3. Plugins
ContentBuilder makes heavy use of the Joomla! plugin infrastructure. There are several different aspects where plugins might come into play: on content display => giving extra value to the displayed content (for example image display, thumbnails, file downloads, etc.) on list state change => trigger an action on selected records from within a list

on form submission => trigger some general action before and after submit on form validation on verification theming => validate one or more fields before the submission is stored => handle registrations, payments, etc. => provide a custom look and feel for list, details, content and forms

Though all of these aspects are important, we would like to focus on content and verification plugins as ContentBuilder already ships with very helpful plugins. For further plugin development, please visit http://crosstec.de and check out the latest development information or ask in the forums.

3.1 Content Plugins Though you may use regular Joomla! content plugins (for list details and articles), there are a few special ones written and shipped with ContentBuilder that help you to spice up your or even add functionality to your content. The 3 most important plugins of this kind currently are Image Scale, Download and Verify. Please make sure all these plugins are installed and enabled (should already be the case) or do so if missing: Image Scale: this plugin tries to pick a value and render a scaled image out of it (usually an image path from an upload type form element). This plugin may be used to create image galleries, profile pages or any content where images might come into play. So let's say you have an upload form element where the user is supposed to upload an image and the name of that element would be myimage, then simply add this tag into the Content Template of your view: {CBImageScale field: myimage; width: 50;} This will render a thumbnail of the size width and height 50px, right at the spot where you defined it. If Image Scale is not able to render this image, it will return nothing. There are several reasons why rendering is not possible. The plugin is clever enough not to run into memory or timeout issues, so if nothing is rendered at all (not even in the html source), then it is most likely that the file is not existing, too large or would consume too much time or memory to scale down. Once the image has been generated, it will be cached to prevent cpu and memory overhead on your server. The default cache time is 86400 seconds (= 1 day) but this value may be altered. If the image is updated and the width or height differs from the cached one, it will automatically create a new cached image. Supported image types are GIF, JPG and PNG. Here is a list of all available options with example values to call the Image Scale plugin: width: 50; => will render the image with the width of 50 pixels. If only the width is given, it will use the same value for height. Either width or height is required. => will render the image with the height of 50 pixels. If only the height is given, it will use the same value for height. Either width or height is required. => the name of the field to pick the path to the image from (usually a file upload field). => the color for the background space if the scaled image doesn't fit within the given width/height boundaries as hex value.

height: 50;

field: *fieldname*; background-color: #ffffff;

 folder: tmp; cache: 86400;

=> an alternative cache folder. Default is media/contentbuilder/plugins/image_scale/cache => the caching time for this image. Default is 86400 seconds. If set to none, caching will be disabled for this image. => the global cache time for all images within the given folder. All cached images within this folder will be deleted after the given seconds. Default is 86400 seconds. => Will float the image into the given direction. Possible values are left or right. => if set to true, the scaled image will be clickable, opening the original image within a modal window. If the dimensions of the image exceed a certain size, it will skip displaying as modal and instead use a regular javascript based popup window.

global_cache: 86400;

align: left; open: true;

alt: *some alternative text* => adds an alternative alt text to the generated image tag title: *some title text* => adds a title to the generated image tag

Download: another interesting content plugin for ContentBuilder to create downloads from upload fields. With this plugin you may implement download galleries or paid download in combination with verification plugins (for example paypal). The procedure is similiar to Image Scale, except that it handles downloads. Beside serving downloads, it will count the hits for each file, display mime type and file size information. All these information may be turned off by the plugin settings. Please note that if you are using IIS and CGI you will have to raise the CGI execution time in order to offer big files. Users of Apache webservers are not affected! So let's say you have an upload form element where the user is supposed to upload a zip file and the name of that element would be myfile, then simply add this tag into the Content Template of your view: {CBDownload field: myfile;} This will render a download box if the file exists. Otherwise it won't display anything. The download box contains the following information: File name Mime type File size Number of downloads

Each information entitiy may be turned off with the plugin settings. Currently, the following settings are available: field: *fieldname*; => the name of the upload field

box-style: border-width:thin::border-color:#000000; => the style of the box that contains the download. Use regular CSS here. Please seperate each css directive by :: instead of semicolon! info-style: color: red; align: left; info: false; hide-filename: true; hide-mime: true; hide-size: true; hide-downloads: true; => same usage as box-style, will be applied to the container that is wrapped by the box. => Will float the image into the given direction. Possible values are left or right. => if set to false all info for this download will be turned off. Default is true. => if set to true, the filename will be hidden from the info. => if set to true, the mime type will be hidden from the info. => if set to true, the size will be hidden from the info. => if set to true, the amount of downloads will be hidden from the info.

Currently, these are the two most important content plugins that ship with ContentBuilder but there is another one that you shouldn't miss - the Verify plugin as it provides adding verification methods to any of your content, for instance paypal payments. Other plugins that handle different payment methods or coupon based verifications are thinkable and can be developed at any time. Please visit http://crosstec.de for further information on plugin development. The Verify plugin lets you load verification plugins (the same that are used in views for registrations above) right into your content and executes them. So let's say you would like to offer paid content submission (for example classified ads), you might like to have a paypal button. When clicking on that button it should redirect to paypal and if the payment has been successfull, the user should automatically be verified to submit content. Well, in combination with the paypal plugin, the Verify plugin provides exactly this feature. 3.2 Paid Verifications with PayPal in Content Items You will need two plugins to be installed and enabled in order to make verifications and paypal

payments work, the Verify and the paypal plugin. Once installed and enabled, you may either enter the Verify tag into your content template or any other existing Joomla! content item (article). The Verify plugin is not tied to a specific view or record, so it may be used globally and independend from ContentBuilder (though it needs ContentBuilder to operate). Please do not forget to edit paypal's setup and entering the merchant data, otherwise paypal will throw an error on payments. The paypal token can be obtained in the merchant's account. The following sample tag will... ...render a link with the label Click here to pay!. ...require to fill in a form from the view with ID 30 (if not existing yet). ...redirect to the paypal payment for the item named 10 Day Subcription. ...verify the view with ID 36 and granting the levels view, new and edit if the payment has been successfull. {CBVerify plugin: paypal; require-view: 30; verify-view: 36; verify-levels: view, new, edit; verification-name: 10 Day Subscription; desc: Click here to pay!; amount: 19.00; } This Verify setup is seperated into 2 parts: 1. The Verify specific options plugin, require-view, verify-view, verify-levels, verification-name and desc 2. The paypal plugin specific option amount (= price). What happens here is that the Verify plugin communicates with the paypal plugin and passes the options to it, while it uses its own specific options to decide what to do if the paypal plugin responded with a successfull verification (= payment). A special note on the option require-view: if the required view is a profile view, it will of course register the user (if not existing) and properly assign the user id to the payment. So you actually may combine registrations and payments. The same payment may be applied directly in the view setup if acting as profile but then the paypal payment would appear when clicking on the link in the registration email. Here is a complete and seperated overview with example values over all available Verify and PayPal options: Verify: plugin: paypal; => choosing the verification plugin to use.

 verification-name: Subscription;

=> a descriptive name for the verification. Verification plugins such as paypal might use it as item name if none given. => a custom verification message. => using an image url instead of a link. => the width of the image. => the height of the image. => a text to display within the link or, if an image is used, having the description as image title. => the ID of the view you want to verify for the current user. => granting the levels new, view and edit after a successfull verification. => force the use to fill in a form from another view (or this view) with the given ID. => an alternative return url after verification if the verification happened in backend context. Default is returning to the corresponding list of the verified view. => an alternative return url after verification if the verification happened in frontend context. Default is returning to the corresponding list of the verified view.

verification-msg: Successfully verified! image: media/images/paypal.gif image-width: 50; image-height: 50; desc: Click here to pay!

verify-view: 18; verify-levels: new, view, edit require-view: 30;

return-admin: index.php

return-site: index.php

PayPal: amount: 19.00; tax: 0; locale: en; currency-code: USD; item-number: 1; => the price to pay for the item => the tax for the item => the language of the PayPal payment screen. Default is en. => the currency for the payment. Default is USD. => the product item number

cancel-url: http://domain.com/cancelled.html => the url to redirect when cancelling the

payment use-ipn: true; => if set to true, paypal's instant payment notifications will be used to verify the payment. Default is false. If you would like to use IPN, please enable it as well in your paypal account. As IPN url please use your domain.

You might like to know that the Verify setup supports multi languages. The setup of multi language verifications is analog to the above. You just need to split the options by | for each language and use 3 underscores to bind the option value to the desired language. Here is an example for english and german: {CBVerify plugin: paypal; require-view: en___30|de___31; verify-view: en___36|de___37; verify-levels: view, new, edit; verification-name: en___10 Day Subscription|de___10 Tage Mitgliedschaft; desc: en___Click here to pay!|de___Hier klicken zum Bezahlen!; amount: en___19.00|de___15.00; locale: en___en|de___de; currency-code: en___USD|de___EUR; } If the user has an active language that is not described in the setup, then it will pick the first language it can find. In our example above it will be english.

What comes next?

So far we hope we were able to give you a good overview about the available options of ContentBuilder. Maybe you got an idea now how you can use ContentBuilder to achieve what you are planning for your website? If not, then please contact our support or write in our forums and help us to add new ideas into ContentBuilder. This document is supposed to grow with the development of ContentBuilder. Please checkout http://crosstec.de for the latest version and also have a look at the available training videos.