Welcome to the Cookbook

loading...

Contributing to The CookBook

The CookBook depends on contributions from people just like you. This application was designed to allow anybody to recommend and add changes as necessary. If you're new to CakePHP you can make a difference and are one of the best people to suggest a change to the docs. Submissions are reviewed by members of the documentation team for consistency, accuracy and wording.

Before you dive in and rewrite the book though, there are some notes and guidelines to keep in mind:

  • Be succinct. People are looking for answers quickly and don't want to read large blocks of text to get to the answer.
  • You can submit plain text (paragraphs), it will be html formatted automatically
  • Chunk your content. Break up your content to make it easier to scan. Use sub-sections, code blocks, lists, and tables appropriately.
  • Wrap inline code with <code> tags. Don't use quotes around the code. For example, "The <code>$uses</code> variable specifies which models to use."
  • Wrap code blocks with <pre> tags. For example:
        <pre>
	$this->functionName();
	$this->otherFunctionName();
    </pre>

    It's not necessary to escape pre contents

  • File and URL paths should be wrapped in <kbd> tags.
  • Use example.com when a generic domain name needs to be referenced. Its purpose is to be generic and will never be linked to a spam or porn site. (see RFC 2606)
  • Links to other resources in the book should be without the domain. Eg. /view/181/built-in-helpers
  • Code examples should conform to CakePHP Coding Standards.
  • Use predefined classes method, warning and note.
  • And finally: Check the preview! If it doesn't look right to you - it won't look right when it's reviewed.

# Special CSS Classes

There are certain elements that can be given special attention. These require a special class attribute to be applied to the element.

# Warning

Warnings should be used to let the user know about something that is important such as indicating that a method or property is deprecated. It could also be used to point out where certain usage might create adverse effects.

Example:

This method has been deprecated. Please use methodName.

<p class="warning">This method has been deprecated. Please use <a href="#">methodName</a>.</p>
  1. <p class="warning">This method has been deprecated. Please use <a href="#">methodName</a>.</p>

Alternatively, if you have a warning that spans across multiple block elements then use a DIV to wrap all elements.

Example:

This approach may create serious performance degradation. Consider alternative approaches:

  • Approach A
  • Approach B
<div class="warning">
   <p>This approach may create serious performance degradation. Consider alternative approaches:</p>
   <ul>
      <li>Approach A</li>
      <li>Approach B</li>
   </ul>
</div>
  1. <div class="warning">
  2. <p>This approach may create serious performance degradation. Consider alternative approaches:</p>
  3. <ul>
  4. <li>Approach A</li>
  5. <li>Approach B</li>
  6. </ul>
  7. </div>

# Note

A note can be used to highlight information that a reader should know or be aware of when developing their application.

Example:

You can add conditions to any of the methods to narrow down your results.

<p class="note">You can add conditions to any of the methods to narrow down your results.</p>
  1. <p class="note">You can add conditions to any of the methods to narrow down your results.</p>

A note that needs to span across multiple block elements should use a DIV that wraps all elements. See the previous section for example.

# Method

The method class should be used to wrap the method statement, parameters, and return value. The class is only applied to a single paragraph element.

Example:

string render (array $options = array())

<p class="method">
   <code>string render (array $options = array())</code>
</p>
  1. <p class="method">
  2. <code>string render (array $options = array())</code>
  3. </p>

# Code and pre tags

Pre tags are assumed to contain php code unless otherwise specified

There are however other classes which can be used for pre tags specifcally:

plain for plain text. I.e. entering:

<pre class="plain">
Plain text
With self entered carriage return
</pre>

Gives:

Plain text
With self entered carriage return

shell for shell commands. I.e. entering:

<pre class="shell">
$ cake bake shell code
</pre>

Gives:

$ cake bake shell code

# Translating Cookbook's fixed texts

The cookbook's fixed texts are stored in the application itself, and are not editable via the website. If you'd like to, for example, change the text for a menu item for your language - find the po file in the source repository fork the cakebook project, make your changes and let someone know in #cakephp-docs so that your changes can be pulled into the main repository.

Stub - update me

# Translating

If a section of the book hasn't been translated into your language yet it will appear in English. The CookBook relies on submissions from users just like you to share and add to the information accumulated here. See Contributing to the CookBook for general guidelines on submissions.

Stub - add notes regarding sync markers

« How to help | General »