GithubHelp home page GithubHelp logo

craftcms / docs Goto Github PK

View Code? Open in Web Editor NEW
37.0 8.0 144.0 186.21 MB

Documentation for Craft CMS, Craft Commerce, and other official products.

Home Page: https://craftcms.com/docs

JavaScript 100.00%
vuepress documentation craftcms

docs's Introduction

Craft Docs

This project includes all project documentation and tutorials at craftcms.com/docs. It does not include class reference documentation.

It consists of markdown content in nested docs/ folders, and a highly customized VuePress theme in docs/.vuepress/. The theme is comprised of single-file Vue components just like the VuePress default, but integrates PostCSS with Tailwind CSS to replace most of the Stylus used by VuePress.

Overview

The major change in this theme is the concept of documentation “sets”, meant to define a documentation “product” that may have one or several versions. Each can be configured as a “primary set,” meaning it appears as a top-level sidebar item. Navigation and search are unique to each set, sort of like the VuePress equivalent of Craft’s multi-site functionality.

The only content not part of a docset is the homepage at docs/README.md.

The pages served from docs/ are treated like any other VuePress project, and the theme modifies resolvers so any displayed content is assumed to be part of an active set once selected.

  • docs/
    • .vuepress/
      • public/ for static files to be published with the build.
      • sets/ for our docset configurations.
      • theme/ all the JavaScript, Vue, PostCSS and Stylus for the custom VuePress theme.
      • anchor-prefixes.js: configuration for abbreviated link shortcuts like yii2: and craft3:.
      • config.js is the root VuePress configuration.
      • head.js for customizing global <head> contents for published pages.
      • placeholders.js for configuring special placeholders to be emphasized in code samples.
    • */ docset Markdown as you’d see it on its own in each legacy VuePress project.
    • README.md the topmost homepage for all docsets.
  • postcss.config.js
  • tailwind.config.js

Local Development

npm install
npm run docs:dev

Quit the process and re-run if you’ve made changes to any .js config files.

Writing Tips

Most stock VuePress Markdown extensions are supported here. See the Markdown Extensions page to learn more about linking, frontmatter, and highlighting lines in code samples.

  • Keep code block line lengths up to 85 characters long to avoid horizontal scrollbars.
  • Avoid placing highlighted code blocks ::: details toggles because the performance is terrible in WebKit. Use our height-limited <toggle-tip> component instead.

docs's People

Contributors

ademers avatar akshayagarwal avatar andris-sevcenko avatar angrybrad avatar augustmiller avatar bencroker avatar benface avatar billythekid avatar brandonkelly avatar carlcs avatar dependabot[bot] avatar dreamseeker avatar gtettelaar avatar jamesedmonston avatar janhenckens avatar jasonmccallister avatar leevigraham avatar lindseydiloreto avatar lukeholder avatar makeilalundy avatar mattstein avatar missmatsuko avatar nfourtythree avatar olivierbon avatar samhernandez avatar shinybrad avatar snyk-bot avatar timkelty avatar vnali avatar xhmikosr avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

docs's Issues

Improve “Entries”

I have a suggestion for https://craftcms.com/docs/3.x/entries.html

The feedback is actually for the overall documentation site. It would be great if the search bar can be fixed at the top so that even if I am reading something near the bottom of the page, I can press / and search the site from there.

[FR] Ability to post base64 images

Description

Sometimes we want to upload an image without using input type="file". Base64 encoding is a reasonably common format and can be set as an input's value without much trouble.

Document Element::isFieldEmpty usage

Started: craftcms/cms#5300

I would like to see isFieldEmpty (Element::isFieldEmpty, entry.isFieldEmpty('myField'), et. al.) documented as a valid way to check a field for empty regardless of the fieldtype.

It looks like Craft uses this internally for required validation, but can be useful in other contexts as well.

In my use-case, I'm mapping a set of element fields, but don't care about the actual field output data, only if it has any.

Seems like the right thing to use, but I'm wary of relying on it without anything in the docs.

user.can('editEntries:[SectionID]') vs user.can('editEntries:[SectionUID]')

Description

Heads up: this might be a long one, and I may very well be wrong. So please use a healthy dose of scepticism :)

I'm working on upgrading a site from craft 2 to 3 and ran into an issue with currentUser.can(). According to this page, in order to check if the user can edit entries in a section (which is what I'm using as a means of checking if the current user should be able to access the current page) I should be using currentUser.can('editEntries:[SectionID]'). However this returns false to me eventhough the current user has that permission.

After some digging, including outputting this:
<pre>{{ dump(craft.app.userPermissions.getPermissionsByUserId(currentUser.id)) }}</pre>
I looked at the source code. The .can(string $permission) pretty much just passes it on to Craft::$app->getUserPermissions()->doesUserHavePermission($this->id, $permission). This function simply checks if the lowercase $permission is in the array of the above dump.

But here's the kicker, that function getPermissionsByUserId() has those permission with uid instead of id. Thus if I follow the documentation, I will never get the right response.

I think either the documentation is wrong or at some point the .can() function had a transform from id to uid removed (as I'm pretty sure it did work in craft 2). I do think it's waaay more convenient to use id, but if the .can() function is wrong it seems like a big deal and I imagine someone should have run into this issue long ago. (which is why I'm sceptical of my find)

Steps to reproduce

I could give steps to get to a point that should be correct according to the doc, but isn't. But think my write-up above covers it?

Additional info

  • Craft version: 3.3.14
  • PHP version: 7.1.33
  • Database driver & version: MySQL 5.5.64

Craft Guides: Add guide for using live preview across multiple domains

Description

CraftCMS introduced a new featured in 3.1 to enable the ability for live preview to work on multi site setups when previewing entries that reside on other domains (in addition to the CP domain). Other than the linked guide below (specifically mentioning config for multiple sub domains), there is no documentation to explain what needs to be setup to enable this new feature. The guide should be amended to include this information.

https://craftcms.com/guides/using-live-preview-across-multiple-subdomains

Create section dedicated to the CP UI

As a plugin developer I want to make sure my plugins match Crafts UI as closely as possible.

To make this a better UX it would be great if the docs included a UI style guide section which described markup and classes. Currently I'm reverse engineering components by looking at the twig source templates.

I fear that with craft3 and the plugin store everyone will start using custom UI's and we'll end up with inconsistent experiences.

The main customisation I've needed so far is nested fieldsets. Here's how I handled it in a plugin I'm currently working on. I had to customise the labels of the "sub" fields and create a container.

image

Restructure 'Extending Craft' pages

The current page structure for plugin/module extension is confusing for someone who never worked with Craft2 and only cares about extending Craft3.

Referencing: https://docs.craftcms.com/v3/extend/updating-plugins.html

A lot of the important Craft3 extension information is under 'Updating Plugins for Craft 3' and the content references both v2 and v3. This assumes you know v2 and are migrating to v3. This made sense when v3 launched, but a new Craft3 dev today should be able to learn v3 without seeing anything about v2.

Recommendations:

  • Leave the existing pages in place to help people migrate to v3.
  • Copy the whole 'Updating Plugins for Craft 3' section as a new top-level 'Core Concepts' item, remove references to v2, and add content for anything not covered for v3.

Getting phpdotenv also into Craft 2 -> Craft 3 upgrades, plus hopeful adds

Doc is missing in the section for these conversions,, but it's easy to provide, thus allowing all Craft 3 sites to take advantage of the better security possible, and be consistent when addressed in future.

Think what would be useful in the initial Updating Craft CMS section of upgrade.md is:

  • insert an step after 4) and similar to it, with this instruction. At present it will result in a tag of ^2.40, which should provide for future.

    compoaer require vlucas/phpdotenv

  • In the step which now becomes 6), replace the index.php code substitution with something like this. Note that the phpdotenv call has added protection, in case the composer step hadn't been done or succeeded, or was lost.

<?php

// Project root path
$root = dirname(__DIR__);

// Load and run Craft
define('CRAFT_BASE_PATH', $root.'/craft');
require_once $root.'/vendor/autoload.php';

// dotenv?
if (file_exists($root.'/.env')
  && file_exists($root.'/vendor/vlucas/phpdotenv')) {
    $dotenv = new Dotenv\Dotenv($root);
    $dotenv->load();
}

$app = require $root.'/vendor/craftcms/cms/bootstrap/web.php';
$app->run();
  • You could quite usefully add a further paragraph in this area, quite possibly a new step (now) 9) and after 'success and delete app', explaining how the converted site will continue to use the present db.php and general.php, while possibly needing some modifications, leading to the following Configuration section

  • In that Configuration section, then it's easy to say that you may want to move forward to putting security items like passwords into .env, because now you can.

  • similarly, it could be quite informative to flesh out the rather misssable Asset Volume Settings section (bigger heading type there?) with a note that you can use .env entries to fill in the per-deployment-site differing values for ASSET_BASE_PATH and ASSET_BASE_URL in volumes.php.

  • last point is that problems with old Redactor configs could usefully be a bit better explained in the Redactor configs section. I would follow your specifics with a short paragraph saying 1) in fact old Redator configs often don't follow these rules, by not quoting all values, and by using the wrong quote character otherwise, so you will have to edit them if Craft shows an on Rich Text fields, and 2) that http://jsonlint.com/ can be very useful in assuring you've made all the corrections.

  • well, one more. It's likely to be helpful to add a now 10) item to the initial Updating Craft CMS section, suggesting to Clear Caches all nder the new Utilities menu, before beginning to try out the converted site. I've had some very misleading problems occur on conversion, until doing this, something easily overlooked but obviously of need for sites that have run before, when you think about it.

Update the plugin tutorial

The tutorial on how to build plugins is great, but on the page about creating a settings page you forgot to mention that the composer.json file has to set:

"hasCpSettings": true,
"hasCpSection": true,

to make the settings "link" show up in the cp.

probs on two aspects of Twig getUrlFormat

  • In converting a Craft 2 site, I got a stack trace on section.getUrlFormat(), which doesn't any longer exist. There isn't any upgrade doc apparent about replacing this, which from source looks likely to need to involve both getSiteSettings and Sites. It didn't just fall out how to do it.

  • Not having the time at the moment to debug the Twig, I'm instead going to just replace the area with a better overall method already created for what I'm building there, which is a kind of automated menu, but someone else is likely to want to find doc for this.

  • in perusing for the problem, I came across a like-named craft.request.getUrlFormat(), in upgrade.md, which looks incorrect in referring to craft.app.config.usePathInfo as a replacement, not so?

[Feature Request] add dark/light mode toggle

Description

Right now the theme honors your browser/system setting for prefers-color-scheme, but it’d be nice to allow the visitor to optionally override that with an on-page control.

Tell devs to run the CLI command for setting up tests

The 'Getting Started' page for testing is a lot of creating folders, creating files, and copying code.

It'd be simpler and less room for error if you tell devs to run the CLI command ./craft tests/setup and then call out specific files they need to manually update. You could then remove the manual steps completely and just give a high-level overview of the folder structure.

Referencing: https://docs.craftcms.com/v3/testing/testing-craft/getting-started.html

Frustrating documentation for controllers

docs/extend/controllers.md

After an hour of debugging I figured out that accessing custom controllers in Craft seem to require the first slug to be /action/.

I would be great if the documentation mentioned this.

Add documentation and update notes for Models, Records and Controllers

The Craft 2 plugin development documentation included information about Models, Records and Controllers which is no longer contained at all in the Craft 3 docs.

The current upgrade guide only mentions a very vague reference back to the Yii documentation for all of these concepts, without any specific instruction on how to port plugins that used them in Craft 2:

See its comprehensive upgrade guide to learn about how things have changed under the hood.

Considering the big changes (e.g. using actual PHP attributes instead of defineAttributes() on models), this really hinders efforts to migrate plugins to Craft 3. It also led me to believe that Models and Records were no longer supported classes for Craft 3 plugins, until I delved into official P&T plugins like Digital Products to notice that they are indeed still used! This has us piecing up classes from the Craft 2 docs, Yii 2 upgrade docs, and reverse engineering... Far from ideal.

Here's the current table of core classes that are documented, which I'm making partly for myself to keep navigate through the upgrade process...

Craft 2 Craft 3 Craft Update Notes Yii Update Notes
Models Missing Missing Models
Records Missing DB Queries Active Record
Controllers Missing (Multiple) Controllers
Element Actions Element Actions Missing N/A
Dashboard Widgets Widget Types Missing N/A
Field Types Field Types Components N/A
Services Services Missing N/A
Template Variables Extending Twig Template Variables N/A

Is there an update planned for the core Models/Records/Controllers documentation, along with examples of how to create and use them in Craft 3?

Update docs to walk through creation of sections

The docs for 3 are lacking in specific instructions and examples around creating new sections. For me it is mostly fine but for a new user it would be super confusing. Should step through each part in the process with screenshots.

SVG Deprecation Warnings in 3.5.0 conflicts with documentation

Description

In the CP deprecation warnings I see this:

The class argument of the svg() Twig function has been deprecated. The |attr filter should be used instead.

However when visiting the docs for the svg function the example is this:

{{ svg('@webroot/icons/lemon.svg', class='lemon-icon') }}

with no reference of how to use the |attr filter

Steps to reproduce

  1. use an SVG function in your code according to the documentation
    2.get deprecation errors based on that svg function

Additional info

  • Craft version: 3.5.0
  • PHP version:
  • Database driver & version:
  • Plugins & versions:

Best practices for avoiding frequent request/response console bugs

A seemingly very common bug is for devs to rely on request/response props and methods that are available in a web app context, but not in a console one.

Especially with the queue, devs may not realize that their code needs to be able to run as web OR console.

So, one generally needs to sprinkle a bunch of getIsConsoleRequest conditionals around.

Is there a better solution here?

The bug is understandable, as things may work fine for the dev when testing if they are not running their queue from console.

Examples:

Upgrades v.s. updates inconsistency

Hi ya'll!

Just noticed a little naming inconsistency. I stumbled upon the "Should we update to Craft 3" page (https://craftcms.com/guides/should-we-update-to-craft-3), where a little Update vs. Upgrade section is dedicated to the fact that 'update' is the preferred term.

This 'Update v.s. Upgrade' terminology isn't really consistently applied to the actual update guide: https://docs.craftcms.com/v3/upgrade.html#performing-the-upgrade -- As "Upgrade" seems to be the word of choice there.

I know, nothing much to worry about -- And certainly not stopping me from doing my job.
Thought I'd point it out, for the sake of consistency! 🙃

Element Saving for Drafts, Revisions, Multi-Site need documentation for Plugin Development

Since the move to make Drafts and Revisions Elements, it has been increasingly confusing for the number of scenarios custom Elements and Field Types need to support (measured by bug reports, time spent on client Yii modules dealing with Elements/Field Types, and curse words). In most cases, I think the solution is easier than I'm making it but the lack of documentation on how to even think about the problem makes it challenging to even know if you're considering all the possible scenarios for Drafts, Revisions, and Multi-Site.

Using X-Debug to troubleshoot is a challenge too as even if you are trying to just watch a single method involved in the save behavior the code ends up hitting that method countless times for things like auto-save, SCENARIO_ESSENTIALS, SCENARIO_LIVE, drafts, revisions, multi-site propagation, and more. Throw in a few variations on the Element settings or different Translation Methods and you have even more scenarios to make sense of as you try to figure out a simple question such as what is a reliable condition I can use to make sure I only trigger something when an Element is saved in the Live Scenario for the first time?, which should not be a complicated question to answer. It is. Or at least feels like it.

To illustrate my confusion here's a spreadsheet I made while trying to figure out how to save a custom field type with a separate data table:
https://share.barrelstrength.co/YEu1nwBK

The spreadsheet is trying to make sense of the number of different times Elements were saving in 6 different scenarios, which each save Elements multiple times.

  • Create a New Entry 
  • Update Existing Entry 
  • Save as Draft
  • Auto-save Draft
  • Convert Draft to Entry 
  • Convert Revision to Entry

This doesn't even get into examples of Elements saving for Multi-site or scenarios where Element saves get triggered from the console, queue, migrations, or failed validation.


Ideal documentation would identify (and give us a checklist for) ALL of the different scenarios we need to plan for, give us a framework on how to think about the problem (at least for custom Elements and Field Types), and clearly show an example of how our code can identify each scenario.

[Feature Request] Improve documentation for custom elements

Description

I've had to make a few custom elements on a couple projects recently and the experience wasn't the best. The documentation points you in the right direction but basically stops and says copy one of Crafts existing elements.

It would be great if a simple element could be created more quickly either with better documentation e.g. actual examples or some kind of CLI tool.

Even if the docs are for a really simple element e.g. form submissions.

Document the DOM PDF version requirements

Description

Craft Commerce requires PHP 7.0 or greater (just like Craft CMS).

The default craft project composer.json sets the platform to 7.0 https://github.com/craftcms/craft/blob/master/composer.json#L36

This platform requirement in the project will favour dependancies that are compatible with 7.0

In Commerce we require dompdf/dompdf ^0.8.3 which runs fine on PHP 7.0

If you run your project on PHP 7.4 and have dompdf 0.8.3 installed, you will get errors.

dompdf 0.8.4+ requires PHP 7.1 but these versions will not be installed due to your projects composer.json platform requirement.

Bottom line, if you are running PHP 7.4 update your projects platform to 7.4 (or 7.1 or greater) and do a composer update and dompdf will be upgraded to 0.8.4+ and work again.

@mattstein please ask me questions if the above is not clear. Probably best in the upgrade & requirements docs pages.

Intro to using services via `craft.app` in templates

It’s currently hard to find info about very common API methods, things like

{% set segments = craft.app.request.getSegments() %}

I know it’s not practicable to duplicate all docs from the Class Reference into documentation articles, but I think there should be something in the Craft 3 Documentation to guide new Craft users. Maybe it would already help to have an intro article in the “Templating” section, with links pointing to the Class Reference pages for common service APIs? Maybe enrich it with some Twig example code?

Please change the highlight colour to be visible

Love the new dark mode docs, but I can't see whether I've selected anything from the code examples. Could you please update that to something visible?

Example of text not selected:

image

Example of a highlighted selection:
image

Probably depends on the monitor settings slightly, but I can't see it at all on at least two of my screens, which makes it very difficult to select and copy code / variables. Thanks!

Add a worked out example of naming compound Elements'

Most people who use Craft/Yii's query builders are going to end up on Entry's doorstep -- perhaps beginning with Entry::find();

It would be very good to have a worked out example of how this works when wanting to sort, for currrent Slack question example, using orderBy() on a column. You can't use an alias for the table involved, so the tablename itself must be used, which I couldn't rapidly lay on hands for an example that this is correct, last night. But it is, except many won't have my foggy long memory of possibilities on such things.

This would be a great place also to explain just what the Entry structure is, so that the joins behind it are understood in principle, if not necessarily in detail -- hence the table names that would be used for various columns.

Nested permissions syntax missing

This page shows how to define nested permissions but doesn't have information on how to check for them.

https://docs.craftcms.com/v3/extend/user-permissions.html

eg. for this example

'permissionName' => [
    'label' => 'Permission Label',
    'nested' => [
        'nestedPermissionName' => [
            'label' => 'Nested Permission Label',
        ],
    ],
];

its not clear which of the following is correct (if any)

$user->can('nestedPermissionName');
$user->can('permissionName.nestedPermissionName');
$user->can('permissionName/nestedPermissionName');

Versioning/Updated Dash docsets

Currently Dash has Craft docsets as part of the main docset library, but they are not currently up to date (latest v2 is 2.6 and latest v3 is 3.1).

There's probably no blocker for getting 2.7 in there via the v2 branch considering it is only receiving security updates now, but there are no dedicated branches or tags for this repo that allow for delineation between 3.2/3.3/3.4. Is this something that could be considered?

@Kapeli Is there anything else that would be required for updated Craft docsets?

Upgrading from Craft 2: Modifying plugin handle

I'm just querying this for sanity reasons. From a Craft 2 to 3 migration, I don't seem to have the settings column on the craft_plugins table.

The example for modifying a Craft 2 plugin handle reference the settings columns below, but it doesn't seem to exist:

https://docs.craftcms.com/v3/extend/updating-plugins.html#writing-an-upgrade-migration

For updating the handle, the settings column isn't needed anyway, but I'm just wanting to clarify this, if the craft_plugins DB table should have a settings column anymore?

RelatedTo - use proper syntax for "and" relations.

https://craftcms.com/docs/3.x/relations.html#simple-relationships

Here's how and usage is described in code example:

{% set relatedDrinks = craft.entries()
    .section('drinks')
    .relatedTo([ 'and', gin, lime ])
    .all() %}

It turns out however that in order for it to work correctly, such syntax needs to be used - at least with php:

$query->relatedTo(['and', ['element' => gin], ['element' => lime]])

Using syntax below in php, causes array_merge(): Argument #2 is not an array error:

$query->relatedTo(['and', gin, lime])

Feature request: documentation for multisite server config on Nginx etc

I know it's impossible to cover every stack/scenario — but some basic documentation on configuring the most typical server setups for Craft multisite would be hugely appreciated.

(I've just spent more than an entire day getting multisite working via Nginx on a Forge-provisioned VPS and have almost cracked it now, but am sure other people would welcome this too).

useful info for craft\db

Here's a description of what happens and what to do, from Slack posting. Would be nice if could be edited into coming doc...

a little tip for the unwary: if you're connecting to an external database such as mssql, don't use craft\db\Connection (or craft\db\Exception). You'll miss getting proper messages for a failed connection, even just server down.

I had the driver and connection fully working, save for server down, and thought it was a driver issue. But actually it's Craft's db code, and its handling if it doesn't recognize the database/driver type -- says simply unsupported connection type, and mentions the driver.

The real messages from the dblib driver are nicely enough detailed -- using yii\db\Connection (subclassed), and yii\db\Exception.

Write a step by step tutorial how to build a plugin

Hi,

I just tried to write my first plugin for craft3 but found it quite hard to bring all peaces together. Before I write a plugin I have to get pieces from three different places right now:

  • Yii docs
  • Craft 3 Class Reference
  • Craft 3 docs und somehow also Craft 2 Docs as the 3 docs don't look complete

But there is still a example missing, how everything works together. I remember how I got into meteor.js which has now quite great tutorials to start by creating a app step by step.

So it would be great to have such a thing for plugins in craft 3 which does the following things:
Writing a plugin with a twig extension, settings in the config, some settings should be also changable in the CP, accessing a Service through craft.myplugin.*, basic error handling/logging, getting input values from the website and writing the data to a custom database table and displaying it again on the website. So basic routing is also included.

Maybe the classical TODO app would be good to way to do by it or similar. But such a tutorial/guide mix is definitely missing but would dramatically improve the learning curve.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.