Location: PHPKode > scripts > Lightweight Club Calendar > lc-calendar-0.9.4/documentation/customize.txt
+-------------------+
| LCC customization |
+-------------------+

Contents:
---------
I.      Quick introduction
II.     LCC Design customization
II. a)  LCC Actions
III.    LCC Fields
IV.     LCC ACL


I. Quick introduction
---------------------
If you only want a different design, some other pics or colors, then the
simplest thing is to just customize the css file of your selected design.
LCC uses much CSS so you have much control over the design.
See below for more information on Designs.

If this isn't satisfying and you need more control over the design, just copy a suitable
design and start customizing that. After you finished, select it in the config.
If you think you made a great new design, feel free to contact me for inclusion into
the distribution!

If you want to connect a new application to LCC, feel free to introduce a new driver!
Or if you want to store new events in an other database - write a new driver!
Refer to howto_write_a_driver.txt for help on this.


II. LCC Design customization
----------------------------
In most cases, it will be suitable to just customize the 'default' design.
The best thing to start off is to copy the default design to some other directory, so
you end up with something like:
  designs/default
  designs/my_new_design
The designs provided by the LCC distribution may be overwritten on updates
so it's not safe to modify these files directly.

A Design is a set of SMARTY templates combined with a css definiton for the style.
All Designs are stored under the "designs" subfolder. Beneath this subfolder, each
design has its own subfolder named like the designs name:
The "default" design lives under "designs/default". All templates of this design are stored
inside this design folder.

The file names and contents are used by the core and must be present.
Of course you are free to add your own templates, but be sure that the
default ones are there, otherwise LCCs core will give a error message to you.
Beyond that you are free to implement own subfolders if neccessary.
Predefined links (like actions) and template variable names are fixed and assigned by the core.

If you plan to use pictures, be sure to use relative paths.

The minimum files that must be present are as follows.
(For template variables assigned to each template, see the documentation
headers of the templates of the "default" design.)

File                  Purpose
-------------------------------------------------------------------------------
message.tpl              Defines messages assigned by the core
calendar.tpl             Displays the calendar and its events
event_view.tpl           Displays the details of an event such as its fields,
                         modification times, participating users
event_editable.tpl       Editable view for an event
note_view.tpl            All notes for a specific event
note_editable.tpl        Editable view for a specific note
design.css               CSS definitions of your design


If you just want to change the look of the design, then it would be best if
you adjust the css-file of the default design to your needs. If you want to relocate
some of the elements or if you want to display additional fields from your
selected EventDriver (for example), then feel free to implement it inside the default design.

Smarty gives you much power to tune the applications behavior since you can react on variables
and even set your own ones. Have a look to the default templates to get knowledge
about what template variables LCC_Core assigns.

The LCC_Core object is available in the smarty variable "$LCC_CORE" in every template.
You can (and should!) use "$LCC_CORE->checkRight()" to check the rights of the authenticated user.
This can be used to hide/display links depending of the privileges of that user.
Please be aware that hiding links is no guarantee that the specific action can't be triggered.
Set the ACL of LCC according to your needs to avoid having users doing stuff they shouldn't do.
Additionally, the LCC_View object is available in $LCC_VIEW.
To allow you to perform checks dependant on the username, you have the username of the authenticated
user available in the template variable $LCC_AUTHED_USER.
Through this objects, you have access to all public methods they provide, so you are 
for example able to assign the result of $LCC_CORE->getEventDriverInstance() - which gives you
access to the selected EventDriver!

You can use the following LCC-Smarty modifiers:
  toMonthString  Converts a integer into the string representation of the
                 month in the users selected language
  convertDate    Converts a UNIX timestamp into the date format of the language
  convertTime    Converts a UNIX timestamp into the time format of the language

As mentioned earlier, please use the "$LCC_CORE->checkRight()" to hide links the user could not use
anyway. If a user access such a link, LCC permission management will halt script execution which
may impose nasty side effects to integrating applications.


II. a) LCC Actions
LCC works with links to trigger actions. Following is a list of actions and their
parameters defined by the core. LCC actions are passed to lcc using the GET parameter
"lcc_action". Parameters are also just GET parameters appendet to the URL.
Offer actions and parameters with something like:
  <a href="{$smarty.server.SCRIPT_NAME}?lcc_action=foobaraction&lcc_param1=1234">.
In the following list, round brackets mean "optional".

Action                 Parameter        Parameter format      Purpose
-------------------------------------------------------------------------------------------------------
(show_calendar)        (lcc_month)      M or MM               The default action is to display the calendar view.
                       (lcc_year)       YYYY                  The month and year is optional, if not set or not
                                                              in a proper format, NOW is assumed.
                                                              Note that the default action can be configured.

edit_event             (lcc_id)         Number (event id)     This is used to show the editable view for
                                                              new/existing events. If "lcc_id" is ommited or not
                                                              existent in the backend, a new event will be created.
                                                              If "lcc_id" exists, the editable view will be loaded.

show_event             lcc_id          Number (event id)      This shows thed etail view of an event

show_notes             lcc_eventid     Number (event id)      Display all notes of an event

delete_event           lcc_id          Number (event id)      Delete a specific event

event_subscribe        lcc_id          Number (event id)      Subscribe yourself to an event
                       lcc_interest    'yes', 'no', 'unknown

event_subscribe_group  lcc_id          Number (event id)      Subscribe a whole group to an event
                       lcc_group       String (name of group)
                       lcc_interest    'yes', 'no', 'unknown

edit_note              lcc_id          Number (note id)       Shows the editable view to edit or add
                                                              a note to an event. If "lcc_id" is ommited
                                                              or not existent in the backend, a new note will
                                                              be created. If "lcc_id" exists, the editable view
                                                              will be loaded.

delete_note            lcc_id          Number (note id)       Delte a specific note.



III.  LCC Fields
----------------
LCC stores event and note data using socalled fields. These fields are written and read from events using
the EventDriver and for notes from the NoteDriver. Security settings are applied to fields that 
can be changed/enhanced through calling the "setFieldSecurity()" methods of the driver object.
There are two types of fields:
  - metadata fields managed and created internally by LCC
  - user definable fields
Only user definable fields can be changed.

If you want to store/display new fields in an event or note, you need to perform two tasks:
- You need to customize the design so you display the data and provide input fields
  for the data. (event_view.tpl, event_editable.tpl and maybe calendar.tpl
  if you want to include the field in the main calendar view)
  If you plan to just display a readonly-field, then it is suitable to only modify event_view.tpl.
- You need to make LCC know of the new field. This is achieved by calling the method
  addCustomField() of the loaded driver object.
  You can retrieve the driver object at loading time or by calling $lcc_core->get*DriverInstance()
  later on. Please refer to the class documentation for more information.
  Keep in mind, that you should set "readonly" fields to "disabled" in the design, because
  users would be maybe irritated otherwise.


The following user definable event fields are predefined in $_allowedFields of LCC_EventDriver:

Field                writable       html allowed     Format
-------------------------------------------------------------------------------
title                yes            no               Plaintext
description          yes            no               Plaintext
color                yes            no               Hex color (e.g "#f0f0f0")
start_date           yes            no               Compatible to strtotime()
end_date             yes            no               Compatible to strtotime()
start_time           yes            no               Compatible to strtotime()
end_time             yes            no               Compatible to strtotime()

Please note, that the date and time fields are used internally to calculate dates.

The following event meta fields are managed by LCC and accessible in templates
and EventDrivers storeData() / getAllData() methods:

Field                  Format
-------------------------------------------------------------------------------
id                     Depends on used EventDriver, but prefferably INT
author                 string
created                UNIX timestamp, this allows for easy conversion using smarty
last_modified          UNIX timestamp
last_modified_author   string
event_start            UNIX timestamp, combined from start_date and start_time
event_end              UNIX timestamp, combined from end_date and end_time


The following user definable note fields are predefined in $_allowedFields of LCC_NoteDriver:

Field                writable       html allowed     Format
-------------------------------------------------------------------------------
text                 yes            no               Plaintext


The following note meta fields are managed by LCC and accessible in templates
and NoteDrivers storeData() / getAllData() methods:

Field                  Format
-------------------------------------------------------------------------------
id                     Depends on used NoteDriver, but prefferably INT
event_id               Depends on EventDriver, but prefferably INT
author                 string
created                UNIX timestamp, this allows for easy conversion using smarty
last_modified          UNIX timestamp
last_modified_author   string


IV.  LCC ACL
------------
You can easily tune which users are allowed to perfom which tasks by customizing
the default access control list of LCC.
This is done by calling the setACL() method of the LCC_Core object.
A example on this can be found in lcc_standalone.php.
With the setACL() you override specific settings from the internal list, the parameters
of the setACL() method are as following:
setACL($action, $level, $groups)
  $action       string   The specific action you want to override
  $level        int      What level the user must at least have to perform $action
  $groups       array    In which groups the user must be part of to perform $action (no groups = empty array)

To be able to perform the action, the authenticated user must
have a higher level as $level AND must be a member of one of the specified groups.
This allows you to fine tune the persmissions.
If the action doesn't require group membership, pass a empty array. In this case only $level
will be evaluated.

For further details on the default ACL and what items are exaclty covered
see "configuring-lcc.txt".
Return current item: Lightweight Club Calendar