Documentation

This documentation is made available to those who wish to customize their installations of ComicControl.  ComicControl is built on a simple class-based PHP and MySQL architecture, which gives those with a knowledge of PHP access to useful functions and snippets that they can drop into their site's templates to deploy features such as page dropdowns, archives, tags, comments, and so on.  More advanced PHP developers can use this information to create their own functions based on ComicControl's architecture. If there's something in the documentation that you think needs clarifying, please let us know at feedback@comicctrl.com.

Please note that most of this information is meant mainly for developers, to serve as an index and bible to the code available for customization and development.  If you are not a developer but are looking to customize your ComicControl installation, please check out the customization section for more user-friendly tips.

Architecture

File structure

A basic ComicControl installation is made up of these files in the root directory of a ComicControl website:

comiccontrol/

This folder contains all the main ComicControl files that control what displays on the front end and control of the back end.  Logging in at yoursite.com/comiccontrol allows access to the back end. All the files in this folder are overwritten on update, so no modifications should be made to files here.  However, if you want to add extra languages to the back end or front end of ComicControl, language files can be placed in comiccontrol/languages /without being overwritten. Plugins can also be added to comiccontrol/plugin-files without being overwritten.  For more information on adding languages and plugins, please visit the customization page.

comics/, comicshighres/, comicsthumbs/, uploads/

These folders contain, respectively, the image files for the final comic image that will display on your site, the original image files uploaded to ComicControl, the resized thumbnail images for your comics, and any other images uploaded either to the image gallery or using the image uploader in the Summernote editor.  These folders are have .htaccess files that disallow indexing, which means that if a user visits yoursite.com/comics, for example, they will not see a list of the files in that folder.

lightbox/

This folder contains files used for displaying the lightbox that is used for showing gallery images.

templates/

This folder contains all template files used in displaying the front end of your site.  A basic template is included with ComicControl, but extra templates can be added by uploading template files into this folder.  For more information on templates, please visit the customization page.

index.php

This file controls the main program routing for the front end of ComicControl.

robots.txt

This file ensures that search engines will not look in the comiccontrol/ folder; if this is removed, your site's back end login may be indexed in sites such as Google and Bing.  

.htaccess

This file controls the URL routing for the front end of ComicControl.  This file is automatically written during ComicControl installation and it is overwritten by certain functions in the ComicControl backend, so if special .htaccess rules must be added to your site, please add them in your site's site options.  Please see the site options page in the support section for more information.

Class structure

ComicControl structures its elements using a few PHP classes, all of which can be found in comiccontrol/includes/classes.php.  For more information about what information is stored by objects using these classes and what functions child objects created with these classes have access to, please read the classes and functions section.

Database structure

ComicControl uses a utf-8 encoded MySQL database in order to store all the information needed to generate the website and backend.  For information on the tables used and what data is contained in them, please read the database section.

Classes & Functions

Below are the main classes that ComicControl uses.  Note: this information is in-depth and will generally only be useful for developers. For more accessible information on functions you can use to place site components, please check out the customization page.

CC_Site

This class keeps track of basic site information, such as the site title, time zone, disqus forum, ComicControl version, and URL.  These are the basic variables and functions the class contains.

public $timezone

This variable stores the time zone the site will be presented in.  This variable uses the PHP time zone format. For a list of all time zones, please see the PHP manual.

public $sitetitle

This is the title of your ComicControl site.

public $commentuser

This is the Disqus shortname or forum name your site will use for displaying Disqus comments. For example, if your site's Disqus forum is at your-site.disqus.com, then this variable would hold the information "your-site".

public $root

This is the root URL that ComicControl will use to display pages.  This would include the domain and subdomain if applicable, as well as the protocol (http or https).  For example, if your site is at http://your-comic.your-site.com/comic-folder/, then this variable would hold the information "http://your-comic.your-site.com/".

public $relativepath

This is the subfolder that your ComicControl site is located in.  This will usually be blank unless you are installing ComicControl in a subfolder of your website.  This must include a trailing slash if you are using a subfolder. For example, if your site is at http://your-comic.your-site.com/comic-folder/, then this variable would hold the information "comic-folder/".  If your site was at http://your-comic.your-site.com/, then this variable would be blank.

public $ccroot

This variable contains the subfolder that the main ComicControl files in.  For most sites, this will simply be "comiccontrol/". However, if you rename the folder that these files are in, this variable will be different.

public $dateformat

This variable contains the format string used to display dates on your website wherever a comic or blog post's publication time is displayed.  This uses PHP date format. For more information, please refer to the PHP manual.

public $timeformat

This variable contains the format string used to display times on your website wherever a comic or blog post's publication time is displayed.  This uses PHP time format. For more information, please refer to the PHP manual.

public $version

This variable contains the current number version of ComicControl on your site. This is used to check for updates so it is not recommended to change it.

public $language

This variable contains the language for the ComicControl installation.  Though individual modules can have different languages set for their display, this variable controls the language that the administration section of ComicControl is displayed in.

public $jquery

This variable contains the URL for the jQuery CDN currently in use by ComicControl.  

public $hammerjs

This variable contains the URL for the Hammer.js CDN currently in use by ComicControl.

public $description

This is the default text that will be outputted in the "description" meta tag for pages on your ComicControl website.  This can be overridden in each individual module's options; this information will only be used as the description on modules that do not have description information set.

public $updatechecked

This is a variable that tracks the last time ComicControl checked the main ComicControl repository for updates.  ComicControl attempts to check the repository at least once every 24 hours and uses this unix timestamp to track that.

public $newestversion

This variable tracks the newest available version of ComicControl available according to the main repository.

public function __construct()

This function is the class constructor.  The constructor uses this class's fetchoption() function in order to assign each of its class variables according to the options contained in the MySQL database.

private function fetchoption($option)

This function fetches a site option's value from the database.

private function setProtocol($url)

This function is used in order to determine whether the page is currently being requested as an HTTP or HTTPS page.  This is used to format links and resources within the ComicControl page to use the corresponding protocol.

CC_User

This class keeps track of user information for those logged into ComicControl.

public $id

The ID of the user in the database.

public $username

The user's username.

public $loginhash

The hash kept in the user's cookies used to verify their login.  Changes with every page load.

public $authlevel

The level of authorization granted to the user.  Non-logged in users have an authorization level of 0; regular users have an authorization level of 1; superusers have an authorization level of 2.

public $language

The user's language.  Not currently in use.

public $avatar

The user's avatar image.

public function __construct()

The constructor function for this class.  Also checks if the user is attempting to log in or has a log in cookie and, if so, checks their credentials and calls the loginuser() function to register their information.

private function loginuser($userinfo,$loginhash = 0,$sessionhash = 0)

Sets the user information on the server end and client end.

public function showAvatar()

Displays the current user's avatar.

CC_Page

This class keeps track of information used to generate the current page, including the parts of the URL that determine which page is being shown, the page language, and the main module associated with the page.

public $id

The ID of the page.

public $title

The title of the page.

public $moduletype

The module type of the page's main module.

public $template

The template file used to display the page.  The filepath here refers to locations in the templates/ folder.

public $language

The language in which this page's text elements will be displayed on the user's end.

public $slug

The slug used to identify the page by URL.  For example, if the page's slug is "example-slug", and your website is at examplesite.com, the page will be located at examplesite.com/example-slug.

public $subslug 

Another slug used with some pages to indicate a specific view associated with that page, such as "archive" for a comic or blog archive, or "search" for a tag search.

public $searchterm

The search term if a search term is included in the page's URL.

public $pagenum 

The page number if the user is looking through a paginated comic or blog archive.

public $isindex 

A boolean specifying whether or not the page currently being requested is the index page.

public $module 

The main module object associated with this page.

public $galleryloaded

A boolean tracking whether a light gallery has been initialized on the page, in which case it will not be initialized again.

public $slugarr

An array generated from the parts of the URL that indicate which page is being requested.

public $description

The description meta tag information for this page.

public function __construct($urlstr,$end = "user")

This is the constructor function for the class.  It parses the page URL to determine what page should be displayed, and then fills in the page and module variables with information pulled from the database.

public function buildModule($slug)

This function builds a module object.  The module does not necessarily need to be the main module for the page.  This can be used to build modules and display them within other pages.

public function displayTitle()

This function determines how to display the page title as it would display in the tab or page header.  This includes removing a redundant title if the page title is the same as the site title.

public function displayMeta()

This function outputs the description meta tag for the page, using either the page's description information or the site's description information if the page's description information is empty.

CC_Module

This class holds information for the individual modules included in a given page.  This basic class is extended by four more classes specific to the type of module: CC_Comic, CC_Text, CC_Blog, and CC_Gallery. The base class contains some functions that are used in multiple module types.

public function getOptions($moduleinfo) 

This function pulls the option values for the module from the database and sets them in an $options array within the object.

public function getPageNav($numpages)

This function is used to display the navigation between archive and tag search pages for the blog and comic module types.

CC_Text

This class extends the CC_Module class.  This class is used for building modules used to display basic text pages and text areas.

public $id

The ID for the module.

public $name

The title of the module.

public $type

The type of the module.  This is always set to "text" for this module.

public $slug

The slug of the module. 

public $content

The text content of the module.  This is stored and displayed as plain HTML.

public $options

The options for the module.

public function __construct($moduleinfo)

The constructor function for the module.  Pulls the module information from the database and sets it within the constructed object.

public function display()

Displays the content of the text module.  If the module option to display the title is set to "yes", the title will also be displayed above the text module's content.

CC_Comic

This class extends the CC_Module class. This class is used for building modules used to display comics, along with their associated archives, news posts, and comment sections.

public $id

The ID for the module.

public $name

The title of the module.

public $type

The type of the module.  This is always set to "text" for this module.

public $slug

The slug of the module. 

public $options

The options for the module.

public function __construct($moduleinfo)

public function display()

Displays the current comic post based on CC_Page's URL information.

public function getPost($slug)

Retrieves the comic information from the database for a comic post with the given $slug.

public function getSeq($dir)

Retrieves the comic information from the database for the comic post in the sequential direction given with $dir. Acceptable values for $dir are "first","prev", "next", and "last".

public function getComic()

Retrieves the current comic information from the database based on CC_Page's URL information.

public function navDisplay()

Displays the comic navigation based on CC_Page's URL information.

public function displayAll()

Displays the news post for the comic and, if enabled in the module options, the comic's transcript, tags, and comments.

public function displayNews()

Displays the news post for the comic post.

public function displayTags()

Displays the tags for the comic post.

public function displayTranscript()

Displays the transcript for the comic post.

public function displayComments()

Displays the comments for the comic post.  Currently only allows Disqus comments.

public function displayDropdown()

Displays a dropdown with all the comic pages which navigates to the selected page on change.

public function displayChapters($dropdown = false,$current = false, $parent = false)

Displays the storylines of the comic in archive format, dependent on the archive options set in the comic's module options.

private function recurseChapters($tree,$dropdown,$current)

Recurses the storylines of the comic to display them in a tree format.

public function search()

Searches the module for tagged comics based on CC_Page's URL parameters.

CC_Blog

This class extends the CC_Module class. This class is used for building modules used to display blogs, along with their associated archives and comment sections.

public $id

The ID of the blog module.

public $name

The name of the blog.

public $type

The module type.  By default, this is set to "blog" for CC_Blog module objects.

public $options

An array of the module options.

public $browsing

A boolean indicating whether the blog is being displayed in browsing (multi-post) mode or single post mode.

public function __construct($moduleinfo,$subslug)

The constructor function for the module. Sets the basic variables of the object.

public function display()

Displays the blog module based on the URL information contained in the cc_page object.

public function recentPosts($num)

Displays $num number of recent blog posts.

public function displayTags($postid)

Displays the tags for the given blog post.

public function displayComments($post)

Display the comments for the given blog post.

public function displayPosts($posts)

Format and display a given array of posts.

public function getPost($slug)

Get the post information for the blog post with the given slug.

CC_Gallery

This class extends the CC_Module class.  This class is used for building modules used to display simple galleries and their corresponding descriptions.

public $id

The ID of the gallery module.

public $name

The name of the gallery module.

public $type

The module type.  By default, this is set to "gallery" for CC_Gallery module objects.

public $description

The gallery description displayed above the image thumbnails when the display() function is called.

public function __construct($moduleinfo)

The constructor function for the module. Sets the basic variables of the object.

public function display()

Displays the gallery.  Displays the gallery title if option is set, then the gallery description, then the gallery thumbnails, which each open a lightbox with a full size version of the image when clicked.

Database

The MySQL database for your ComicControl installation holds all non-file based data, such as comic information, module information, users, and blog information.  The follow tables are created upon installation. Their function and columns are described below. Each table has a prefix in the table name to designate the ComicControl installation, which you will choose on installation.  This allows for multiple ComicControl installations to use the same database

cc_prefix_blogs

This table holds the posts that are contained in any blog modules created in ComicControl.  Blogs do not have separate tables, but rather use their module IDs to distinguish between each different blog module's posts.

Columns:

id - primary unique ID for the blog post

blog - the module ID of the associated blog module

title - the blog post title

content - the blog post content in pure HTML

publishtime - the time the blog post was or will be published, formatted as a UNIX timestamp.

commentid - a unique ID used to identify the blog post to Disqus.

slug - the URL slug used to identify the blog post.

cc_prefix_blogs_tags

This table holds any tags associated with any blog posts across the ComicControl installation.

Columns:

id - primary unique ID for the tag

blog - the module ID of the associated blog module

blogid - the ID of the associated blog post

tag - the tag text

publishtime - the publication time of the associated blog post

cc_prefix_comics

This table holds the data for each comic added to the ComicControl installation.  Comic modules do not have individual tables, but are all collected in this table and associated to their module by the comic's module ID.

Columns:

id - primary unique ID for the comic post

comic - the module ID for the post's associated comic module

comichighres - the filename for the high resolution/original image uploaded for the comic post.

comicthumb - the filename for the thumbnail image for the comic post.

imgname - the filename for the default image displayed for the comic post.

publishtime - the publication time for the comic post, formatted as a UNIX timestamp.

title - the title of the comic post

newstitle - the title of the comic post's news information

newscontent - the HTML content of the comic post's news information

transcript - the transcript of the comic in HTML format

storyline - the ID of the comic post's associated storyline

commentid - a unique ID used to identify the comic post to Disqus

hovertext - the comic post's hovertext (text displayed on mouse hover)

slug - the URL slug for the comic post

width - the width of the highest resolution image associated with the comic post

height - the height of the highest resolution image associated with the comic post

mime - the MIME type of the comic image

contentwarning - content warning information for the comic post

altnext - an alternative link that clicking on the comic will lead to, if set

cc_prefix_comics_storyline

This table holds the data for each storyline added to the ComicControl installation.  These correspond to any chapters, volumes, books, sections, etc. your comics are divided into.

Columns:

id - the primary unique ID for the storyline

name - the storyline name

sorder - a number indicating the storyline's order within the comic.  Determines the order in which the storylines are displayed in archives.

comic - the ID of the associated comic module

parent - the ID of the storyline's parent storyline; for example, if the storyline is a chapter, the parent storyline is the book or volume it is in.  A parent of 0 means the storyline is top level.

level - the number of "parents" a storyline has.  Used for display purposes.

cc_prefix_comics_tags

This table holds the tags for all comic posts in the ComicControl installation.

Columns:

id - the primary unique ID for the tag

comic - the module ID of the associated comic module

comicid - the ID of the associated comic post

tag - the tag text

publishtime - the publication time of the associated comic post

cc_prefix_galleries

This table holds all the data for images contained in any gallery modules within the ComicControl installation.

Columns:

id - the primary unique ID for the image

gallery - the module ID for the associated gallery

imgname - the filename for the image

thumbname - the filename for the image thumbnail

caption - the caption for the image in HTML format

porder - the display order of the image within its gallery

cc_prefix_htaccess

This table holds the data used to build the .htaccess file for the root ComicControl directory.  Since ComicControl allows for additional htaccess directives to be added to its installation, it holds those extra directives along with its base content here so that the .htaccess file can be rebuilt on directive changes or upgrades.  Each row is designated to hold a specific piece of the .htaccess file: row 1 holds any prepended directives, row 2 holds any appended directives, and row 3 holds the standard .htaccess data ComicControl uses.

Columns:

id - the primary unique ID for this .htaccess segment

content - the content of this .htaccess segment

cc_prefix_images

This table holds the data for any images added to ComicControl's image library.

Columns:

id - the primary unique ID for the image

imgname - the filename for the image

thumbname - the filename of the image thumbnail

cc_prefix_languages

This table holds the data for languages available for the back end and front end of the ComicControl installation.  By default, only English is included. Additional languages can be added to this table if their corresponding files are added to the ComicControl installation.

Columns:

id - the primary unique ID for the language

shortname - the shortname used to identify the language's associated files

language - the full name of the language

scope - the scope in which this language is used, either admin for back end components or user for front end components.  

cc_prefix_modules

This table holds the identifying data for the modules added to the ComicControl installation.

Columns:

id - the primary unique ID for the module

title - the title of the module

moduletype - the module's type; either comic, text, gallery, or blog

slug - the URL slug identifying the module

language - the language that ComicControl-specific front end text for the module will be displayed in

template - the file location for the template used to display the module on its own

cc_prefix_modules_options

This table holds the option information for all the modules within ComicControl.

Columns:

id - the primary unique ID for the option

moduleid - the ID of the option's associated module

optionname - the name of the option used to identify its function

value - the value of the option

cc_prefix_options

This table holds the overall site options for the ComicControl installation.

Columns:

id - the primary unique ID for the option

optionname - the name of the option used to identify its function

value - the value of the option

cc_prefix_plugins

This table holds identifying information for any plugins added to ComicControl.

Columns:

id - the primary unique ID for the plugin

name - the full name of the plugin

filepath - the filepath for the main plugin settings or administration file within the plugins folder

slug - the URL slug for the plugin within the ComicControl backend

description - A description of the plugin

cc_prefix_sessions

This table holds on to data for user sessions that are currently active.  New logins create new sessions and old expired sessions are deleted. User cookies are compared against this data if their browser session is empty or expired.

Columns:

id - the primary unique ID for the session

userid - the ID of the user associated with the session

loginhash - a unique hash to compare against the user's cookies

loginexpire - the UNIX timestamp for that session's expiration time

cc_prefix_text

This table holds on to the HTML content of text modules within the ComicControl installation.

Columns:

id - the ID of the associated text module.

content - The HTML content of the text module.

cc_prefix_users

This table holds the data for ComicControl back end users.

Columns:

id - the primary unique ID for the user.

username - the user's username.

password - the hashed combination of the user's password and salt.

email - the user's e-mail address.

salt - a salt used to create the password hash.

resethash - a unique hash used to identify valid password reset requests.

resetsalt - a salt used to generate the unique password reset hash

authlevel - the user's level of authorization.  Level 2 users are superusers and can delete and add other users; level 1 users cannot.  Otherwise both levels of authorization have access to all parts of ComicControl.

avatar - The filename for the user's avatar if set.

Feedback

If you have any feedback on ComicControl's code or the information available here, please let us know by e-mailing feedback@comicctrl.com.  Please note that by sending suggestions, corrections, ideas, or any other form of feedback to us, you forfeit the right to claim copyright or ownership of that feedback or any code contained therein.