Understanding ccHost URLs

Understanding how URLs work in ccHost is a very important concept that you should understand before doing anything else.

URL Parts

ccHost URLs are composed of four main parts:

1. Root URL of installation

   This is the URL address of where index.php lives. For example: http://example.com, or http://example.com/cchost

2. Virtual Root

   Don't worry if you don't know what a 'ccHost virtual root' is, we'll get to it here but for now assume it's the word media.

3. Command

   This part of the URL maps to an internal command in ccHost. This can be anything from a request for a submit form, a feed, a record listing, etc. Examples are people which shows a listing of the latest registered users who have uploaded or files which lists the latest uploads.

4. Parameters

   Many if not most commands accept and even require parameters. For example, adding a specific user's name to the people command will display the user's main page, e.g. people/rejon

You should refer to the ccHost Command Reference for a listing of all available commands.

If you have enabled 'pretty URLs' in your installation then all the elements are strung together into one URL:

http://example.com/media/people/rejon

If not, then everything starting from the virtual root is prepended the following way:

http://example.com?ccm=/media/people/rejon

URLs in Menus and Navigator Tabs

In general when asked for an URL for menus or navigator tabs, all you enter is the command and parameters. The system will assume you want the command to execute in the current virtual root and already knows if your site uses pretty URLs or not. In fact you can change your installation to use pretty URLs later and all these menu items will continue to work.

If you enter a fully qualified URL (anything that starts with http://) the menu and tab systems will redirect the browser to that url, no matter what the rest of the address it. If the action URL does not start with http:// then the system will assume this is a ccHost command with parameters and attempt to execute it as outlined above.

URLs in XHTML Templates

It is very important that you use ${home-url} variable as a prefix to commands (more about home-url) in URLs when working in template files:

You can <a href="{$home-url}submit">submit files</a> to our site...

The URL in the href attribute will auto-magically expand to something like:

http://yourserver.com/cchost?ccm=/myvroot/submit

Don't put a trailing forward slash after the ${home-url} but if you need a parameter then put one between the command and the parameter

Go to <a href="{$home-url}people/{user_name}">your home page</a> now

Forcing Virtual Roots

There may come a time where you want a menu item like Register or a navigator tab like Home to go to a specific virtual root like media. In that case you will want to specify the full URL in the menu item or tab, like http://root-installation.com?ccm=/media/register. That way no matter what virtual root the user is in, they will be taken to the main register screen or in the case of a 'Home' tab simply http://root-installation.

If you change your site to use pretty URLs at some point these URLs will continue work, they just won't be, well, pretty. At that point you can edit these menu items to the pretty versions without the ?ccm=.

URLs in This Document

In this documentation when asked to browse to a location, it will only say the command and parameters and assume you will prepend the proper parts that apply to your installation and virtual root configuration. For example, if you see a request like "browse to admin/menu/killcache" that you are expected to enter the following into your browser's address bar:

http://example.com?ccm=/media/login  (with pretty URLs OFF)
http://example.com/media/login (with pretty URLs ON)

Note the addition of the virtual root media in both cases. If you are reading this, it is probably because you forgot to add that.

In some cases you may be asked to add a query, as in 'browse to command?query=foo'.

This would expand to:

http://example.com/media/command?query=foo (pretty URLs ON)
http://example.com?cmd=/media/command&query=foo (pretty URLs OFF)

Note how the question mark became an ampersand in the non-pretty URL version.

Most of the requests to browse to a command assume you are currently logged in with administrative rights.

Terminology: "tag" vs. "tag" vs. "tag"

It is worth noting as quickly as possible that there are three different meanings of the word tag used when administering a ccHost installation. All three are conventions of the subsystems we use and we felt it was better to use context as a disambiguator rather than inventing terms for processes everybody knows as 'tagging' -- albeit with different purposes.

Super Admins

The main access levels are Everyone, Registered Users and Administrators.

The potentially confusing thing is that both internal commands and user interface elements (like menu items and navigator tabs) have security clearances but they have very different effects:

In other words, you may have a menu item that invokes the editorial/picks command and mark the menu item as Administrators Only but that will only hide the menu item from everyone but Administrators, it would not prevent someone from entering that command into their browser directly and seeing the results of the command because that command happens to be registered integrally for Everyone.

Also note that the access permissions on commands only determine whether the code for that command is initially invoked. The code itself may determine even stricter criteria for the command.

In other words, a command might be marked as for Registered users only (e.g. editorial/submit/{upload_id}) but the code that implements that command may have further restrictions (only allows 'editors' to do the actual submit).

There is also an implied 'ownership' built into the code for upload and user records. That means a command marked Registered users only like files/delete/{upload_id} is further restricted by who 'owns' the upload, that is: who uploaded the thing.

From Global Settings you can assign a small group of users 'super access' which overrides normal admin privileges.

You can use the admin/access command to determine which commands in the system are restricted to this group and this group only.

Where ccHost Looks for Files

Starting in ccHost version 3.1 admins have full control over where ccHost looks for files and writes logs and temporary files during the course of building a page.

If you installed 3.1 or later, the installation program created a directory structure with a name you specified under your root installation that you should, but are not obliged to, use for your customizing your site.

If you installed before 3.1 we recommend you setup a similar structure, but again, you don't have to if you have another system that works for you.

The Global Settings/Paths configuration screen gives you full control of where and how ccHost looks for files.

Directories Explained

The following tables explains both the system and admin directories. These are here for reference in relation to the Global Settings/Paths configuration screen.

The following table describes non-essential files and directories that come with the installation package but are not used by ccHost to operate your installation.