Warning Livedoc is no longer being updated and will be deprecated shortly. Please refer to https://documentation.tjhsst.edu.

TJ Website Editing Guide

From Livedoc - The Documentation Repository
Revision as of 16:13, 2 March 2010 by Andrew Hamilton (talk | contribs) (Added information on making large changes in new branches)
Jump to: navigation, search

File Organization

  • Anything put in the AFS filesystem appears on the website for existing domains. No webserver configuration for special directories is required.
  • All files now have a logical place in AFS, rather than some files being under /afs/csl/web/site, some others in /afs/csl/web/www, and other amounts of mess.
    • http://domain.tjhsst.edu/directory1/directory2/file.html translates into /afs/csl/web/domain/directory1/directory2/file.html. This is true for all main website documents, including main pages on the website that use the TJ theme.
    • The converse is NOT true: /afs/csl/web/directory does not mean directory.tjhsst.edu exists. Currently, this is only true for the user directory and the tjpf directory. If /afs/csl/web/domain does not exist, then some configuration will be required to setup the webserver.

Editing a Page

The Main TJ Website is now contained in a git repository. To edit a page, first you'll need to set up a personal staging area in your web-docs folder.

cd ~/web-docs
git clone /afs/csl.tjhsst.edu/web/staging
cd staging/includes/php
cp config-example.php config.php #Need to edit this to set the webroot variable
cp mysql-example.php mysql.php
cp mysqlrw-example.php mysqlrw.php

If you want your index page slideshow to work properly, you will need to copy the pictures over manually (since they are managed outside of git)

rsync -rv /afs/csl.tjhsst.edu/web/staging/show/images/ ~/web-docs/staging/show/images/

Now you have a complete sand-boxed copy of the website in which to make and test your changes. When you are ready to commit them, run git commit -a to commit your changes. You will be prompted for a commit message which should provide a useful summary of the changes you have made. If you are making lots of changes, you may want to break them up into a series of smaller commits to make the history more legible. To commit only certain files, use git add <filename> for each file you want to add and then run git commit (no -a) to commit just those changes. If you are adding a new file, you will need to use git add <filename> to tell git to track the file.

Once this has been done you can pull your changes into the main staging area by running git pull <username> master from within /afs/csl.tjhsst.edu/web/staging/. If git reports that <username> does not appear to be a repository, then you should add your repository to /afs/csl.tjhsst.edu/web/staging/.git/config (follow one of other existing entries, changing the username and path as appropriate). At this point you should test everything again to make sure that it plays nicely with any other changes that may have been made recently. You should then ask one of the Lead Admins or Mr. Washer to pull the changes into the main website (this may take a little while to happen, please be patient).

Large Edits

large rewrites of portions of the main website should generally be placed into a separate development branch in git while they are under development to avoid allow this development to take place in parallel with normal website maintenance. To create a new branch:

git branch <new branch name> #This will create a new branch
git branch #lists current branches
git checkout <branch name> #switches to the named branch
git push origin <branch name> #pushes a branch to the main staging area
#The following will set up a local copy of a branch that's in the staging area
git fetch origin
git branch --track <branch name> origin/<branch name>

To merge changes on this branch into staging (assuming the branch is called testing and already exists in both staging and your personal copy):

cd /afs/csl.tjhsst.edu/web/staging
git checkout testing
git pull <username> testing

OR

cd ~/web-docs/staging
git checkout testing
git push origin testing

Note that unless you are actively testing an alternate branch, it's a good idea to leave the master branch checked out in staging to minimize confusion.

Misc Notes

  • It's generally a good idea to run git pull origin master in your sandbox before starting to make changes to make sure that you have the most up-to-date copy of the code. This reduces the risk of merging conflicts as well as bugs due to unforseen conflicts with other code.
  • If you want to move or delete files, use git mv or git rm instead of just rm or mv; this will make sure that git interprets the changes properly. Otherwise, moves especially tend to be seen as deleting a page and adding a completely new page which is not what you want.
  • Links to pages that are part of the main website repository should almost certainly be prefixed with <?php echo $webroot; ?> or something similar; this is what makes the sandbox links stay there. Links to club websites should not be prefixed in this manner since the club sites are not cloned as part of the sandbox.
  • If you are making a new directory, you will probably want to symlink the main includes directory into the new directory (see the site for an example). The main header and other parts of the site currently rely on this symlink to function. Includes that are intended only for a specific part of the site should be put into an includes-local directory in the relevant portion of the site.

User Web-docs:

  • Only accessible via http://www.tjhsst.edu/~someuser, instead of being accessible from many different subdomains.
  • All users, excluding teachers and the legacy teacher webdocs directories, that have web-docs permissions are listed in /afs/csl/web/user/ (teachers and the legacy teacher webdocs directories automatically are given web-docs permissions, although the web-docs directory must still be created and given the proper access rights).

Granting web-docs permissions

  • The user must have a web-docs directory in the volume used above. This directory must give the AFS www-data user at least read (rl) access to the directory in order for the webserver to be able to read the data. The user's home directory must also give www-data at least list (l).
  • Once authorized as your /admin user, execute the following command: fs mkmount -vol volume -dir username in the /afs/csl/web/user.temp directory, where volume is the name of the user's home directory volume. An easy way to find the volume name is by using "fs lq" in the user's home directory. For new student home directories, this is currently in the form year.username.

Removing web-docs permissions

  • Once authorized as your /admin user, execute the following command: fs rmmount username in the /afs/csl/web/user/ directory.

Banning a user

Banning a user will show the banned error page, instead of showing the 404 error page.

  1. Remove permissions, as shown above.
  2. Add a line in /etc/apache2/conf.d/macros on the webserver in the StandardUserDir macro, following the example given in the comments.

Themes

The website can be themed! Have a new idea to try, or want a few changes in the design? This can all be done in one place under /afs/csl/web/media/themes/. The current theme is selected by changing the current symbolic link, which is why it is necessary to use current in the include paths mentioned above in creating a document. A printer-friendly page, a part of the current theme, is automatically used when printing any portion of the website that uses the TJ theme.

Legacy webdocs

Right now, these sites are housed under /afs/csl/web/webdocs_legacy/. This should change in the future. These directories are left over from the old Novell webserver.

Previous TJ Websites

A copy of the previous TJ website can be found at http://web1.tjhsst.edu/

A copy of an even older TJ website can be found at http://oldsite.tjhsst.edu/