Difference between revisions of "Cchost/customize"

From Creative Commons
Jump to: navigation, search
(Admin Customizations)
(Admin Customizations)
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Customizing a ccHost Installation=
+
[[Category:ccHost]]
 +
[[Category:ccMixter]]
 +
[[Category:Developer]]
 +
[[Category:Software]]
 +
[[Category:Technology]]
 +
{{draft}}
 +
{{lowercase}}
 +
 
 
There are many levels of customization to a ccHost installation with each level requiring more and more technical skill. It is not obvious what kind of customization is possible at each level so here are some hints that might help you to decide what you need to do in order to achieve your goals.
 
There are many levels of customization to a ccHost installation with each level requiring more and more technical skill. It is not obvious what kind of customization is possible at each level so here are some hints that might help you to decide what you need to do in order to achieve your goals.
  
Line 6: Line 13:
 
*Create formatted [[Cchost/admin/Content_Manager|content pages]]
 
*Create formatted [[Cchost/admin/Content_Manager|content pages]]
 
*Upload [[Cchost/admin/FAQ_and_Cookbooks#How_do_I_change_the_banner_.28logo.29.3F|banner images (logos)]]
 
*Upload [[Cchost/admin/FAQ_and_Cookbooks#How_do_I_change_the_banner_.28logo.29.3F|banner images (logos)]]
*Control the text in the header and footer of every page
+
*Edit the text in the header and footer of every page
*Control the menu items and groups on every page
+
*Edit the menu items and groups on every page
*Control the navigation tabs at the top of every page and create sets of "sub-navigation" tabs that are embedded in a page
+
*Edit the [[Cchost/customize/Navigation_Tabs|navigation tabs]] at the top of every page and create sets of "sub-navigation" tabs that are embedded in a page
 
*Create your own submit form types
 
*Create your own submit form types
 
*Select basic layout of pages from a list of over 40 schemes (e.g. menus on the right, flexible width of main content page, etc.)
 
*Select basic layout of pages from a list of over 40 schemes (e.g. menus on the right, flexible width of main content page, etc.)
Line 18: Line 25:
 
*Save and retrieve multiple versions of 'skin profiles' and create 'mini sites' with different look and feel for each one
 
*Save and retrieve multiple versions of 'skin profiles' and create 'mini sites' with different look and feel for each one
 
*Add "pseudo verifying" file types to the system
 
*Add "pseudo verifying" file types to the system
 +
*Select listing types for a list of options
 +
*Configure the [[Cchost/How_Content_is_Displayed#Query_Browser|query browser]]
  
 
==Query Customizations==
 
==Query Customizations==
Line 24: Line 33:
 
   tags=remix&sinced=2 weeks ago&sort=rankings&title=Hot Remixes
 
   tags=remix&sinced=2 weeks ago&sort=rankings&title=Hot Remixes
  
The query engine also works with topic contents.
+
The query engine also works with topic contents. Documentation for the Query API can be found at '''<your_installation_root>/query-api'''.
  
 
==Configuration Customizations==
 
==Configuration Customizations==
Line 30: Line 39:
 
    
 
    
 
Even if you don't exactly know what the configuration syntax is or how it works, you can easily customize your installation with some judicious cut and paste in configuration files that the system will look for in your <local_files> directory. These include:
 
Even if you don't exactly know what the configuration syntax is or how it works, you can easily customize your installation with some judicious cut and paste in configuration files that the system will look for in your <local_files> directory. These include:
*String sets
+
*How to [[cchost/admin/config_customize#Strings|replace strings]] in forms, prompts and listings.
*Color schemes
+
*Create your own [[cchost/admin/config_customize#Colors|custom color scheme]].
*Sidebar extras
+
*Create specialized [[cchost/admin/config_customize#Sidebar_extras|sidebar widgets]].
  
 
==Markup Customization==
 
==Markup Customization==
Line 42: Line 51:
 
If you are generally happy with the overall look and layout of the site but want to change specific screen, you can create customized display layouts and then select them through the admin screens:
 
If you are generally happy with the overall look and layout of the site but want to change specific screen, you can create customized display layouts and then select them through the admin screens:
  
*Upload page
+
*[[cchost/Custom_Query_Templates|Custom query templates]] (way more powerful than you might first realize)
*Upload listings
+
*[[cchost/Static_HTML_Pages|Static HTML]] (and PHP) pages
*Query browser listing
+
*[[cchost/How_Content_is_Displayed#Upload Page|Upload page]]
 +
*[[cchost/How_Content_is_Displayed#Upload Listings|Upload listings]]
 +
*[[cchost/How_Content_is_Displayed#Query Browser|Query browser listing]]
 
*Form layouts
 
*Form layouts
*Custom query templates (way more powerful than you might first realize)
 
 
   
 
   
 
{{Infobox|This assumes that all the data you need to display is already available and you are simply re-arranging items. You can remove items by simply not displaying them, but if you want to add new data fields you can not do that at 'Markup' level of customization.}}
 
{{Infobox|This assumes that all the data you need to display is already available and you are simply re-arranging items. You can remove items by simply not displaying them, but if you want to add new data fields you can not do that at 'Markup' level of customization.}}
Line 56: Line 66:
  
 
==Developer Customizations==
 
==Developer Customizations==
 +
Any file with a '''.php''' extension in '''<local_files>/lib''' will be picked up by ccHost, parsed and executed. So all your custom code can go into that directory in one .php file, in multiple, however you like.
 
===Common===
 
===Common===
 
There are many customizations that can be done with just a few lines of code. Some of those the more popular ones are:
 
There are many customizations that can be done with just a few lines of code. Some of those the more popular ones are:
*Add or remove form fields including the submit forms
+
*[[cchost/developer/customize#Add_or_remove_form_fields|Add or remove form fields]] including the submit forms
*Add data fields per user and per upload
+
*Hooking the [[cchost/developer/Hooking_the_User_Profile_page|user profile page]]
*Retrieving custom data for listing display
+
*Add data fields [[cchost/developer/customize#Add_data_per_user|per user]] and [[cchost/developer/customize#Add_data_per_upload|per upload]]and
*Saving and retrieving data from the system configuration
+
*[[Cchost/developer/customize#Using_custom_data_in_a_template|Retrieving custom data]] for listing display in a template
*Adding an admin setting to settings menu
+
*Saving and retrieving [[Cchost/developer/customize#Saving_and_retrieving_system_configuration_data|data from the system configuration]]
*Mapping a URL to your custom code
+
*[[Cchost/developer/customize#Adding_settings_to_the_admin_menus|Adding an admin setting]] to settings menu
 +
*[[Cchost/developer/customize#Mapping_URLs_to_custom_code|Mapping a URL]] to your custom code
  
 +
===Event Hooking===
 
ccHost triggers events at certain key moments and you can register to be notified at those times. The more popular ones of those are:
 
ccHost triggers events at certain key moments and you can register to be notified at those times. The more popular ones of those are:
*When a new file has been uploaded
+
*When a [[cchost/developer/tutorial/Hooking_File_Events|file has been uploaded or deleted]].
 
*When a file or entire upload record has been deleted
 
*When a file or entire upload record has been deleted
 
*When the remix sources for an upload has changed
 
*When the remix sources for an upload has changed
Line 78: Line 91:
 
*Adding % macros that expand on file renaming and ID3 tagging
 
*Adding % macros that expand on file renaming and ID3 tagging
 
*Adding and verifying new parameters to the query engine
 
*Adding and verifying new parameters to the query engine
*Replacing the getID3 verifier
+
*[[cchost/developer/tutorial/Replacing the File Verifier|Replacing the file verifier]]
 
*Adding a new search type
 
*Adding a new search type

Latest revision as of 16:56, 7 November 2008


There are many levels of customization to a ccHost installation with each level requiring more and more technical skill. It is not obvious what kind of customization is possible at each level so here are some hints that might help you to decide what you need to do in order to achieve your goals.

Admin Customizations

In ccHost 5 there are dozens of customizations that do not require any coding knowledge. You can do all these simply by filling out forms:

  • Create formatted content pages
  • Upload banner images (logos)
  • Edit the text in the header and footer of every page
  • Edit the menu items and groups on every page
  • Edit the navigation tabs at the top of every page and create sets of "sub-navigation" tabs that are embedded in a page
  • Create your own submit form types
  • Select basic layout of pages from a list of over 40 schemes (e.g. menus on the right, flexible width of main content page, etc.)
  • Select default font family and size from a list.
  • Select color scheme from a list of pre-authored color sets
  • Select 'sidebar extras' from a list of available plugins
  • Select how your forms are laid out from a list of available layouts.
  • Select a string set that changes every string in the system to fit your type of site (e.g. image gallery, remix community, etc.)
  • Save and retrieve multiple versions of 'skin profiles' and create 'mini sites' with different look and feel for each one
  • Add "pseudo verifying" file types to the system
  • Select listing types for a list of options
  • Configure the query browser

Query Customizations

With a little knowledge of URL building you gain control over what uploaded content is displayed in the settings of your choice. For example if you want to show the most popular uploads tagged 'remix' for the last two weeks you specify that using URL syntax in a navigation tab, including the title to display:

 tags=remix&sinced=2 weeks ago&sort=rankings&title=Hot Remixes

The query engine also works with topic contents. Documentation for the Query API can be found at <your_installation_root>/query-api.

Configuration Customizations

The way the system is set up, all of the customizations in the 'Admin' section above are actually fancy ways of manipulating configuration files already in your system, many of which can be superseded by simply making your own version.

Even if you don't exactly know what the configuration syntax is or how it works, you can easily customize your installation with some judicious cut and paste in configuration files that the system will look for in your <local_files> directory. These include:

Markup Customization

If you are comfortable with a little HTML and CSS hacking and you still want more control over your installation then you will find quite a large world open up to you.

NOTE to PHP developers: Because all templates are parsed as PHP, extreme hacking is always available to you at this level of customization. While it's not the most 'portable' way to hack the site, if you're convinced you understand the consequences of such actions here is the first place where a few lines of PHP hackery can have powerful effect.

Custom Pieces

If you are generally happy with the overall look and layout of the site but want to change specific screen, you can create customized display layouts and then select them through the admin screens:

This assumes that all the data you need to display is already available and you are simply re-arranging items. You can remove items by simply not displaying them, but if you want to add new data fields you can not do that at 'Markup' level of customization.

Custom Skins

The ultimate control over look and feel of an installation can be accomplished by creating your own skin template by browsing to admin/skins/create which will not only copy a template framework, but also a skin profile.

Once this template is installed into your <local_files>/skins directory, you can customize the 'body' template which controls the contents of every page's header, footer, layout, etc. You can also start copying individual templates to your skin directory from ccskins/shared and the system will use your version.

Developer Customizations

Any file with a .php extension in <local_files>/lib will be picked up by ccHost, parsed and executed. So all your custom code can go into that directory in one .php file, in multiple, however you like.

Common

There are many customizations that can be done with just a few lines of code. Some of those the more popular ones are:

Event Hooking

ccHost triggers events at certain key moments and you can register to be notified at those times. The more popular ones of those are:

  • When a file has been uploaded or deleted.
  • When a file or entire upload record has been deleted
  • When the remix sources for an upload has changed
  • When a new topic has been added or deleted
  • When a page session is starting (but after the user is known and configuration in place)
  • After the page has been setup, but before handed off to the template engine for rendering
  • Several different phases of a form being constructed (this applies to every single form in the system)

Esoteric

There are many other hooks in the system (over 100) many of which still fall in the category of "easy to hook" even if the hook itself may or may not require heavy lifting. These include:

  • Adding % macros that expand on file renaming and ID3 tagging
  • Adding and verifying new parameters to the query engine
  • Replacing the file verifier
  • Adding a new search type