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.
Contents: Architecture | Classes & Functions | Database | Feedback
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 few basic templates are 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 information on the customization page 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 their own 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()
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
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
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 "comic" for this module.
public $slug
The slug of the module.
public $options
The options for the module.
public function __construct($moduleinfo)
The constructor function for the module. Sets the basic variables of the object.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 opening 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 multiple ComicControl installations to use the same database.
cc_
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_
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_
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_
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_
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_
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_
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_
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_
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_
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_
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_
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_
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_
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.