Chapter 14. Module Components

14.1. Configuration File - module.ini
14.2. Integrating Modules (Publish/Subscribe)
14.3. Controlling Access with ACLs and Asserts
14.4. Controllers
14.5. Filters
14.6. Forms
14.7. Layouts
14.8. Models
14.9. Resources
14.10. Tests
14.11. Validators
14.12. Views
14.13. Workflows

14.1. Configuration File - module.ini

The configuration file, module.ini, identifies the module to Perforce Chronicle and specifies its initial configuration. The following example shows the contents of a typical configuration file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
; Perforce Module
 
version          = 1.0
description      = A description of the module.
icon             = icon.png
tags             = comma-separated, free-form, tags, describing, module, attributes
enabledByDefault = true
 
[maintainer]
name        = Maintainer Name
email       = "maintainer@email.address"
url         = http://www.maintainer.site
 
[dependencies]
module.Foo      = "1.*"
library.Zend    = "1.10.*"
 
[stylesheets]
all.href        = reset.css
screen.media    = screen
screen.href[]   = layout.css
screen.href[]   = layout.css
print.media     = print
print.href      = print.css
 
[scripts]
javascript[] = common.js

The following sections provide details about the contents of the configuration file. Note that all fields are optional.

Table 14.1. Module Configuration Elements

Element Description
version The revision of the module.
description Describes the general characteristics of the module, for example, special features or intended use.
tags Descriptive terms used for ad-hoc categorization of modules.
icon A graphic for the module, specified using a URL relative to an image file in the module's folder. The suggested size is 128x128 pixels. The icon is displayed in the list of modules on the Manage Modules page.
enabledByDefault When creating a web site, enable the module by default.
[maintainer] The name, email, and web site of the person who maintains the module.
[dependencies] Lists other modules and libraries that this module requires. The format of this list is:
1
module.<module-name> = <suitable-versions>
Or:
1
library.<library-name> = <suitable-versions>
For example:
1
2
3
4
[dependencies]
module.SomeModule  = "*"
module.OtherModule = "1.5, 1.6, 2.*"
library.Zend       = "1.10.*"
If version does not matter, specify "*". If there are several suitable versions, specify them as a comma-separated list. You can also use wildcards (such as "*" and "?") to match versions, as shown in the preceding example.
[stylesheets] Defines the CSS stylesheets that must be included during HTML generation. Specify the stylesheet paths relative to the module's resources folder. The media may be specified as all, screen or print; additionally conditions can be appended as dash separated values following the media type:
1
2
3
4
5
6
7
8
9
[stylesheets]
all.href[]       = file1.css
all.href[]       = file2.css
lt-ie8.href      = ie-rules.css
lt-ie8.condition = lt IE 8
screen.media     = screen
screen.href      = screen.css
print.media      = print
print.href       = print.css
[scripts] A list of client-side script files to include on every page. Group scripts by programming language (for example, javascript, vbscript). Specify scripts using an URL that is relative to the module's resources folder, or use an absolute URL.
[dojo] Lists Dojo modules that are provided by the module. For example:
1
2
3
4
5
6
[dojo]
base.namespace              = dojo.foo.base
base.path                   = dojo/foo/base
full.namespace              = dojo.foo
full.path                   = dojo/foo
full.acl.users              = add
The example declares that the module provides the dojo.foo.base Dojo module, in the dojo/foo folder with the name base (the .js JavaScript extension is automatically appended). The example also declares that the module provides the dojo.foo Dojo module to users that have the add privilege for the users resource.
[configure] Specifies that the module is configurable and specifies the module/controller/action route parameters to use to configure the module. For example:
1
2
3
4
[configure]
module      = example
controller  = configure
action      = index
You must specify the controller, but module and action are optional. module defaults to the module that is being described and action defaults to the index action. You can specify additional parameters, which are incorporated into the assembled URI.
[routes] Provide custom routing rules for the module. For example:
1
2
3
4
5
6
7
[routes]
route1.type                    = Zend_Controller_Router_Route_Static
route1.route                   = static-page-one
route1.defaults.module         = content
route1.defaults.controller     = index
route1.defaults.action         = view
route1.defaults.id             = 1
[menus] Defines default menus and the items that they contain. For example:
1
2
3
[menus]
some-menu.someEntry.label    = a test link
some-menu.someEntry.uri      = "http://example.com"
[types] Defines content types, which control the structure of content entries. For example:
1
2
3
4
5
6
7
8
9
10
11
12
[types]
basic-page.label                            = Basic Page
basic-page.group                            = Pages
basic-page.iconFile                         = images/icon-page.png
basic-page.elements.title.type              = text
basic-page.elements.title.options.label     = Title
basic-page.elements.title.options.required  = true
basic-page.elements.title.display.tagName   = h1
basic-page.elements.title.display.filters[] = HtmlSpecialChars
basic-page.elements.body.type               = editor
basic-page.elements.body.options.label      = Body
basic-page.elements.body.display.filters[]  = DefaultStripTags
The format of this section is: 
<type>.<property> = <value>
Or: 
<type>.elements.<element>.<property> = <value>
Valid values for settings in this region are as follows:
  • label: name of the content type.
  • group: the category that the content type belongs to.
  • iconFile: (optional) an icon representing the content type, specified as a URL relative to the module's folder.
  • elements: list of elements that compose the content type. Each element can have multiple properties. For details, see Section 4.6, “Specifying Content Type Elements”.
[widgets] Declares widget types provided by the module. Widgets are configurable action controllers. To add a widget type, you must specify the controller. Be sure to provide a label and description. Optionally, you can specify an icon and default options for the widget configuration. For example:
1
2
3
4
5
6
[widgets]
clock.label             = Clock Widget
clock.description       = A widget that displays the current time.
clock.icon              = clock-widget.png
clock.controller        = clock-widget
clock.defaults.format   = 12h
[acl] Declares resources, privileges and default "allow" rules that are relevant to the module. For example:
1
2
3
4
5
6
7
8
[acl]
users.label                             = Users
users.privileges.add.label              = Add Users
users.privileges.add.allow              = member, administrator
 
users.privileges.permissions.label      = Manage Permissions
users.privileges.permissions.allow      = administrator
users.privileges.permissions.needsSuper = true
The needsSuper option specifies that only Perforce superusers can have this privilege.
[workflows] Declares workflows, the content types affected, the states content should be guided through. Each state can include declarations for available transitions, conditions, and actions. For example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[workflows]
example.label                                                   = Example Workflow
example.types[]                                                 = basic-page
example.states.draft.label                                      = Draft
example.states.draft.transitions.review.label                   = Promote to Review
example.states.draft.transitions.review.actions.email.action    = SendEmail
example.states.draft.transitions.review.actions.email.toRole    = reviewers
example.states.draft.transitions.published.label                = Publish
 
example.states.review.label                                     = Review
example.states.review.transitions.draft.label                   = Demote to Draft
example.states.review.transitions.published.label               = Publish
example.states.review.transitions.published.conditions[]        = IsCategorized
 
example.states.published.label                                  = Published
example.states.published.transitions.review.label               = Demote to Review
example.states.published.transitions.draft.label                = Demote to Draft
See Section 5.6, “Specifying Workflows” for more details, but please note that defining workflows in module.ini requires the workflow identifier and 'states', as demonstrated above.

| Perforce Chronicle Reference Guide > Developer Guide > Module Components
Perforce Chronicle - Release: 2012.2/486814