From 35c465d4b7459b4cce40f50c53515b9061b484cd Mon Sep 17 00:00:00 2001 From: Thomas Willingham Date: Thu, 21 Nov 2013 19:41:09 +0000 Subject: Document schemas --- doc/Schema-development.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 doc/Schema-development.md (limited to 'doc/Schema-development.md') diff --git a/doc/Schema-development.md b/doc/Schema-development.md new file mode 100644 index 000000000..f3e6b97f4 --- /dev/null +++ b/doc/Schema-development.md @@ -0,0 +1,79 @@ +Red development - a guide to the schema system +============================================== + + +A schema, in a nutshell, is a collection of settings for a bunch of variables to define +certain elements of a theme. A schema is loaded as though it were part of config.php +and has access to all the same information. Importantly, this means it is identity aware, +and can be used to do some interesting things. One could, for example, restrict options +by service class, or present different options to different users. + +By default, we filter only by whether or not expert mode is enabled. If expert mode is +enabled, all options are presented to the user. If it is not, only scheme, background +image, font face, and iconset are available as choices. + +A schema is loaded *after* the user settings. Therefore, to allow a user to overwrite a +particular aspect of a schmea you would use the following syntax: + + if (! $foo) + $foo = 'bar'; + +However, there are circumstances - particularly with positional elements - where it +may be desirable (or necessary) to override a users settings. In this case, the syntax +is even simpler: + + $foo = 'bar'; + +Users will not thank you for this, however, so only use it when it is required. + +If no user options are set, and no schema is selected, we will first try to load a schema +with the file name "default.php". This file should never be included with a theme. If it +is, merge conflicts will occur as people update their code. Rather, this should be defined +by administrators on a site by site basis. + +The canonical default schema is darkness.php. Any bugs should be tested with this schema +first, in order to determine whether we're dealing with a theme bug or a schema bug. + +You schema does not need to - and should not - contain all of these values. Only the values +that differ from the defaults should be listed. This gives you some very powerful options +with very few lines of code. + +Note the options available differ with each theme. The options available with the Redbasic +theme are as follows: + +* nav_colour + The colour of the navigation bar. Options are red, black and silver. Alternatively, + one can set $nav_bg_1, $nav_bg_2, $nav_bg_3 and $nav_bg_4 to provide gradient and + hover effects. +* banner_colour + The font colour of the banner element. Accepts an RGB or Hex value. +* bgcolour + Set the body background colour. Accepts an RGB or Hex value. +* background_image + Sets a background image. Accepts a URL or path. +* item_colour + Set the background colour of items. Accepts an RGB or Hex value. +* item_opacity + Set the opacity of items. Accepts a value from 0.01 to 1 +* toolicon_colour + Set the colour of tool icons. Accepts an RGB or Hex value. +* toolicon_activecolour + Set the colour of active or hovered icon tools. +* font_size + Set the size of fonts in items and posts. Accepts px or em. +* body_font_size + Sets the size of fonts at the body level. Accepts px or em. +* font_colour + Sets the font colour. Accepts an RGB or Hex value. +* radius + Set the radius of corners. Accepts a numeral, and is always in px. +* shadow + Set the size of shadows shown with inline images. Accepts a numerical + value. Note shadows are not applied to smileys. +* converse_width + Set the maximum width of conversations. Accepts px, or %. +* nav_min_opacity +* top_photo +* reply_photo +* sloppy_photos + Determins whether photos are "sloppy" or aligned. Set or unset (1 or '') -- cgit v1.2.3 From b170d8047153a9c9f0f0f16d39e0ecb45d17b0b6 Mon Sep 17 00:00:00 2001 From: Thomas Willingham Date: Thu, 21 Nov 2013 19:42:04 +0000 Subject: Remove telltale signs the doco was mostly stolen from APW --- doc/Schema-development.md | 3 --- 1 file changed, 3 deletions(-) (limited to 'doc/Schema-development.md') diff --git a/doc/Schema-development.md b/doc/Schema-development.md index f3e6b97f4..415c68efa 100644 --- a/doc/Schema-development.md +++ b/doc/Schema-development.md @@ -31,9 +31,6 @@ with the file name "default.php". This file should never be included with a the is, merge conflicts will occur as people update their code. Rather, this should be defined by administrators on a site by site basis. -The canonical default schema is darkness.php. Any bugs should be tested with this schema -first, in order to determine whether we're dealing with a theme bug or a schema bug. - You schema does not need to - and should not - contain all of these values. Only the values that differ from the defaults should be listed. This gives you some very powerful options with very few lines of code. -- cgit v1.2.3 From f896819c781807612318ad389ea5fe655926cc2a Mon Sep 17 00:00:00 2001 From: friendica Date: Thu, 21 Nov 2013 14:51:12 -0800 Subject: There was one small typo - and I'm trying with great difficulty not to use the word "user" to refer to site members - especially in public documentation. In dev forums is another matter. It does exist in function names and the string "username" isn't considered derogatory, but most other times it's considered derogatory to site members. Channel is often another acceptable replacement. --- doc/Schema-development.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'doc/Schema-development.md') diff --git a/doc/Schema-development.md b/doc/Schema-development.md index 415c68efa..481792fcc 100644 --- a/doc/Schema-development.md +++ b/doc/Schema-development.md @@ -6,27 +6,27 @@ A schema, in a nutshell, is a collection of settings for a bunch of variables to certain elements of a theme. A schema is loaded as though it were part of config.php and has access to all the same information. Importantly, this means it is identity aware, and can be used to do some interesting things. One could, for example, restrict options -by service class, or present different options to different users. +by service class, or present different options to different members. By default, we filter only by whether or not expert mode is enabled. If expert mode is -enabled, all options are presented to the user. If it is not, only scheme, background +enabled, all options are presented to the member. If it is not, only scheme, background image, font face, and iconset are available as choices. -A schema is loaded *after* the user settings. Therefore, to allow a user to overwrite a -particular aspect of a schmea you would use the following syntax: +A schema is loaded *after* the member's personal settings. Therefore, to allow a member +to overwrite a particular aspect of a schema you would use the following syntax: if (! $foo) $foo = 'bar'; However, there are circumstances - particularly with positional elements - where it -may be desirable (or necessary) to override a users settings. In this case, the syntax +may be desirable (or necessary) to override a member's settings. In this case, the syntax is even simpler: $foo = 'bar'; -Users will not thank you for this, however, so only use it when it is required. +Members will not thank you for this, however, so only use it when it is required. -If no user options are set, and no schema is selected, we will first try to load a schema +If no personal options are set, and no schema is selected, we will first try to load a schema with the file name "default.php". This file should never be included with a theme. If it is, merge conflicts will occur as people update their code. Rather, this should be defined by administrators on a site by site basis. -- cgit v1.2.3