Commit d1d3dcf1 authored by Andrew Manning's avatar Andrew Manning

Deleted old versions that have been integrated. Integrated and slightly revised Comanche doco.

parent ce87a0c1
......@@ -18,7 +18,7 @@ class Permissions {
* permission roles. You will want to set a default PermissionLimit for each channel and also
* provide a sane default for any existing connections. You may or may not wish to provide a
* default auto permission. If in doubt, leave this alone as custom permissions by definition
* are the responsbility of the channel owner to manage. You just don't want to create any
* are the responsibility of the channel owner to manage. You just don't want to create any
* suprises or break things so you have an opportunity to provide sane settings.
*
* Update the version here and in PermissionRoles
......
......@@ -308,8 +308,16 @@ empty:
1. On the $Projectname server visit new.hub/locs and upgrade to your channel to a primary one. And when the old Redmatrix server is still listed delete them here as well. Press "Sync" to inform all other server in the grid.
### Troubleshooting
#### Log files
The system logfile is an extremely useful resource for tracking down things that go wrong. This can be enabled in the admin/log configuration page. A loglevel setting of LOGGER_DEBUG is preferred for stable production sites. Most things that go wrong with communications or storage are listed here. A setting of LOGGER_DATA provides [b]much[/b] more detail, but may fill your disk. In either case we recommend the use of logrotate on your operating system to cycle logs and discard older entries.
At the bottom of your .htconfig.php file are several lines (commented out) which enable PHP error logging. This reports issues with code syntax and executing the code and is the first place you should look for issues which result in a "white screen" or blank page. This is typically the result of code/syntax problems.
Database errors are reported to the system logfile, but we've found it useful to have a file in your top-level directory called dbfail.out which [b]only[/b] collects database related issues. If the file exists and is writable, database errors will be logged to it as well as to the system logfile.
In the case of "500" errors, the issues may often be logged in your webserver logs, often /var/log/apache2/error.log or something similar. Consult your operating system documentation.
There are three different log facilities.
**The first is the database failure log**. This is only used if you create a file called specifically 'dbfail.out' in the root folder of your website and make it write-able by the web server. If we have any database failed queries, they are all reported here. They generally indicate typos in our queries, but also occur if the database server disconnects or tables get corrupted. On rare occasions we'll see race conditions in here where two processes tried to create an xchan or cache entry with the same ID. Any other errors (especially persistent errors) should be investigated.
......@@ -343,3 +351,14 @@ To immediately clear out all the extra logging stuff you added. Use the informa
1. Enable the **logrot** addon in the official [hubzilla-addons](https://github.com/redmatrix/hubzilla-addons) repo
1. Create a directory in your web root called `log` with webserver write permissions
1. Go to the **logrot** admin settings and enter this folder name as well as the max size and number of retained log files.
#### Reporting issues
When reporting issues, please try to provide as much detail as may be necessary for developers to reproduce the issue and provide the complete text of all error messages.
We encourage you to try to the best of your abilities to use these logs combined with the source code in your possession to troubleshoot issues and find their cause. The community is often able to help, but only you have access to your site logfiles and it is considered a security risk to share them.
If a code issue has been uncovered, please report it on the project bugtracker (https://github.com/redmatrix/hubzilla/issues). Again provide as much detail as possible to avoid us going back and forth asking questions about your configuration or how to duplicate the problem, so that we can get right to the problem and figure out what to do about it. You are also welcome to offer your own solutions and submit patches. In fact we encourage this as we are all volunteers and have little spare time available. The more people that help, the easier the workload for everybody. It's OK if your solution isn't perfect. Every little bit helps and perhaps we can improve on it.
Zot API
=======
channel/export/basic
Export channel data
channel/stream
Fetch channel conversation items
network/stream
Fetch network conversation items
[files](help/api/api_files)
List file storage
filemeta
Export file metadata for any uploaded file
[filedata](help/api/api_filedata)
Fetch file contents or partial contents for any uploaded file
file/export
file
[albums](help/api/api_albums)
List photo albums
photos
list photo metadata
photo
[group](help/api/group)
List privacy groups
[group_members](help/api/group_members)
List members of a privacy group
[xchan](help/api/api_xchan)
Global extended channel (identity) information
[item/update](help/api/api_item_update)
Create or update an item (post, activity, webpage, etc.)
item/full
Get all data associated with an item
abook
Connections
abconfig
Connection metadata (such as permissions)
perm_allowed
Check a permission for a given xchan
[h2]Channels[/h2]
[h3]What are channels?[/h3]
Channels are simply collections of content stored in one place. A channel can represent anything. It could represent you, a website, a forum, photo albums, anything. For most people, their first channel with be "Me".
The most important features for a channel that represents "me" are:
[ul]
[*]Secure and private "spam free" communications
[*]Identity and "single-signon" across the entire network
[*]Privacy controls and permissions which extend to the entire network
[*]Directory services (like a phone book)
[/ul]
In short, a channel that represents yourself is "me, on the internet".
[h3]Creating channels[/h3]
You will be required to create your first channel as part of the sign up process. You can also create additonal channels from the "Select channel" link.
You will be asked to provide a channel name, and a short nick name. For a channel that represents yourself, it is a good idea to use your real name here to ensure your friends can find you, and connect to your channel. The short nickname will be used to generate a "webbie". This is a bit like a username, and will look like an email address, taking the form nickname@domain. You should put a little thought into what you want to use here. Imagine somebody asking for your webbie and having to tell them it is "llamas-are_kewl.123". "llamasarecool" would be a much better choice.
Once you have created your channel, you will be taken to the settings page, where you can configure your channel, and set your default permissions.
Once you have done this, your channel is ready to use. At [observer=1][observer.url][/observer][observer=0]example.com/channel/username[/observer] you will find your channel "stream". This is where your recent activity will appear, in reverse chronological order. If you post in the box marked "share", the entry will appear at the top of your stream. You will also find links to all the other communication areas for this channel here. The "About" tab contains your "profile", the photos page contain photo albums, and the events page contains events share by both yourself and your contacts.
[h3]The grid, permissions and delegation[/h3]
The "Grid" page contains all recent posts from across $Projectname network, again in reverse chronologial order. The exact posts that appear here depend largely on your permissions. At their most permissive, you will receive posts from complete strangers. At the other end of the scale, you may see posts from only your friends - or if you're feeling really anti-social, only your own posts.
As mentioned at the start, many other kinds of channel are possible, however, the creation procedure is the same. The difference between channels lies primarily in the permissions assigned. For example, a channel for sharing documents with colleagues at work would probably want more permissive settings for "Can write to my "public" file storage" than a personal account. For more information, see the [zrl=[baseurl]/help/roles]permissions section[/zrl].
You can also delegate control of your channels' posts and connections, but not its configurations, to another channel. That is done by editing a connection and assigning it the permission to administer your channel's resources.
#include doc/macros/main_footer.bb;
[b]Personal Cloud Storage[/b]
$Projectname provides an ability to store privately and/or share arbitrary files with friends.
You may either upload files from your computer into your storage area, or copy them directly from the operating system using the WebDAV protocol.
On many public servers there may be limits on disk usage.
[b]File Attachments[/b]
The quickest and easiest way to share files is through file attachments. In the row of icons below the status post editor is a tool to upload attachments. Click the tool, select a file and submit. After the file is uploaded, you will see an attachment code placed inside the text region. Do not edit this line or it may break the ability for your friends to see the attachment. You can use the post permissions dialogue box or privacy hashtags to restrict the visibility of the file - which will be set to match the permissions of the post your are sending.
To delete attachments or change the permissions on the stored files, visit [observer.baseurl]/cloud/{{username}}" replacing {{username}} with the nickname you provided during channel creation.
[b]Web Access[/b]
Your files are visible on the web at the location "cloud/{{username}}" to anybody who is allowed to view them. If the viewer has sufficient privileges, they may also have the ability to create new files and folders/directories.
[b]WebDAV access[/b]
See: [zrl=[baseurl]/help/cloud_desktop_clients]Cloud Desktop Clients[/zrl]
[b]Permissions[/b]
When using WebDAV, the file is created with your channel's default file permissions and this cannot be changed from within the operating system. It also may not be as restrictive as you would like. What we've found is that the preferred method of making files private is to first create folders or directories; then visit "filestorage/{{username}}"; select the directory and change the permissions. Do this before you put anything into the directory. The directory permissions take precedence so you can then put files or other folders into that container and they will be protected from unwanted viewers by the directory permissions. It is common for folks to create a "personal" or "private" folder which is restricted to themselves. You can use this as a personal cloud to store anything from anywhere on the web or any computer and it is protected from others. You might also create folders for "family" and "friends" with permission granted to appropriate privacy groups.
#include doc/macros/main_footer.bb;
[b]Cloud Desktop Clients[/b]
[b]Windows Clients[/b]
[li][zrl=[baseurl]/help/dav_windows]Windows Internal Client[/zrl][/li]
[b]Linux Clients[/b]
[li][zrl=[baseurl]/help/dav_mount]Command Line as a Filesystem[/zrl][/li]
[li][zrl=[baseurl]/help/dav_dolphin]Dolphin[/zrl][/li]
[li][zrl=[baseurl]/help/dav_konqueror]Konqueror[/zrl][/li]
[li][zrl=[baseurl]/help/dav_nautilus]Nautilus[/zrl][/li]
[li][zrl=[baseurl]/help/dav_nemo]Nemo[/zrl][/li]
[b]Server Notes[/b]
Note: There have been reported issues with clients that use "chunked transfer encoding", which includes Apple iOS services, and also the "AnyClient" and "CyberDuck" tools. These work fine for downloads, but uploads often end up with files of zero size. This is caused by an incorrect implemention of chunked encoding in some current FCGI (fast-cgi) implementations. Apache running with PHP as a module does not have these issues, but when running under FCGI you may need to use alternative clients or use the web uploader. At the time of this writing the issue has been open and no updates provided for at least a year. If you encounter zero size files with other clients, please check the client notes; as there are occasional configuration issues which can also produce these symptoms.
#include doc/macros/cloud_footer.bb;
[b]Connecting To Channels[/b]
Connections in $Projectname can take on a great many different meanings. But let's keep it simple, you want to be friends with somebody like you are familiar with from social networking. How do you do it?
First, you need to find some channels to connect to. There are two primary ways of doing this. Firstly, setting the "Can send me their channel stream and posts" permission to "Anybody in this network" will bring posts from complete strangers to your matrix. This will give you a lot of public content and should hopefully help you find interesting, entertaing people, forums, and channels.
The next thing you can do is look at the Directory. The directory is available on every $Projectname website which means searching from your own site will bring in results from the entire network. You can search by name, interest, location and keyword. This is incomplete, so we'll improve this paragraph later.
To connect with other $Projectname channels:
Visit their profile by clicking their photograph in the directory, matrix, or comments, and it will open their channel home page in the channel viewer. At the left hand side of the screen, you will usually see a link called "connect". Click it, and you're done. Depending on the settings of the channel you are connecting to, you may need to wait for them to approve your connection, but no further action is needed on your part. Once you've initiated the connection, you will be taken to the connection editor. This allows you to assign specific permissions for this channel. If you don't allow any permissions, communication will be very limited. There are some quick links which you can use to avoid setting individual permissions. To provide a social network environment, "Full Sharing" is recommended. You may review the settings that are applied with the quick links to ensure they are suitable for the channel you are connecting with and adjust if necessary. Then scroll to the bottom of the page and click "Submit".
You may also connect with any channel by visiting the "Connections" page of your site or the Directory and typing their "webbie" into the "Add New Connection" field. Use this method if somebody tells you their webbie and you wish to connect with them. A webbie looks like an email address; for example "bob@example.com". The process is the same as connecting via the "Connect" button - you will then be taken to the connection editor to set permissions.
[b]Premium Channels[/b]
Some channels are designated "Premium Channels" and may require some action on your part before a connection can be established. The Connect button will for these channels will take you to a page which lists in detail what terms the channel owner has set. If the terms are accepted, the connection will then proceed normally. In some cases, such as with celebrities and world-reknowned publishers, this may involve payment. If you do not agree to the terms, the connection will not proceed, or it may proceed but with reduced permissions allowed on your interactions with that channel.
#include doc/macros/main_footer.bb;
# Connecting To Channels #
Connections in $Projectname can take on a great many different meanings. But let's keep it simple, you want to be friends with somebody like you are familiar with from social networking. How do you do it?
First, you need to find some channels to connect to. There are two primary ways of doing this. Firstly, setting the "Can send me their channel stream and posts" permission to "Anybody in this network" will bring posts from complete strangers to your matrix. This will give you a lot of public content and should hopefully help you find interesting, entertaing people, forums, and channels.
The next thing you can do is look at the Directory. The directory is available on every $Projectname website which means searching from your own site will bring in results from the entire network. You can search by name, interest, location and keyword. This is incomplete, so we'll improve this paragraph later.
To connect with other $Projectname channels:
Visit their profile by clicking their photograph in the directory, matrix, or comments, and it will open their channel home page in the channel viewer. At the left hand side of the screen, you will usually see a link called "connect". Click it, and you're done. Depending on the settings of the channel you are connecting to, you may need to wait for them to approve your connection, but no further action is needed on your part. Once you've initiated the connection, you will be taken to the connection editor. This allows you to assign specific permissions for this channel. If you don't allow any permissions, communication will be very limited. There are some quick links which you can use to avoid setting individual permissions. To provide a social network environment, "Full Sharing" is recommended. You may review the settings that are applied with the quick links to ensure they are suitable for the channel you are connecting with and adjust if necessary. Then scroll to the bottom of the page and click "Submit".
You may also connect with any channel by visiting the "Connections" page of your site or the Directory and typing their "webbie" into the "Add New Connection" field. Use this method if somebody tells you their webbie and you wish to connect with them. A webbie looks like an email address; for example "bob@example.com". The process is the same as connecting via the "Connect" button - you will then be taken to the connection editor to set permissions.
## Block/Ignore/Archive/Hide channels ##
Channels in your address book can have statuses such as *blocked*, *ignored*, *archived* and *hidden*. From your connections page you can see tabs that display the channels with those statuses. From your edit connection pages you can change the statuses of a channel.
Here's their meaning:
**Blocked:** the channel can't read your items regardless of permissions, nor can it write to your channel.
**Ignored:** the channel can read your items if it has permission, but can't write to your channel.
**Hidden:** the channel does not show up in your profile's connections list, noone can see you're connected, but beware they may still show up to your other connections, for example in post replies.
**Archived:** if a channel can't be reached for 30 days, it is automatically marked as archived. This keeps all the data but stops polling the channel for new information and removes it from autocomplete. If later you learn the channel has come back online, you may manually unarchive it.
## Premium Channels ##
Some channels are designated "Premium Channels" and **may** require some action on your part before a connection can be established. The Connect button will for these channels will take you to a page which lists in detail what terms the channel owner has set. If the terms are accepted, the connection will then proceed normally. In some cases, such as with celebrities and world-reknowned publishers, this **may** involve payment. If you do not agree to the terms, the connection will not proceed, or it may proceed but with reduced permissions allowed on your interactions with that channel.
#include doc/macros/main_footer.bb;
[b]Credits[/b]
Thanks to all who have helped and contributed to the project and its predecessors over the years. It is possible we missed in your name but this is unintentional. We also thank the community and its members for providing valuable input and without whom this entire effort would be meaningless.
It is also worth acknowledging the contributions and solutions to problems which arose from discussions amongst members and developers of other somewhat related and competing projects; even if we have had our occasional disagreements.
Mike Macgirvin
Fabio Comuni
Simon L'nu
marijus
Tobias Diekershoff
fabrixxm
tommy tomson
Simon
zottel
Christian Vogeley
Jeroen van Riet Paap (jeroenpraat)
Michael Vogel
erik
Zach Prezkuta
Paolo T
Michael Meer
Michael
Abinoam P. Marques Jr
Tobias Hößl
Alexander Kampmann
Olaf Conradi
Paolo Tacconi
tobiasd
Devlon Duthie
Zvi ben Yaakov (a.k.a rdc)
Alexandre Hannud Abdo
Olivier Migeot
Chris Case
Klaus Weidenbach
Michael Johnston
olivierm
Vasudev Kamath
pixelroot
Max Weller
duthied
Martin Schmitt
Sebastian Egbers
Erkan Yilmaz
sasiflo
Stefan Parviainen
Haakon Meland Eriksen
Oliver Hartmann (23n)
Erik Lundin
habeascodice
sirius
Charles
Tony Baldwin
Hauke Zuehl
Keith Fernie
Anne Walk
toclimb
Daniel Frank
Matthew Exon
Michal Supler
Tobias Luther
U-SOUND\mike
mrjive
nostupidzone
tonnerkiller
Antoine G
Christian Drechsler
Ludovic Grossard
RedmatrixCanada
Stanislav Lechev [0xAF]
aweiher
bufalo1973
dsp1986
felixgilles
ike
maase2
mycocham
ndurchx
pafcu
Simó Albert i Beltran
Manuel Reva
Manuel Jiménez Friaza
[b]Using The Cloud - Dolphin[/b]
Visit webdavs://example.com/dav where "example.com" is the URL of your hub.
When prompted for a username and password, enter your channel name (the first part of your webbie - no @ or domain name) and password for your normal account.
Note, if you are already logged in to the web interface via Konqueror, you will not be prompted for further authentication.
#include doc/macros/cloud_footer.bb;
[b]Using The Cloud - Konqueror[/b]
Simply visit webdavs://example.com/dav after logging in to your hub, where "example.com" is the URL of your hub.
No further authentication is required if you are logged in to your hub in the normal manner.
Additionally, if one has authenticated at a different hub during their normal browser session, your identity will be passed to the cloud for these hubs too - meaning you can access any private files on any server, as long as you have permissions to see them, as long as you have visited that site earlier in your session.
This functionality is normally restricted to the web interface, and is not available to any desktop software other than KDE.
#include doc/macros/cloud_footer.bb;
[b]Mounting As A Filesystem[/b]
To install your cloud directory as a filesystem, you first need davfs2 installed. 99% of the time, this will be included in your distributions repositories. In Debian
[code]apt-get install davfs2[/code]
If you want to let normal users mount the filesystem
[code] dpkg-reconfigure davfs2[/code]
and select "yes" at the prompt.
Now you need to add any user you want to be able to mount dav to the davfs2 group
[code]usermod -aG davfs2 <DesktopUser>[/code]
[b]Note:[/b] on some systems the user group may be different, i.e. - "network"
on Arch Linux. If in doubt, check the davfs documentation for your
particular OS.
Edit /etc/fstab
[code]nano /etc/fstab[/code]
to include your cloud directory by adding
[code]
[baseurl]/dav/ /mount/point davfs user,noauto,uid=<DesktopUser>,file_mode=600,dir_mode=700 0 1
[/code]
Where [baseurl] is the URL of your hub, /mount/point is the location you want to mount the cloud, and <DesktopUser> is the user you log in to one your computer. Note that if you are mounting as a normal user (not root) the mount point must be in your home directory.
For example, if I wanted to mount my cloud to a directory called 'cloud' in my home directory, and my username was bob, my fstab would be
[code][baseurl]/dav/ /home/bob/cloud davfs user,noauto,uid=bob,file_mode=600,dir_mode=700 0 1[/code]
Now, create the mount point.
[code]mkdir /home/bob/cloud[/code]
and also create a directory file to store your credentials
[code]mkdir /home/bob/.davfs2[/code]
Create a file called 'secrets'
[code]nano /home/bob/.davfs2/secrets[/code]
and add your cloud login credentials
[code]
[baseurl]/dav <username> <password>
[/code]
Where <username> and <password> are the username and password [i]for your hub[/i].
Don't let this file be writeable by anyone who doesn't need it with
[code]chmod 600 /home/bob/.davfs2/secrets[/code]
Finally, mount the drive.
[code]mount [baseurl]/dav[/code]
You can now find your cloud at /home/bob/cloud and use it as though it were part of your local filesystem - even if the applications you are using have no dav support themselves.
[b]Troubleshooting[/b]
With some webservers and certain configurations, you may find davfs2 creating files with 0 bytes file size where other clients work just fine. This is generally caused by cache and locks. If you are affected by this issue, you need to edit your davfs2 configuration.
[code]nano /etc/davfs2/davfs2.conf[/code]
Your distribution will provide a sample configuration, and this file should already exist, however, most of it will be commented out with a # at the beginning of the line.
First step is to remove locks.
Edit the use_locks line so it reads [code]use_locks 0[/code].
Unmount your file system, remount your file system, and try copying over a file from the command line. Note you should copy a new file, and not overwrite an old one for this test. Leave it a minute or two then do [code]ls -l -h[/code] and check the file size of your new file is still greater than 0 bytes. If it is, stop there, and do nothing else.
If that still doesn't work, disable the cache. Note that this has a performance impact so should only be done if disabling locks didn't solve your problem. Edit the cache_size and set it to [code]cache_size 0[/code] and also set file_refresh to [code]file_refresh 0[/code]. Unmount your filesystem, remount your file system, and test it again.
If it [i]still[/i] doesn't work, there is one more thing you can try. (This one is caused by a bug in older versions of dav2fs itself, so updating to a new version may also help). Enable weak etag dropping by setting [code]drop_weak_etags 1[/code]. Unmount and remount your filesystem to apply the changes.
[b]Using The Cloud - Nautilus[/b]
1. Open a File browsing window (that's Nautilus)
2. Select File > Connect to server from the menu
3. Type davs://<domain_name>/dav/<your_channelname> and click Connect
4. You will be prompted for your channel name (same as above) and password
5. Your personal DAV directory will be shown in the window
#include doc/macros/cloud_footer.bb;
[b]Using The Cloud - Nemo[/b]
For (file browser) Nemo 1.8.2 under Linux Mint 15, Cinnamon 1.8.8. Nemo ist the standard file browser there.
1st way
type "davs://<domain_name>/dav/<your_channelname>" in the address bar.
2nd way
Menu > file > connect to server
Fill the dialog
- Server: hubzilla_domain_name
- Type: Secure WebDAV (https)
- Folder: /dav
- Username: yourchannelname
- Password: yourpassword
Once open you can set a bookmark.
#include doc/macros/cloud_footer.bb;
[b]Using The Cloud - Windows Internal Client[/b]
RedDav using Windows 7 graphical user interface wizard:
1. Left-click the Start-button to open the start menu.
2. Right-click the My computer icon to access its menu.
3. Left-click Map network drive... to open the connection dialog wizard.
4. Type #^[url=https://example.net/dav/your_channel_name]https://example.net/dav/your_channel_name[/url] in the textbox and click the Complete button where "example.net" is the URL of your hub.
5. Type your Hubzilla account's user name. IMPORTANT - NO at-sign or domain name.
6. Type your Hubzilla password
#include doc/macros/cloud_footer.bb;
[size=large][b]$Projectname FAQ[/b][/size]
[toc]
[h3]I am able to edit a post's text after I saved it, but is there a way to change the permissions?[/h3]
Short anser: No, there isn't. There are reasons. You are able to change permissons to your files, photos and the likes, but not to posts after you have saved them. The main reason is: Once you have saved a post it is being distributed either to the public channel and from there to other $Projectname servers or to those you intended it to go. Just like you cannot reclaim something you gave to another person, you cannot change permissions to $Projectname posts. We would need to track everywhere your posting goes, keep track of everyone you allowed to see it and then keep track of from whom to delete it.
If a posting is public this is even harder, as $Projectname is a global network and there is no way to follow a post, let alone reclaim it reliably. Other networks that may receive your post have no reliable way to delete or reclaim the post.
[h3]I downloaded my channel and imported it (cloned my identity) to another site but there is no content, no posts, no photos. What is wrong???[/h3]
Posts and photos/files are provided separately from the channel basic information. This is due to memory limitations dealing with years of conversations and photo archives. Posts and conversations can be synced separately from the basic channel information. Photos and file archives can be transferred using a plugin tool such as 'redfiles', which is currently listed as "experimental". When creating this feature we thought that keeping all your contacts was the most important task. Your friends have already seen your old content. Posts/conversations were next in priority and these may now be synced. Files and photos are the last bit to get completely working. Once we find someone willing to finish implementing this, it will be done. :)
[h3]I can't see private resources[/h3]
You have probably disabled third party cookies. You need to enable them for remote authentication to work.
[h3]There are a lot of foreign language posts. Let's auto-translate them.[/h3]
There are also a lot of [b]private[/b] foreign language posts and auto-translation services would require us to transmit these private messages to the translation service; and we don't know what they will do with them on their servers. Actually we do know thanks to Edward Snowden. Our best bet is a project called [b][i]Apertium[/i][/b] which is an open source translator we can install locally. It is currently missing German translations - which are the most requested translation in the matrix. Once again, this will be implemented when we find somebody who really wants to make it happen.
#include doc/macros/main_footer.bb;
This diff is collapsed.
#include install/INSTALL.txt;
#include doc/macros/main_footer.bb;
......@@ -471,6 +471,265 @@ Content of [code]block.json[/code]:
}
[/code]
[h3]Comanche Page Description Language[/h3]
Comanche is a markup language similar to [url=[baseurl]/help/member/bbcode]BBcode[/url] with which to create elaborate and complex web pages by assembling them from a series of components - some of which are pre-built and others which can be defined on the fly. Comanche uses a Page Decription Language to create these pages.
Comanche primarily chooses what content will appear in various regions of the page. The various regions have names and these names can change depending on what layout template you choose.
[h4]Page Templates[/h4]
Currently there are five layout templates, unless your site provides additional layouts.
[dl terms="b"]
[*= default]
The default template defines a "nav" region across the top, "aside" as a fixed width sidebar,
"content" for the main content region, and "footer" for a page footer.
[*= full]
The full template defines the same as the default template with the exception that there is no "aside" region.
[*= choklet]
The choklet template provides a number of fluid layout styles which can be specified by flavour:
[list]
[*] (default flavour) - a two column layout similar to the "default" template, but more fluid
[*] bannertwo - a two column layout with a banner region, compatible with the "default" template on small displays
[*] three - three column layout (adds a "right_aside" region to the default template)
[*] edgestwo - two column layout with fixed side margins
[*] edgesthree - three column layout with fixed side margins
[*] full - three column layout with fixed side margins and adds a "header" region beneath the navigation bar
[/list]
[*= redable]
A template for reading longer texts full screen (so without navigation bar). Three columns: aside, content and right_aside.
For maximum readability it is advised to only use the middle content column.
[*= zen]
Gives you the freedom to do everything yourself. Just a blank page with a content region.
[/dl]
To choose a layout template, use the 'template' tag.
[code]
[template]full[/template]
[/code]
To choose the "choklet" template with the "three" flavour:
[code]
[template=three]choklet[/template]
[/code]
The default template will be used if no other template is specified. The template can use any names it desires for content regions. You will be using 'region' tags to decide what content to place in the respective regions.
Three "macros" have been defined for your use.
[code]
$htmlhead - replaced with the site head content.
$nav - replaced with the site navigation bar content.
$content - replaced with the main page content.
[/code]
By default, $nav is placed in the "nav" page region and $content is placed in the "content" region. You only need to use these macros if you wish to re-arrange where these items appear, either to change the order or to move them to other regions.
To select a theme for your page, use the 'theme' tag.
[code]
[theme]suckerberg[/theme]
[/code]
This will select the theme named "suckerberg". By default your channel's preferred theme will be used.
[code]
[theme=passion]suckerberg[/theme]
[/code]
This will select the theme named "suckerberg" and select the "passion" schema (theme variant). Alternatively it may be possible to use a condensed theme notation for this.
[code]
[theme]suckerberg:passion[/theme]
[/code]
The condensed notation isn't part of Comanche itself but is recognised by $Projectname platform as a theme specifier.
[h4]Regions[/h4]
Each region has a name, as noted above. You will specify the region of interest using a 'region' tag, which includes the name. Any content you wish placed in this region should be placed between the opening region tag and the closing tag.
[code]
[region=htmlhead]....content goes here....[/region]
[region=aside]....content goes here....[/region]
[region=nav]....content goes here....[/region]
[region=content]....content goes here....[/region]
[/code]
[h4]CSS and Javascript[/h4]
We have the possibility to include javascript and css libraries in the htmlhead region. At present we make use of jquery (js), bootstrap (css/js) and foundation (css/js).
This will overwrite the selected themes htmlhead.
[code]
[region=htmlhead]
[css]bootstrap[/css]
[js]jquery[/js]
[js]bootstrap[/js]
[/region]
[/code]
[h4]Menus and Blocks[/h4]
Your webpage creation tools allow you to create menus and blocks, in addition to page content. These provide a chunk of existing content to be placed in whatever regions and whatever order you specify. Each of these has a name which you define when the menu or block is created.
[code]
[menu]mymenu[/menu]
[/code]
This places the menu called "mymenu" at this location on the page, which must be inside a region.
[code]
[menu=horizontal]mymenu[/menu]
[/code]
This places the menu called "mymenu" at this location on the page, which must be inside a region. Additionally it applies the "horizontal" class to the menu. "horizontal" is defined in the redbasic theme. It may or may not be available in other themes.
[code]
[menu][var=wrap]none[/var]mymenu[/menu]
[/code]
The variable [var=wrap]none[/var] in a block removes the wrapping div element from the menu.
[code]
[block]contributors[/block]
[/code]
This places a block named "contributors" in this region.
[code]
[block=someclass]contributors[/block]
[/code]
This places a block named "contributors" in this region. Additionally it applies the "someclass" class to the block. This replaces the default block classes "bblock widget".
[code]
[block][var=wrap]none[/var]contributors[/block]
[/code]
The variable [var=wrap]none[/var] in a block removes the wrapping div element from the block.
[h4]Widgets[/h4]
Widgets are executable apps provided by the system which you can place on your page. Some widgets take arguments which allows you to tailor the widget to your purpose. (TODO: list available widgets and arguments). The base system provides
[code]
profile - widget which duplicates the profile sidebar of your channel page. This widget takes no arguments
tagcloud - provides a tag cloud of categories
count - maximum number of category tags to list
[/code]
Widgets and arguments are specified with the 'widget' and 'var' tags.
[code]
[widget=recent_visitors][var=count]24[/var][/widget]
[/code]
This loads the "recent_visitors" widget and supplies it with the argument "count" set to "24".
[h4]Comments[/h4]
The 'comment' tag is used to delimit comments. These comments will not appear on the rendered page.
[code]
[comment]This is a comment[/comment]
[/code]
[h4]Conditional Execution[/h4]
You can use an 'if' construct to make decisions. These are currently based on system configuration variable or the current observer.
[code]
[if $config.system.foo]
... the configuration variable system.foo evaluates to 'true'.
[else]
... the configuration variable system.foo evaluates to 'false'.
[/if]
[if $observer]
... this content will only be show to authenticated viewers
[/if]
[/code]
The 'else' clause is optional.
Several tests are supported besides boolean evaluation.
[code]
[if $config.system.foo == bar]
... the configuration variable system.foo is equal to the string 'bar'
[/if]
[if $config.system.foo != bar]
... the configuration variable system.foo is not equal to the string 'bar'
[/if]
[if $config.system.foo {} bar ]
... the configuration variable system.foo is a simple array containing a value 'bar'
[/if]
[if $config.system.foo {*} bar]
... the configuration variable system.foo is a simple array containing a key named 'bar'
[/if]
[/code]
[h4]Complex Example[/h4]
[code]
[comment]use an existing page template which provides a banner region plus 3 columns beneath it[/comment]
[template]3-column-with-header[/template]
[comment]Use the "darknight" theme[/comment]
[theme]darkknight[/theme]
[comment]Use the existing site navigation menu[/comment]
[region=nav]$nav[/region]
[region=side]
[comment]Use my chosen menu and a couple of widgets[/comment]
[menu]myfavouritemenu[/menu]
[widget=recent_visitors]
[var=count]24[/var]
[var=names_only]1[/var]
[/widget]