Cchost/concepts/Virtual Roots

From Creative Commons
Jump to: navigation, search


Docs Home Install Upgrade Troubleshoot Customize Admins Devs Content Query Templates Commands Skins


Your ccHost site can be configured to look like many different sites with just a few menu selections and no changes to your web server configuration.

Why?

Why do this? Let's say you are running a remix community as your main site but also want to run a contest or you mainly run contests and you also want to have a personal 'media weblog' on the side -- or -- whatever.

Most configuration settings in ccHost are specific to each virtual root. That means each virtual root can have it's own skin, it's own menus, home page, admins, page content, navigator tabs, rules for file naming, MP3/ID3 tagging, etc., etc.

By default a virtual root will inherit settings from the main root (media) until you override them. This is a very powerful feature but can lead to plenty of confusion if not taken into account when dealing with virtual roots. (Prediction: you will forget this admonition, then you'll get frustrated, then you'll remember it and we can say 'I told you so.')

Default Virtual Root ('media')

The default virtual root is called media. You can not delete this root, you can add your own. Every ccHost command in a URL starts with the virtual root. If you don't supply one then media is assumed.

For example, for sites with pretty URLs turned off:

 http://example.com?ccm=/media/submit // pretty URLs off
 http://example.com/media/submit      // pretty URLs ON

Is the same as

 http://example.com?ccm=/submit  // pretty URLs off
 http://example.com/submit       // pretty URLs ON

However, if you want to execute the submit command in another virtual root you'll have to specify that:

 http://example.com?ccm=/my_virtual_root/submit  // pretty URLs off
 http://example.com/my_virtual_root/submit       // pretty URLs ON

Name Conflicts

If you create a document called bobby you can view the file with:

 http://example.com/media/docs/bobby 

Since media is the default virtual root you can also see it with:

 http://example.com/docs/bobby

Since docs is the default command you also see it with:

 http://example.com/bobby

Now you can see why naming your virtual root bobby will be a conflict. If you did that, ccHost would consider the URL above to be a request to go the home page of the bobby

It would be equally bad to call your virtual root docs (or any other command for that matter) because you would be disabling that command for the media root (the virtual root has precedence).

Creating a Virtual Root

To create a new virtual root go to Global Settings -> Virtual ccHost (or browse to admin/cfgroot

The only initial requirement will be the core name of the new virtual root. Make it a good one because it will be seen in many hundreds of URLs. Make it short, lowercase, alpha only, easy to type ('aqz' is not easy to type, try it) but descriptive like 'albums' or 'cindysart'.

See Your Virtual Root

After naming the virtual root you can then use that name in the URL address to access it. For example, let's say you name your new root myroot, to access that root simply tack it on to the domain and directory:

 http://example.com?ccm=/myroot // Pretty URLs off
 http://example.com/myroot      // Pretty URLs ON

Setting Properties in a Virtual Root

  1. Log in as admin (if not already)
  2. Click on Manage Site
  3. Select your virtual from the drop-down at the top of the form

You will now be setting configuration values for your virtual root.

Deleting a Virtual Root

  1. Log in as an admin (if not already)
  2. Click on Manage Site (or browse to admin/site/local)
  3. Select the virtual root from the Edit the settings for virtual root drop down
  4. click on the Delete this virtual root button

Developers

Determining the Current Virtual Root

The ccHost runtime will put the current virtual root into a global called $CC_GLOBAL_ROOT.

So if you code is saving some root specific data, say to a browser cookie:

 global $CC_CFG_ROOT;

 $data['last_vroot'] = $CC_CFG_ROOT;
 

This global is available by the time the CC_EVENT_APP_INIT event is triggered.

Saving Root Specific Settings

Read this section in order to save your own custom configuration settings into different virtual roots.