Pawtucket2

From CollectiveAccess Documentation
Jump to: navigation, search

Pawtucket2 is the latest version of Pawtucket and is currently under development. It is available for download on Github at https://github.com/collectiveaccess/pawtucket2/. The installation process is identical to the previous version and is detailed in Installing Pawtucket.

The default theme in Pawtucket2 uses Bootstrap, and creating a new theme for your project is slightly different than in previous versions.

Creating a new Theme

To create a new theme, navigate to the /themes folder of your Pawtucket installation. There you will find two folders, one named "default" and one named "copyme." The default theme contains all of the views and styles that populate the default theme. The copyme folder contains no views, but is comprised of a series of folders that mimic the structure of the default theme, as well as a blank theme.css file.

To create your theme, copy the "copyme" folder and its contents and name it whatever you wish. For this example, we'll assume it's called mytheme. Open the setup.php file in the root of your installation and locate the CA_THEMES_BY_DEVICE option. Replace "default" with your theme name, ie:

$_CA_THEMES_BY_DEVICE = array(
	'_default_' 	=> 'mytheme'		
);

Your theme is now enabled. In order to function properly, your theme will also need the information specified in detail.conf, search.conf and others. If you're not sure what you need to specify in these files, copy the contents of the themes/default/conf into your theme's conf folder (themes/mytheme/conf).

Editing a Theme

In Pawtucket2, your theme will contain all of your custom views and styles, and anything you do not customize will fall back to the files contained in the default theme. Almost all themes will utilize at least some areas of the default theme - this will make it easier for your theme to received updates as we make improvements to Pawtucket2. When you pull an update from git, the default theme will receive all of the necessary changes and your custom views and styles will remain unaffected.

When you wish to create a custom view for your theme, copy the file from the default theme into the corresponding folder in your theme. For example, to edit a link in your navigation bar, you would locate themes/default/views/pageFormat/pageHeader.php and copy the file into themes/mytheme/views/pageFormat/pageHeader.php. Your new file will override the one in the default theme and any changes you make will be reflected in your Pawtucket2 installation. Repeat this for each view you wish to edit in your new theme.

It is to your advantage to override as few views as is necessary to create your design. Copying the entire default theme as a shortcut is not recommended, as you will be prevented from receiving updates and bug fixes when you pull new code from git.

Assets

The assets folder (mytheme/assets/pawtucket) is new in Pawtucket2. By default, this will contain folders for your css files and custom graphics. If you plan to install custom fonts or javascript for your theme, this is the best place to store those folders as well.

Initially, your assets folder will only contain a blank css file (mytheme/assets/pawtucket/css/theme.css). This is where you should include any of the styles needed for your theme. Styles in this file will override any styles in the default theme, so repeat those styles in this file if you need to change their formatting.

Loading a new asset

If you want to load any additional stylesheets or javascript for your theme, you'll need to specify them in assets.conf (note that new graphics in your graphics folder are excluded from this requirement). For example, if you want to load a js file, you would create a new folder in your assets directory and upload it there. Let's say you've created mytheme/assets/pawtucket/js/slider.js. Your assets.conf file needs to be edited to reflect the new file in both themePackages and themLoadSets as follows:

themePackages = {
	# -----------------------
	pawtucket = {
		css = css/main.css:100, 
		fonts = css/fonts.css,
		fontAwesome = css/Font-Awesome/css/font-awesome.css,
		themecss = css/theme.css:200,
                myjs = js/slider.js
	}
	# -----------------------
}

themeLoadSets = {
	#
	# Libraries listed in "_default" are always loaded (whether or not they have been
	# registered in code to load), are loaded in the order listed and are always 
	# loaded first
	#
	_default = [
		pawtucket/css, pawtucket/fonts, pawtucket/fontAwesome, pawtucket/themecss, pawtucket/myjs
	]
}

Your new assets now loads with your theme.

Configuration Files

A handful of configuration files are needed to make your Pawtucket2 installation run smoothly.

  • app.conf - Contains global settings for your Pawtucket2 installation. Inherits many of its options from the root app/conf/app.conf file outside of your theme folder.
  • assets.conf - Loads your themes externals files such as stylesheets and custom fonts as outlined above.
  • browse.conf - Defines what metadata is browseable in the "browse" menu for each record type
  • contact.conf - Used to configure an optional contact form.
  • contribute.conf - Used to configure an optional user contribution form for croudsourced assets.
  • datetime.conf - Controls the display of various date formats.
  • detail.conf - Specifies what records in your system will have detail pages (dedicated views).
  • front.conf - Specifies what Set appears in the homepage slideshow and what caption information is displayed.
  • gallery.conf - Specifies what Sets appear in the optional "Featured Gallery" section.
  • global.conf - Provides options for globally used icons and other aesthetic options.
  • icons.conf - Defines icons to use as placeholder thumbnails when no media is present in detail pages and search results.
  • listing.conf - Configures optional "Listing" views that display all of a specified type of record on a single static page.
  • media_display.conf - Contains options for displaying media through the RepresentationViewer and Media overlay (zoom window).
  • search.conf - Defines what records are returned when as user conducts a search in the main search bar. May also contain search types for an optional Advanced Search, if used.
  • lightbox.conf - Defines views for the Lightbox and optional timeline view for Lightbox items.


Plugins

Pawtucket can be extended using plugins, code modules that encapsulate new functionality in reusable packages. Plugins can be installed at the application level (in app/plugins) or as part of a theme (in themes/[theme name]/plugins).

Plugins can extend Pawtucket in three ways:

  1. By implementing Pawtucket2-plugin-hooks – functions that are called by Pawtucket when certain events occur. The plugin is passed data by Pawtucket, performs whatever actions it needs to, and then returns the possibly modified data to Pawtucket. In this way plugin can, for example, modify search results before they are displayed.
  2. By adding their own controllers and views to Pawtucket. The standard Gallery plugin, for example, implements an optional online exhibitions interface using its own set of controllers, views and configuration files. Simply moving the plugin into the app/plugins directory and enabling it in the plugin configuration file enables Gallery functionality in Pawtucket .
  3. By implementing a tool interface to add batch processing functionality, accessible via the caUtils command-line utility.

i_sphinx

Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools