Installation

Contents

Requirements

The following programs and modules are required to run The State Decoded, in addition to a basic LAMP/WAMP stack (MySQL 5+, PHP 5.4+, Apache 2+). Nearly all of these are almost certainly already installed and configured properly on any standard server. The exception is on Amazon’s EC2 and other stripped-down cloud servers. The State Decoded’s installer will automatically check to see whether these are installed and running, and alert you to any problems.

Instead of the built-in text search engine, you may use the more advanced Solr search engine. This provides many enhancements over the default engine, but can be difficult to setup and configure.

You must use Apache Solr 4.3 or newer.

In most cases this rules out any system package installations (via yum, yast2, apt-get, etc.), which are all older versions.

Simply download Solr to your server, and in the example/ directory, run java -jar start.jar -Dsolr.solr.home=/var/www/example.com/solr_home/, replacing /var/www/example.com/solr_home/ with the actual path to the solr_home directory, which is provided as part of the State Decoded download.

Note the port number on which Solr is running. This is 8080 by default, but some Linux distributions (e.g., Ubuntu) will set it to 8983 instead. If it isn’t 8080, then you’ll need to modify SOLR_URL in config.inc.php to reflect that different port number.

Custom method: Modify class.[Statename].inc.php—specifically Parser::iterate, Parser::parse, and Parser::store—to support the legal code that you will be importing. See “How the Parser Works” for details.

Load http://example.com/admin/ in your browser and follow the prompts in the “Import Data” section. Wait while the parser runs, which could require anywhere from 5-60 minutes to run, depending on the power of your server and the length of your legal code. This is iterating through the XML, loading it into the database, and creating the website. When the is parser finished, you have a complete site for your legal code at http://example.com/.

If you do not sign up for Typekit, the site will work perfectly well. It simply won’t look as nice as it otherwise would.

Custom functions

Within the State class, in class.[Statename].inc.php, there exist several methods, commented out, that can be written for your specific implementation, to provide additional functionality on your site. To implement these, it is only necessary to write the methods—all of the glue is already in place to include their output within the law object, return the data via the API, and display it on the law pages.

This class can also be used to house additional functionality not envisioned within The State Decoded.

Official URL

Method official_url(). Turns a law’s section number into the URL for the law on its official government website. For example, 10-2.301.4 might become http://example.gov/laws/10-2.301.4/. This URL will be provided on the sidebar of every law page and within the API’s law method.

Translate history

Method translate_history(). Turns a law’s history text into a plain-English version of the same text. For example, Code 1950, c. 118; 1972, c. 825 might become:

This law was first codified in 1950, as recorded in chapter 118 of the Acts of Assembly, and was amended in 1972, by chapter 825.

The translated history will be displayed after each law on the law page, and will be provided within the API’s law method.

Citations

Method citations(). Turns a law’s section number and history into one or more citation methods. For example, it might turn a law’s section number (10-2.301.4) and the most recent year in which that law was amended (1997) into Ne. Code § 10-2.301.4 (1997). All created citation methods will be displayed in the sidebar of the law page and within the API’s law method.

Definition parsing

Within class.[Statename].inc.php, the extract_definitions() method does its best to determine the scope of definitions. “Scope” is how broadly that a term is to be defined. Some terms are defined only for the purpose of a single law:

As used in this section, unless the context requires a different meaning:

“Costs” means the reasonable and customary charges for goods and services incurred or to be incurred in major information technology projects.

Others might be defined for an entire structural unit—a chapter, title, part, or other named structural unit. And still others might be global, defined for the entire legal code. Every legal code has its own terminology, and many are inconsistent in how a definition’s scope is described. “As used in this chapter,” “for the purpose of this chapter,” and “for purposes of this chapter” are all viable phrases indicating scope. These candidate phrases are stored in the $scope_indicators array. The scope of a list of definitions is gathered from the first paragraph in that list.

Then there are the phrases that indicate an actual definition:

“mean”

“means”

“shall include”

“includes”

“has the same meaning as”

“shall be construed”

“shall also be construed to mean”

These are all terms that can connect a defined term to its definition. These are stored in the $linking_phrases array. If your legal code uses different terminology, you need only add its linking phrases to the list.

Finally, the terms themselves are located based on the presence of quotation marks. (Either straight quotation marks—U+0022 in Unicode—or angled double quotation marks—U+201C and U+201D in Unicode.) If the terms within your legal code are not stored within double quotation marks, then extract_definitions() will need to be modified to be able to isolate those terms, such as locating them within <em></em> tags. For those rare legal codes that do not offset defined terms in any way (italics, quotation marks, or otherwise; e.g., Nebraska), modifications to the code will be necessary in order to isolate the term being defined.

The State Decoded does its best to allow for the many terms and phrases employed by different legal codes, but this may need to be tuned to accommodate the legal code that you are parsing. Survey how it indicates the scope of definitions, and how it connects a term to its definition, and modify extract_definitions() to suit those circumstances.

Varnish caching

If you are running a Varnish server, and you want The State Decoded to automatically purge expired content, provide the URL for the Varnish server as the value of VARNISH_HOST within config.inc.php. Make sure that your Varnish VCLsupports a BAN.

Autolinking cross-references

Many legal codes use coherent, compact, unique citation methods, assigning every law an identifier that is never used elsewhere. With the regular expression in the config file (SECTION_PCRE), The State Decoded can identify all cross-references and turn these into links. But for those legal codes that do not use these identifiers, some custom autolinking code will need to be written.

The first step to doing this is to copy the replace_sections() method found within includes/class.Autolinker.inc.php and paste it into your class.[Statename].inc.php file, within a State_Autolinker class, like such:

The function of the existing replace_sections() method is to process a single match from SECTION_REGEX. Normally this is as simple as return '<a class="law" href="/'.$match.'/">'.$match.'</a>';, because the section number is the same as the URL slug. But for something like, say, the Maryland Code’s citations, it’s necessary to be able to generate a URL for “§ 9-301 of the State Government Article” (say, sg-9-301). That might mean maintaining a lookup table within replace_sections() to turn every article name (“State government Article”) into a URL prefix (“sg-“). Methods will vary between legal codes.